OTLP Ingestion

• OTLP/HTTP protobuf — Content-Type: application/x-protobuf. Recommended; supported by every OpenTelemetry SDK.
• OTLP/HTTP JSON — Content-Type: application/json. Not every SDK can export JSON; prefer protobuf unless yours does.
• Content-Encoding: gzip for either format.
• OTLP/gRPC is not supported. There is no gRPC listener; configure your exporter or Collector for OTLP/HTTP.

Endpoint: POST /api/traces/v1/otlp. The alias POST /api/otlp/v1/traces lets you set the base OTEL_EXPORTER_OTLP_ENDPOINT=https://mydle.app/api/otlp. Auth: Authorization: Bearer tt_… (tracing source token — create sources under Traces → Ingest; the token is shown once).

Node.js, verified end to end with @opentelemetry/exporter-trace-otlp-proto 0.220.0, @opentelemetry/sdk-trace-base 2.9.0, @opentelemetry/resources 2.9.0 and @opentelemetry/api 1.9.1:

npm install @opentelemetry/api @opentelemetry/resources \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/otlp-exporter-base

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { CompressionAlgorithm } from "@opentelemetry/otlp-exporter-base";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";

const exporter = new OTLPTraceExporter({
  url: "https://mydle.app/api/traces/v1/otlp",
  headers: { Authorization: `Bearer ${process.env.MYDLE_TRACE_TOKEN}` },
  compression: CompressionAlgorithm.GZIP,
});

const provider = new BasicTracerProvider({
  resource: resourceFromAttributes({
    "service.name": "checkout-api",
    "service.version": "2.4.1",
    "deployment.environment.name": "production",
  }),
  spanProcessors: [new BatchSpanProcessor(exporter, { maxExportBatchSize: 500 })],
});

The standard environment variables express the same settings for SDKs with OTLP/HTTP protobuf support (not covered by our automated test):

OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://mydle.app/api/traces/v1/otlp
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer tt_…"
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION=gzip

• Per request: 5 MiB body, 5 MiB after gzip, 500 spans, 64 KiB per normalized span. Keep maxExportBatchSize at or below 500.
• A protobuf request may contain at most 200,000 objects (spans, attributes, values, events) and nest attribute values at most 32 levels deep. More objects return 413 TOO_MANY_OBJECTS; deeper nesting returns 400.
• Larger requests return 413 and nothing is stored. A batch with any invalid span is rejected as a whole.
• Monthly usage is measured on the normalized span, so protobuf, JSON and gzip are charged the same.

Responses follow the OTLP/HTTP specification and use the request's Content-Type: an empty ExportTraceServiceResponse on success, a google.rpc.Status with ErrorInfo (reason such as INVALID_PROTOBUF, TOO_MANY_SPANS, QUOTA_EXCEEDED) on failure.

Retries are safe: a span already stored for the workspace (same trace ID and span ID, in either format) is skipped and not charged again.

• Trace and span IDs as lowercase hex; parent links, kind, status, events (including exceptions) and links.
• Resource attributes are merged into span attributes; service.name, service.version (release) and deployment.environment.name are promoted. The instrumentation scope is kept as otel.scope.name / otel.scope.version.
• All attribute value types: strings, booleans, integers, doubles, arrays, nested key/value lists and bytes (as base64).

Primary write is always Postgres. When ClickHouse is configured, a secondary fail-open writer dual-writes envelopes for query acceleration. ClickHouse misconfiguration does not fail the ingest request.

• OpenTelemetry
• Trace Explorer