OTLP explained: How OpenTelemetry sends data

Compare OTLP/gRPC and OTLP/HTTP, read partial-success responses, and configure the correct DataKit endpoints for traces, metrics, and logs.

Best practices
Illustration of service traces and metrics in application performance monitoring

An exporter can reach a Collector and still send to the wrong path. It can also get an HTTP 200 even though the receiver rejected some of the batch. To diagnose either case, you need to know what the exporter put on the wire and what the response actually acknowledged.

OTLP, the OpenTelemetry Protocol, defines how telemetry is encoded and sent. It uses Protobuf message definitions and supports both gRPC and HTTP. The specification is stable for traces, metrics, and logs. Profiles are still in development. Two systems can exchange data when their support overlaps for the signal, transport, and encoding.

OTLP at a glance

  • OTLP covers encoding and transport. The backend handles storage and queries.
  • gRPC uses binary Protobuf. OTLP/HTTP can also use OTLP’s JSON mapping when the receiver supports it.
  • Resource and instrumentation scope group the individual spans, metrics, or log records.
  • DataKit accepts OTLP traces, metrics, and logs. Its default HTTP setup uses port 9529 and routes under /otel/v1/.

What happens when an exporter sends a batch?

  1. Build the request. An SDK exporter or a Collector groups the telemetry into an OTLP export request.
  2. Send it. A gRPC exporter makes a unary call. An HTTP exporter sends a POST. Configure compression, TLS, and authentication according to what the endpoints support.
  3. Read the response. Full success means this receiver accepted the batch. With OTLP/HTTP, full and partial success both use HTTP 200. A populated partial_success field can contain a rejected-item count and a diagnostic message. It can also contain only a warning with zero items rejected. The exporter must not retry that request.

For a failed OTLP/HTTP request, the specification calls for retries on 429, 502, 503, and 504. Honor Retry-After when provided and back off otherwise. Other 4xx and 5xx responses are non-retryable. For example, with a 400, check the payload. OTLP/gRPC uses gRPC status codes and error details instead. UNAVAILABLE is retryable.

An acknowledgment covers one hop. If a Collector accepted a request, check the Collector’s export separately before concluding that the backend stored it. When an acknowledgment is lost, a retry can deliver duplicate data. OTLP specification

How OTLP groups telemetry

Traces, metrics, and logs follow the same outer structure. The exact Protobuf fields vary by signal.

Export<Signal>ServiceRequest
└── resource_<signal>[]
    ├── resource (service.name, host.name, …)
    └── scope_<signal>[]
        ├── scope (name, version, …)
        └── spans[] / metrics[] / log_records[]

A trace span carries IDs such as trace_id and span_id, a parent span ID where applicable, and fields for status and attributes. Metrics include types such as Sum, Gauge, Histogram, and ExponentialHistogram. A log record has fields for the event time, severity, body, and attributes, and can carry trace context.

For a trace export, the binary schema groups spans under resource_spans and scope_spans. In OTLP JSON, keys use lowerCamelCase, as in traceId. Trace and span IDs use hex strings, and enums use integers. An arbitrary JSON payload or a default Protobuf-to-JSON serializer may produce a different format.

OTLP/gRPC or OTLP/HTTP?

OTLP/gRPC OTLP/HTTP
Standard default port 4317 4318
Request and connection Unary export calls on a gRPC connection HTTP POST, with connection reuse
Encoding Binary Protobuf Binary Protobuf or OTLP JSON, depending on the receiver
Proxy requirements Must forward gRPC correctly Must allow the POST, path, and content type
Debugging A gRPC client with the service definition curl with a valid POST body in the right encoding

Start with the transport your SDK, proxies, and receiver support. If both work, compare throughput and resource use at the batch sizes and compression settings you plan to run. A binary HTTP request uses application/x-protobuf. Check its full route too. The standard HTTP paths are /v1/traces, /v1/metrics, and /v1/logs, but a receiver can use different routes.

Connecting an application to a receiver

  1. Send from the application. Use the OpenTelemetry SDK or supported automatic instrumentation to produce telemetry. Configure the exporter for the destination’s protocol and endpoint.
  2. Route through a Collector. An OpenTelemetry Collector can receive data, then batch, filter, or redact it according to the configured pipeline before exporting.
  3. Bridge an older trace format. If your Collector distribution includes the Jaeger or Zipkin receiver, enable the one that matches the existing sender. The pipeline can export those traces over OTLP. Check protocol variants, field mappings, and context before depending on the converted data.

To send to Guance, enable the DataKit OpenTelemetry input and the exporters for the signals you need. Check the address from the sender’s network namespace. The sample gRPC listener at 127.0.0.1:4317 only accepts connections through loopback. For HTTP, use http/protobuf. DataKit defaults to port 9529, with routes at /otel/v1/traces, /otel/v1/metrics, and /otel/v1/logs.

For a plaintext connection on a trusted test network, replace the hostname and use the following with DataKit’s default HTTP routes.

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit-host:9529/otel

The shared HTTP endpoint is a base URL. A conforming exporter appends the signal path. A per-signal variable such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT takes the complete URL, for example http://datakit-host:9529/otel/v1/traces. The metric and log settings follow the same rule. Supply only the credentials required by the receiver or gateway. The actual DataKit setup determines the Guance workspace. OTLP exporter configuration

Send a batch you can identify, then query each enabled signal in the intended workspace. Any configured Collector filters or redaction still run before export. To open a trace from a log, check that the identifier matches and that the trace itself is available.

Frequently asked questions

How do I secure an OTLP connection? Configure TLS where traffic crosses an untrusted network and verify the receiver’s certificate. Authentication depends on the deployment. A gateway might require headers, while another setup may use mutual TLS.

Can OTLP become a bottleneck? Encoding, compression, transfer, and receiver processing all consume resources. Larger batches can reduce request overhead but add waiting or memory usage. Gzip can save bandwidth at a CPU cost. Look at export latency, queue usage, and rejected items before adjusting those settings.

Can newer exporters talk to older receivers? Protobuf supports some compatible schema changes, such as adding fields an older receiver can ignore. Interoperability still depends on the signals, encodings, and optional capabilities that both implementations support.

Can Guance be my only OTLP backend? DataKit can send the supported signals to Guance when its ingestion and processing cover your needs. Verify the data needed for your queries, retention, and alerts for each signal you plan to use.

Further reading

References: OTLP specification · Guance OpenTelemetry integration · DataKit documentation · Guance APM

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting