OpenTelemetry (OTLP)

Obscenter traces Node.js with its own agent. Every other language joins through OpenTelemetry, and its spans land in the same traces as the native ones, on the same pages.

The endpoint

POST https://your-install/v1/traces       OTLP/HTTP, protobuf or JSON encoding

Point an OpenTelemetry SDK at your install with three environment variables. Protobuf is what most SDKs send by default; JSON is read the same way.

OTEL_EXPORTER_OTLP_ENDPOINT=https://your-install
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf      # or http/json
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=<application key or agent key>

• OTLP/HTTP, protobuf or JSON. The body is application/x-protobuf or application/json, plain or gzip-compressed. A protobuf request gets a protobuf answer, as the protocol says. gRPC is not accepted; another content type is refused with 415.
• Traces only. There is no /v1/logs or /v1/metrics. Logs come from the host agent, and metrics from the agents.
• The key goes in x-api-key. Without a valid key the answer is 401. Payloads may be up to 4 MB as sent and 16 MB once unpacked. A body that cannot be read is refused with 400 and nothing of it is stored.
• If part of a batch cannot be mapped, the answer reports the rejected spans in OTLP's partialSuccess.

How spans are mapped

• service.name becomes the service.
• A span of kind SERVER becomes the request.
• Other spans become database spans when they carry db.system, HTTP spans when they are of kind CLIENT, and application spans otherwise.
• The host comes from host.name.

The services appear under Backend → Services, and their calls under Traces, with an otel badge on the spans that came this way.

One request, one row

A Node.js service can be measured by the native agent and also export its own OpenTelemetry spans. The two must never become two services or two requests. So when service.name matches a natively instrumented service, the OTLP spans are grafted into the native request. The match is tried three ways:

1. by trace id;
2. otherwise by overlap: the same service and method, at an overlapping time, with the route as a tie-break;
3. otherwise the fragment waits, for up to three minutes, for its native request to arrive.

A pass every 20 seconds promotes fragments that never pair into requests of their own. A span id that is already stored is dropped, so a retrying exporter does not duplicate anything.

Without an exporter

If a Node.js app already uses @opentelemetry/api to create its own spans, you do not need to configure an exporter at all. The in-process agent wraps the tracer provider and records those spans straight into the request it is measuring. They show with an otel · in-process badge. The install page puts it this way: already using OpenTelemetry, it fits; not using it, the agent picks the spans up anyway.

Attributes your spans declare with a dotted name, such as checkout.total, appear on the Business logic page with their values and ranges.

SDKs that only speak gRPC

The HTTP exporters send straight to your install, in protobuf or JSON. An SDK that can only export over gRPC needs an OpenTelemetry Collector beside the service. Let the SDK send to the Collector in whatever it speaks, and let the Collector forward to your install over HTTP:

receivers:
  otlp:
    protocols:
      grpc:
      http:
exporters:
  otlphttp:
    endpoint: https://your-install      # /v1/traces is added by the exporter
    headers:
      x-api-key: agt_…
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]

Gzip-compressed bodies are accepted, so the exporter's default compression can stay on. Set service.name on each service, through OTEL_SERVICE_NAME or the SDK's resource. If a browser page or a Node.js service calls this one with a traceparent, its spans continue the same trace, and the whole chain shows as one call.

Deploy markers

CI can mark a deploy with POST /api/deploy. Charts draw the marker, and tickets quote it when a fault starts soon after. See Deploy markers.