github.com/waldiirawan/apm-agent-go/v2@v2.2.2/docs/opentracing.asciidoc (about)

     1  [[opentracing]]
     2  == OpenTracing API
     3  
     4  The Elastic APM Go agent provides an implementation of the https://opentracing.io[OpenTracing API],
     5  building on top of the core Elastic APM API.
     6  
     7  Spans created through the OpenTracing API will be translated to Elastic APM transactions or spans.
     8  Root spans, and spans created with a remote span context, will be translated to Elastic APM
     9  transactions. All others will be created as Elastic APM spans.
    10  
    11  [float]
    12  [[opentracing-init]]
    13  === Initializing the tracer
    14  
    15  The OpenTracing API implementation is implemented as a bridge on top of the core Elastic APM API.
    16  To initialize the OpenTracing tracer implementation, you must first import the `apmot` package:
    17  
    18  [source,go]
    19  ----
    20  import (
    21  	"github.com/waldiirawan/apm-agent-go/module/apmot/v2"
    22  )
    23  ----
    24  
    25  The apmot package exports a function, "New", which returns an implementation of the
    26  `opentracing.Tracer` interface. If you call `apmot.New()` without any arguments,
    27  the returned tracer will wrap `apm.DefaultTracer()`. If you wish to use a different
    28  `apm.Tracer`, then you can pass it with `apmot.New(apmot.WithTracer(t))`.
    29  
    30  [source,go]
    31  ----
    32  otTracer := apmot.New()
    33  ----
    34  
    35  Once you have obtained an `opentracing.Tracer`, use the standard OpenTracing API
    36  to report spans to Elastic APM. Please refer to https://github.com/opentracing/opentracing-go[opentracing-go]
    37  for documentation on the OpenTracing Go API.
    38  
    39  [source,go]
    40  ----
    41  import (
    42  	"context"
    43  
    44  	"github.com/waldiirawan/apm-agent-go/module/apmot/v2"
    45  
    46  	"github.com/opentracing/opentracing-go"
    47  )
    48  
    49  func main() {
    50  	opentracing.SetGlobalTracer(apmot.New())
    51  
    52  	parent, ctx := opentracing.StartSpanFromContext(context.Background(), "parent")
    53  	child, _ := opentracing.StartSpanFromContext(ctx, "child")
    54  	child.Finish()
    55  	parent.Finish()
    56  }
    57  ----
    58  
    59  [float]
    60  [[opentracing-mixed]]
    61  === Mixing Native and OpenTracing APIs
    62  
    63  When you import `apmot`, transactions and spans created with the <<api, native API>>
    64  will be made available as OpenTracing spans, enabling you to mix the use of the
    65  native and OpenTracing APIs. e.g.:
    66  
    67  [source,go]
    68  ----
    69  // Transaction created through native API.
    70  transaction := apm.DefaultTracer().StartTransaction("GET /", "request")
    71  ctx := apm.ContextWithTransaction(context.Background(), transaction)
    72  
    73  // Span created through OpenTracing API will be a child of the transaction.
    74  otSpan, ctx := opentracing.StartSpanFromContext(ctx, "ot-span")
    75  
    76  // Span created through the native API will be a child of the span created
    77  // above via the OpenTracing API.
    78  apmSpan, ctx := apm.StartSpan(ctx, "apm-span", "apm-span")
    79  ----
    80  
    81  The `opentracing.SpanFromContext` function will return an `opentracing.Span`
    82  that wraps either an `apm.Span` or `apm.Transaction`. These span objects are
    83  intended only for passing in context when creating a new span through the
    84  OpenTracing API, and are not fully functional spans. In particular, the `Finish`
    85  and `Log*` methods are no-ops, and the `Tracer` method returns a no-op tracer.
    86  
    87  [float]
    88  [[opentracing-apm-tags]]
    89  === Elastic APM specific tags
    90  
    91  Elastic APM defines some tags which are not included in the OpenTracing API,
    92  but are relevant in the context of Elastic APM. Some tags are relevant only
    93  to Elastic APM transactions.
    94  
    95  - `type` - sets the type of the transaction or span, e.g. "request", or "ext.http".
    96             If `type` is not specified, then the type may be inferred from other
    97             tags. e.g. if "http.url" is specified, then the type will be "request"
    98             for transactions, and "ext.http" for spans. If no type can be inferred,
    99             it is set to "unknown".
   100  
   101  The following tags are relevant only to root or service-entry spans, which are
   102  translated to Elastic APM transactions:
   103  
   104  - `user.id` - sets the user ID, which appears in the "User" tab in the transaction details in the Elastic APM app
   105  - `user.email` - sets the user email, which appears in the "User" tab in the transaction details in the Elastic APM app
   106  - `user.username` - sets the user name, which appears in the "User" tab in the transaction details in the Elastic APM app
   107  - `result` - sets the result of the transaction. If `result` is _not_ specified, but `error` tag is set to `true`,
   108               then the transaction result will be set to "error"
   109  
   110  [float]
   111  [[opentracing-logs]]
   112  === Span Logs
   113  
   114  The `Span.LogKV` and `Span.LogFields` methods will send error events to Elastic APM for logs
   115  with the "event" field set to "error".
   116  
   117  The deprecated log methods `Span.Log`, `Span.LogEvent`, and `Span.LogEventWithPayload` are no-ops.
   118  
   119  [float]
   120  [[opentracing-caveats]]
   121  === Caveats
   122  
   123  [float]
   124  [[opentracing-caveats-propagation]]
   125  ==== Context Propagation
   126  
   127  We support the `TextMap` and `HTTPHeaders` propagation formats; `Binary` is not currently supported.
   128  
   129  [float]
   130  [[opentracing-caveats-spanrefs]]
   131  ==== Span References
   132  
   133  We support only `ChildOf` references. Other references, e.g. `FollowsFrom`, are not currently supported.
   134  
   135  [float]
   136  [[opentracing-caveats-baggage]]
   137  ==== Baggage
   138  
   139  `Span.SetBaggageItem` is a no-op; baggage items are silently dropped.