Docs/OpenTelemetry SDKs

OpenTelemetry SDKs

Send spans from your services' OpenTelemetry SDKs straight to Status Harbor. You don't need a Lighthouse agent for this: any service that can reach https://otlp.statusharbor.io can send. The spans show up on the Traces page in the console, next to your check and service traces (see Traces). SDK traces are included from the Pro plan.

1. Create a token

Create an API token with the traces:write scope under Settings → API Tokens. It can send spans and nothing else, so it is safe to put in your services' config. The Console then shows the settings below with your token filled in.

2. Point the exporter at Status Harbor

Every OpenTelemetry SDK reads the same environment variables:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.statusharbor.io/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20<your token>
OTEL_SERVICE_NAME=<your service>
  • The header value is URL-encoded: %20 is the space after Bearer. Copy it from the Console, which encodes the token for you (a token ending in = needs %3D there).
  • OTEL_SERVICE_NAME is the name the service gets in traces and on the service map. Use one name per service, not per instance.

Status Harbor accepts traces only. The zero-code agents below also export metrics and logs by default; turn those off or the SDK sends them too and they are refused with "traces only":

OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none

If you prefer one endpoint for all signals, this form works the same way (the SDK appends /v1/traces itself):

OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.statusharbor.io
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<your token>
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none

3. Check the token

An empty export request checks the token and your plan without sending any spans:

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  -H "Authorization: Bearer <your token>" \
  -H "Content-Type: application/x-protobuf" \
  --data-binary '' \
  https://otlp.statusharbor.io/v1/traces

200 means you are set. 401 means the token is wrong or revoked and 403 means your plan has no SDK traces.

Node.js

Without code changes, load the auto-instrumentation when Node starts:

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

Or set the SDK up in code. Use the -proto exporter: @opentelemetry/exporter-trace-otlp-http sends JSON, which Status Harbor refuses.

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto @opentelemetry/auto-instrumentations-node
// tracing.js - load it first: node --require ./tracing.js app.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
 
const sdk = new NodeSDK({
  // Reads OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and _HEADERS.
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Python

Without code changes, run your app under opentelemetry-instrument:

pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install
opentelemetry-instrument python app.py

Set OTEL_METRICS_EXPORTER=none and OTEL_LOGS_EXPORTER=none here: the Python agent exports all three signals by default.

Or set the SDK up in code:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
# Reads OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_TRACES_*.
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

Go

Go has no zero-code agent; set the SDK up in code with the HTTP exporter:

go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp
import (
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)
 
func setupTracing(ctx context.Context) (func(context.Context) error, error) {
	// Reads OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and _HEADERS.
	exp, err := otlptracehttp.New(ctx)
	if err != nil {
		return nil, err
	}
	// The default resource reads OTEL_SERVICE_NAME.
	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp))
	otel.SetTracerProvider(tp)
	return tp.Shutdown, nil
}

Call the returned shutdown function on exit so the last batch is sent. Go services on a host with a Lighthouse can also be traced without any code through service traces.

Java

Attach the OpenTelemetry Java agent. It uses http/protobuf by default and also exports metrics and logs, so set OTEL_METRICS_EXPORTER=none and OTEL_LOGS_EXPORTER=none:

curl -LO https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
java -javaagent:opentelemetry-javaagent.jar -jar app.jar

Other languages

.NET, Ruby, PHP, Rust and the other SDKs read the same variables. Make sure the exporter speaks http/protobuf: some SDKs, .NET among them, default to gRPC until OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf is set.

Kubernetes

Keep the header in a Secret and pass the rest as plain env:

kubectl create secret generic statusharbor-otlp \
  --from-literal=headers='Authorization=Bearer%20<your token>'
env:
  - name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
    value: https://otlp.statusharbor.io/v1/traces
  - name: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
    value: http/protobuf
  - name: OTEL_EXPORTER_OTLP_TRACES_HEADERS
    valueFrom:
      secretKeyRef:
        name: statusharbor-otlp
        key: headers
  - name: OTEL_SERVICE_NAME
    value: checkout

Using gRPC today?

Status Harbor accepts OTLP over HTTP only. Switch the exporter to OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf; it is one setting in every SDK. If your services must keep gRPC, send it to an OpenTelemetry Collector next to them and let the Collector export to Status Harbor over HTTP:

receivers:
  otlp:
    protocols:
      grpc:
exporters:
  otlphttp:
    traces_endpoint: https://otlp.statusharbor.io/v1/traces
    headers:
      Authorization: Bearer <your token>
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]

What you see in the Console

In your codeOn the Traces page
Span status Error with a descriptionThe span in red, with the description at the top of its details
recordException (Node.js, Java), record_exception (Python), RecordError (Go)An exception event: type, message and the stack trace
Span events (addEvent)Events in time order, and ticks on the span's bar
Span linksLinks, with Open linked trace
Resource attributes (service.version, deployment.environment.name)Resource in the span's details
The tracer's name and versionScope

See Reading a trace for the waterfall and the span details.

What is accepted

  • OTLP over HTTP with protobuf, gzip or not, in batches up to 8 MiB.
  • Traces only: not gRPC, http/json, metrics or logs.
  • Over your plan's span budget the endpoint answers 429 with Retry-After; OpenTelemetry exporters wait and retry on their own.
  • Attribute values are stored as text. Numbers keep every digit and arrays read as JSON ([1,2,3]), but they are shown as text, and an empty string is shown as -.

Your plan sets how much storage your traces may use; when it is full, your oldest days are deleted first and new spans are still accepted (see Trace storage).

Spans from your SDKs are stored as you send them: you choose their attributes. Status Harbor removes any statusharbor.* attribute and adds your team. Spans are kept for 30 days; your plan sets how far back you can search and how many spans per second your team can send (see Plans & limits).

Troubleshooting

What your SDK logs when an export fails:

ErrorCause
401The token is missing, wrong or revoked
403 with an error messageYour plan has no SDK traces
403 with an HTML page, or gRPC UNIMPLEMENTEDThe exporter uses gRPC: set http/protobuf
404 "traces only"A metrics or logs exporter is still on
413A batch over 8 MiB: lower the exporter's batch size
415The exporter sends http/json: set http/protobuf
429Over your plan's span budget; the SDK retries

No error but no traces? New spans can take up to a minute to appear in the Traces list, which checks again for two minutes after it loads. The SDK also sends spans in batches every few seconds: short scripts and serverless functions must shut the SDK down (or flush it) before they exit. Spans sent without OTEL_SERVICE_NAME appear under unknown_service.