github.com/instana/go-sensor@v1.62.2-0.20240520081010-4919868049e1/docs/manual_instrumentation.md (about)

     1  ## Instrumenting Code Manually
     2  
     3  The IBM Instana Go Tracer is built on top of the [Opentracing SDK](https://github.com/opentracing/opentracing-go).
     4  In practical terms this means that we provide concrete implementations for Opentracing's tracer, span interfaces and other required implementations to fulfill the SDK.
     5  
     6  All these concrete implementations are publicly available and can be used by anyone.
     7  
     8  The main difference between customers creating their own traces and using our SDK is that we encapsulate all the boilerplate code and data collection logic within the tracer and additional packages instrumentation for your convenience.
     9  
    10  However, customers can extend it to create custom spans or provide extra tags with our SDK.
    11  
    12  This section is dedicated to explore the creation of custom spans to be sent to the Instana Agent.
    13  
    14  
    15  ### Understanding Entry Spans
    16  
    17  A trace should always start with an entry span, which should be the parent span of subsequent spans.
    18  
    19  If a span is created with the type `intermediate` or `exit` and it is sent to the Agent, the UI will provide a hollow entry span automatically called `Internal Trigger`.
    20  However, our tracer limits its own spans (which is, not custom spans) to always require an entry span.
    21  
    22  A common use case is the instrumentation of outgoing HTTP requests with our SDK.
    23  These requests are `exit` spans, as they are "exiting" your application and require an entry span.
    24  Often this entry span will be an incoming HTTP request or a receiving queue message. But if this is not the case, an entry span must be manually created and attached as the parent span of the outgoing HTTP request (exit) span.
    25  
    26  ### Creating and Reporting Spans
    27  
    28  You can create an entry span with the `StartSpan` method and by providing `ext.SpanKindRPCServer` as one of the options:
    29  
    30  ```go
    31  package main
    32  
    33  import (
    34    instana "github.com/instana/go-sensor"
    35    ot "github.com/opentracing/opentracing-go"
    36    "github.com/opentracing/opentracing-go/ext"
    37  )
    38  
    39  func main() {
    40    col := instana.InitCollector(&instana.Options{
    41      Service: "My Service",
    42    })
    43  
    44    ps := col.StartSpan("my-entry-span", []ot.StartSpanOption{
    45      ext.SpanKindRPCServer,
    46    }...)
    47  
    48    // Do some work
    49  
    50    // Always make sure to call Finish to send the span to the Agent.
    51    ps.Finish()
    52  }
    53  ```
    54  
    55  The `StartSpan` method is compliant to the Opentracing interfaces, so you can rely on the Opentracing elements, such as `ot.StartSpanOption` for the span options or `ot.Tags` as part of the span options.
    56  You can also notice the usage of Opentracing's `ext.SpanKindRPCServer` to define the span as an entry span.
    57  
    58  > [!NOTE]
    59  > You can use Opentracing's `ext.SpanKindRPCClient` to define an exit span. If no kind is provided, the span is assumed to be an `intermediate` span.
    60  
    61  
    62  ### Correlating Spans
    63  
    64  If you wish to define a relation for a span with respect to another span, so that multiple spans can be correlated to each other to form a more elaborate trace, you can use the method `ot.ChildOf()` as one of the options for child spans.
    65  
    66  ```go
    67  package main
    68  
    69  import (
    70    instana "github.com/instana/go-sensor"
    71    ot "github.com/opentracing/opentracing-go"
    72    "github.com/opentracing/opentracing-go/ext"
    73  )
    74  
    75  func main() {
    76    col := instana.InitCollector(&instana.Options{
    77      Service: "My Service",
    78    })
    79  
    80    ps := col.StartSpan("my-parent-entry-span", []ot.StartSpanOption{
    81      ext.SpanKindRPCServer,
    82    }...)
    83  
    84    // Do some work
    85  
    86    ps.Finish()
    87  
    88    exs := col.StartSpan("my-child-exit-span", []ot.StartSpanOption{
    89      ext.SpanKindRPCClient,
    90  
    91      // Make sure to provide the parent span context to ot.ChildOf in order to correlate these spans
    92      ot.ChildOf(ps.Context()),
    93    }...)
    94  
    95    // Do some work
    96  
    97    exs.Finish()
    98  }
    99  ```
   100  
   101  -----
   102  [README](../README.md) |
   103  [Tracer Options](options.md) |
   104  [Tracing HTTP Outgoing Requests](roundtripper.md) |
   105  [Tracing SQL Driver Databases](sql.md) |
   106  [Tracing Other Go Packages](other_packages.md)