Trace SDK Web Service

Using the Trace SDK REST Web Service, it is possible to integrate Instana into any application regardless of language. Each active Instana Agent can be used to feed manually captured traces into the Web Service, which can be joined with automatically captured traces or be completely separate. The Agent offers an endpoint which listens on http://localhost:42699/com.instana.plugin.generic.trace and accepts the following JSON via a POST request:

  "spanId": <64 bit long>,
  "parentId": <64 bit long>,
  "traceId": <64 bit long>,
  "backendTrace": <64 bit long>,
  "timestamp": <64 bit long>,
  "duration": <64 bit long>,
  "name": <string>,
  "type": <string>,
  "error": <boolean>,
  "data": {
    <string> : <string>

spanId is the unique identifier for any particular span. The trace is defined by a root span, that is, a span that does not have a parentId. The traceId needs to be identical for all spans that belong to the same trace, and is allowed to be overlapping with a spanId. Spans form a hierarchy by referencing the spanId of the parent as parentId. An example of a span hierarchy in a trace is shown below:

root (spanId=1, traceId=1, type=Entry)
  child A (spanId=2, traceId=1, parentId=1, type=Exit)
    child A (spanId=3, traceId=1, parentId=2, type=Entry)
      child B (spanId=4, traceId=1, parentId=3, type=Exit)
child B (spanId=5, traceId=1, parentId=4, type=Entry)

backendTrace is optional and only used for connecting this span as the End-User Monitoring (EUM) span for the referenced backend traceId. The type needs to be set to EUM.

timestamp and duration are in milliseconds. The timestamp must be the epoch timestamp coordinated to UTC. 

name can be any string which is used to visualize and group traces, and can contain any text. However, simplicity is recommended.

type is optional, when absent is treated as ENTRY. Options are ENTRYEXITINTERMEDIATE, or EUM. Setting the type is important for the UI. It is assumed that after an ENTRY, child spans are INTERMEDIATE or EXIT. After an EXIT an ENTRY should follow. This is visualized as a remote call. 

data is optional and can contain arbitrary key-value pairs. The behavior of supplying duplicate keys is unspecified. 

error is optional and can be set to true to indicate an erroneous span.

The endpoint also accepts a batch of spans, which then need to be given as an array:

    // span as above
    // span as above

For traces received via the Trace SDK Web Service the same rules regarding Conversion and Service/Endpoint Naming are applied as for the Java Trace SDK.