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:
%20is the space afterBearer. Copy it from the Console, which encodes the token for you (a token ending in=needs%3Dthere). OTEL_SERVICE_NAMEis 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=noneIf 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=none3. 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/traces200 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.jsOr 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.pySet 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/otlptracehttpimport (
"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.jarOther 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: checkoutUsing 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 code | On the Traces page |
|---|---|
Span status Error with a description | The 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 links | Links, with Open linked trace |
Resource attributes (service.version, deployment.environment.name) | Resource in the span's details |
| The tracer's name and version | Scope |
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
429withRetry-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:
| Error | Cause |
|---|---|
401 | The token is missing, wrong or revoked |
403 with an error message | Your plan has no SDK traces |
403 with an HTML page, or gRPC UNIMPLEMENTED | The exporter uses gRPC: set http/protobuf |
404 "traces only" | A metrics or logs exporter is still on |
413 | A batch over 8 MiB: lower the exporter's batch size |
415 | The exporter sends http/json: set http/protobuf |
429 | Over 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.