Send traces

Rootprint accepts OTLP spans at a single endpoint, authenticated with an ingest API key. Spans go to the span store, not to the key’s index. See Traces.

Endpoint

POST https://<your-rootprint>/v1/traces

Authentication

Authorization: Bearer <your-ingest-api-key>

Any existing ingest API key works. Create one at Settings → API keys if you do not have one.

Supported content types

Rootprint accepts application/x-protobuf only. Any other Content-Type returns 415 Unsupported Media Type.

The JavaScript package @opentelemetry/exporter-trace-otlp-http defaults to JSON. Switch to @opentelemetry/exporter-trace-otlp-proto (same OTLPTraceExporter API).

Environment variables

Variable	Value
`OTEL_SERVICE_NAME`	Your service name (lands in the span’s `service_name`).
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`https://<your-rootprint>/v1/traces`
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	`Authorization=Bearer%20<your-ingest-api-key>`
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`
`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`	`none` for the Python and Node.js agents. They default to `otlp` and would retry `localhost:4318` forever.

The endpoint variable takes the full path, not a base URL.

The %20 after Bearer is required: OpenTelemetry SDKs expect URL-encoded values in OTEL_EXPORTER_OTLP_TRACES_HEADERS.

Set up your service

Python
Node.js
Go
OpenTelemetry Collector

Install the zero-code agent. opentelemetry-bootstrap adds instrumentation for the libraries you have installed, such as Flask, Django, FastAPI, requests, and psycopg.

pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install

Set the environment.

export OTEL_SERVICE_NAME=my-python-service
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='https://<your-rootprint>/v1/traces'
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20rp_your-ingest-api-key
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none

Run your app under the agent. Exercise a route and the spans are batched and exported within a few seconds.

opentelemetry-instrument python app.py

Install the auto-instrumentation package. Its register entrypoint patches http, express, koa, pg, redis, and more before your code loads. For Fastify, also add @fastify/otel.

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node

Set the environment.

export OTEL_SERVICE_NAME=my-node-service
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='https://<your-rootprint>/v1/traces'
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20rp_your-ingest-api-key
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none

Start your app with the register hook.

node --require @opentelemetry/auto-instrumentations-node/register app.js

If your entrypoint is ESM, add the loader hook as well. Without it, modules loaded with import are not patched.

node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
  --import @opentelemetry/auto-instrumentations-node/register app.js

Go has no stable zero-code agent, so you wire up the provider in code. Add the SDK and the HTTP/protobuf trace exporter to your module (run go mod init first if you have none).

go get go.opentelemetry.io/otel \
    go.opentelemetry.io/otel/sdk/trace \
    go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

Set the environment. The exporter reads these automatically.

export OTEL_SERVICE_NAME=my-go-service
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='https://<your-rootprint>/v1/traces'
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20rp_your-ingest-api-key

Save this to main.go and run go run . — Shutdown flushes the batch before the process exits. Then instrument for real with the net/http and database wrappers in go.opentelemetry.io/contrib.

package main

import (
	"context"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	ctx := context.Background()
	exporter, err := otlptracehttp.New(ctx)
	if err != nil {
		panic(err)
	}
	provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer provider.Shutdown(ctx)
	otel.SetTracerProvider(provider)

	_, span := otel.Tracer("hello").Start(ctx, "hello-from-go")
	span.End()
}

Install the Contrib distribution (otelcol-contrib) v0.149 or newer, which accepts the otlp_http exporter name used below. See the upstream install guide.Save this at /etc/otelcol-contrib/config.yaml, then point your instrumented services at the Collector (4317 for gRPC, 4318 for HTTP) instead of at Rootprint.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch: {}

exporters:
  otlp_http:
    traces_endpoint: https://<your-rootprint>/v1/traces
    compression: gzip
    headers:
      Authorization: "Bearer rp_your-ingest-api-key"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http]

If the Collector already ships logs, merge this receiver, exporter, and pipeline into that file rather than replacing it. One otlp_http exporter carries both signals: set logs_endpoint and traces_endpoint side by side and declare both pipelines.Restart the Collector:

sudo systemctl restart otelcol-contrib
sudo systemctl status otelcol-contrib

Send a test span. JSON is fine on this hop, because the Collector re-encodes to protobuf on export.

NOW=$(date +%s)
curl -sS -X POST http://localhost:4318/v1/traces \
  -H 'content-type: application/json' \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"curl-smoke-test"}}]},"scopeSpans":[{"spans":[{"traceId":"5b8efff798038103d269b633813fc60c","spanId":"eee19b7ec3c1b174","name":"hello-from-curl","kind":2,"startTimeUnixNano":"'"${NOW}000000000"'","endTimeUnixNano":"'"${NOW}100000000"'"}]}]}]}'

Correlate spans with logs

Ship logs from the same service as well, and Rootprint pairs logs and spans by trace ID. See Send logs and Correlate logs with traces. With the Collector, log records need trace context: from an OpenTelemetry log appender in the application, or a trace_parser operator that reads the trace ID out of tailed lines.

Response codes

Status	Meaning
`200`	Accepted. Carries `partial_success` when some spans were rejected.
`401`	Missing ingest API key.
`403`	Invalid or unknown ingest API key.
`413`	Payload too large.
`415`	`Content-Type` is not `application/x-protobuf`.
`429`	Rate limit exceeded. Honor `Retry-After`.
`503`	Quickwit unavailable. OTLP clients retry it.

See POST /v1/traces for every status and the error encoding.

Get Started

Send Logs

Traces

Search Logs

Manage Rootprint

Endpoint

Authentication

Supported content types

Environment variables

Set up your service

Correlate spans with logs

Response codes

​Endpoint

​Authentication

​Supported content types

​Environment variables

​Set up your service

​Correlate spans with logs

​Response codes

​Related

Endpoint

Authentication

Supported content types

Environment variables

Set up your service

Correlate spans with logs

Response codes

Related