Send traces to the Agent by API

Datadog APM allows you to collect performance metrics by tracing your code to determine which parts of your application are slow or inefficient.

Tracing data is sent from your instrumented code to the Datadog Agent through an HTTP API. Datadog tracing libraries simplify sending metrics to the Datadog Agent. However you might want to interact directly with the API to instrument applications that cannot use the libraries or are written in languages that don’t yet have an official Datadog tracing library.

The tracing API is an Agent API rather than a service side API. Submit your traces to the http://localhost:8126/v0.3/traces local endpoint so your Agent can forward them to Datadog.

Path

PUT http://localhost:8126/v0.3/traces

Request

Traces can be sent as an array of traces:

[ trace1, trace2, trace3 ]

And each trace is an array of spans:

trace1 = [ span, span2, span3 ]

and each span is a dictionary with a trace_id, span_id, resource and so on. Each span within a trace should use the same trace_id. However, trace_id and span_id must have different values.

Model

Datadog tracing libraries support both 64-bit and 128-bit trace IDs. Read Span and Trace ID formats to learn more.
FieldTypeDescription
durationint64The duration of the request in nanoseconds.
errorint32Set this value to 1 to indicate if an error occurred. If an error occurs, you should pass additional information, such as the error message, type and stack information in the meta property.
metaobjectA set of key-value metadata. Keys and values must be strings.
- <any-key>stringAdditional properties for key-value metadata.
metricsobjectA set of key-value metadata. Keys must be strings and values must be 64-bit floating point numbers.
- <any-key>doubleAdditional properties for key-value metrics.
namestringThe span name. The span name must not be longer than 100 characters.
parent_idint64The span integer ID of the parent span.
resourcestringThe resource you are tracing. The resource name must not be longer than 5000 characters.
servicestringThe service you are tracing. The service name must not be longer than 100 characters.
span_idint64The span integer (64-bit unsigned) ID.
startint64The start time of the request in nanoseconds from the UNIX epoch.
trace_idint64 or int128The unique integer (64-bit unsigned or 128-bit unsigned) ID of the trace containing this span.
typeenumThe type of request. Allowed enum values: web, db, cache, custom

Example

[
  [
    {
      "duration": 12345,
      "error": "integer",
      "meta": {
        "<any-key>": "string"
      },
      "metrics": {
        "<any-key>": "number"
      },
      "name": "span_name",
      "parent_id": "integer",
      "resource": "/home",
      "service": "service_name",
      "span_id": 987654321,
      "start": 0,
      "trace_id": 123456789,
      "type": "web"
    }
  ]
]

Response

200
OK

Example

    # Curl command
curl -X PUT "http://localhost:8126/v0.3/traces" \
-H "Content-Type: application/json" \
-d @- << EOF
[
  [
    {
      "duration": 12345,
      "name": "span_name",
      "resource": "/home",
      "service": "service_name",
      "span_id": 987654321,
      "start": 0,
      "trace_id": 123456789
    }
  ]
]
EOF
    # Invoke-RestMethod command

$uri = "http://localhost:8126/v0.3/traces"
$headers = @{
    "Content-Type" = "application/json"
}
$body = @"
[
  [
    {
      "duration": 12345,
      "name": "span_name",
      "resource": "/home",
      "service": "service_name",
      "span_id": 987654321,
      "start": 0,
      "trace_id": 123456789
    }
  ]
]
"@

Invoke-RestMethod -Uri $uri -Method Put -Body $body -Headers $headers

    Further Reading

    Additional helpful documentation, links, and articles:

    Learn about Datadog APM tracingDOCUMENTATION more more APM Terminology and OverviewDOCUMENTATION more more