go.dedis.ch/onet/v3@v3.2.11-0.20210930124529-e36530bca7ef/tracing/README.md (about)

     1  # Tracing in Onet
     2  
     3  ## TLDR
     4  
     5  Import the tracing service:
     6  
     7  ```
     8  import _ go.dedis.ch/onet/v3/tracing/service
     9  ```
    10  
    11  Sign up on https://honeycomb.io and get an API key.
    12  Create a dataset on honeycomb.io.
    13  Run your binary like this:
    14  
    15  ```
    16  HONEYCOMB_API_KEY=api_key:dataset ./conode
    17  ```
    18  
    19  Start tracing!
    20  
    21  ## Why
    22  
    23  While logging is quite important in setting up and running a system, it has
    24   its limits:
    25  - it gets garbled when multiple nodes run at the same time
    26  - only prepared messages can be seen
    27  - difficult to filter and chose which messages are printed
    28  
    29  This is why tracing exists, which I learnt from Charity Majors:
    30   https://twitter.com/mipsytipsy
    31  With her great name, good writing style, calling out people while still
    32   listening to suggestions, she convinced me that tracing is needed, not only
    33   logging, monitoring, ..., but tracing.
    34  The biggest advantage of tracing is to be able to look at collected `traces`
    35   that contain one or more `spans`.
    36  Each trace tells a little story about what's happening in the code.
    37  Usually it's a user interaction, but for onet it also makes sense to have
    38   protocols behaviour's traced.
    39  
    40  ## How
    41  
    42  In order not to have to rewrite a lot of code, this tracing module uses the
    43   `onet/log` package to simulate the tracing.
    44  By signing up as a `Logger`, this package gets informed of every `log.*` call.
    45  It looks at the stack that lead up to that call and decides to which trace
    46   this `log` belongs.
    47  This allows it to use all the `log.*` calls already in the code and to start
    48   directly tracing.
    49  In order to detect trace-starts, there is a list of methods that indicate a
    50   new trace.
    51   
    52  As go doesn't support tracing of which go-routines are started by which other
    53   go-routine, the tracing mechanism needs some manual support:
    54  `log.TraceID` allows different go-routines to register to the tracing service
    55   as spans belonging together.
    56  This method is used to link different parts of the protocol together, by
    57   using the `onet.Token.RoundID` as unique identifier.
    58  This should even work cross-node.
    59   
    60  ## Add your own traces
    61  
    62  There is a good chance that it will work out-of-the box.
    63  If you want to add your own methods where a trace should start, simply add
    64   them to the environment:
    65   
    66  ```
    67  export TRACING_ENTRY_POINTS="github.com/org/repo/pkg.method"
    68  export TRACING_DONE_MSGS="done with tracing"
    69  HONEYCOMB_API_KEY=api_key:dataset ./conode
    70  ```
    71  
    72  If you're wondering what traces are available, you can set
    73  
    74  ```
    75  export TRACING_PRINT_SINGLE_SPANS=10
    76  ```
    77  
    78  This will output stack-traces with length `10` on all unregistered spans.
    79  The outputted lines can be added to `TRACING_ENTRY_POINTS`, as well as a
    80   meaningful done message to `TRACING_DONE_MSGS`.
    81  And voilà, your own tracing is enabled.
    82  
    83  ## Unknown traces
    84  
    85  Some of the traces will not be found.
    86  If you set `TRACING_CREATE_SINGLE_SPANS=true`, these unknown traces will be
    87   created as traces with a single span.
    88  This is not pretty, but might turn out useful sometimes.
    89  
    90  ## Debugging
    91  
    92  As loggers cannot use onet/log, you can set the following environment
    93   variable to output some debugging information about what's happening:
    94   
    95  ```
    96  export TRACING_DEBUG=true 
    97  ```
    98