Как настроить OpenTelemetry
OpenTelemetry (OTel) — CNCF стандарт для unified observability (traces + metrics + logs). Замена Jaeger / Zipkin-specific + Prometheus-specific кода. 2026: auto-instrumentation для Node/Python/Java covers 90% frameworks без кода. Architecture: SDK в app → OTel Collector → backend (Jaeger, Grafana Tempo, Datadog, Honeycomb). Setup: 30 минут для basic tracing.
Ниже: пошаговая инструкция, рабочие примеры, типичные ошибки, FAQ.
Пошаговая настройка
- Install SDK:
npm install @opentelemetry/api @opentelemetry/sdk-node - Enable auto-instrumentation для your framework (Express, FastAPI, Prisma)
- Configure exporter: OTLP (standard) к OTel Collector
- Deploy Collector как sidecar или standalone
- Configure backend (Jaeger — free, Grafana Tempo — free, Datadog — paid)
- Propagate trace context через HTTP headers (baggage + traceparent)
- Sample — не 100% (cost). 1-5% + errors 100%
Рабочие примеры
| Сценарий | Конфиг |
|---|---|
| Node.js auto-instrument | // tracing.js — load first
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const sdk = new NodeSDK({
traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4318/v1/traces' }),
instrumentations: [ getNodeAutoInstrumentations() ]
});
sdk.start(); |
| Start app | $ node -r ./tracing.js server.js
# Or as preload:
$ NODE_OPTIONS="--require ./tracing.js" node server.js |
| Custom span | const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('my-app');
async function processOrder(orderId) {
return tracer.startActiveSpan('processOrder', async (span) => {
span.setAttribute('order.id', orderId);
try {
const result = await doWork(orderId);
span.setStatus({ code: 1 });
return result;
} finally {
span.end();
}
});
} |
| OTel Collector config | # otel-collector-config.yaml
receivers:
otlp:
protocols: { http: {}, grpc: {} }
exporters:
jaeger: { endpoint: jaeger:14250, tls: { insecure: true } }
prometheus: { endpoint: 0.0.0.0:8889 }
service:
pipelines:
traces: { receivers: [otlp], exporters: [jaeger] }
metrics: { receivers: [otlp], exporters: [prometheus] } |
| Python setup | $ pip install opentelemetry-distro[otlp]
$ opentelemetry-bootstrap -a install
$ opentelemetry-instrument \
--traces_exporter otlp \
--service_name my-service \
python app.py |
Типичные ошибки
- Sampling = 100% в prod → огромный storage cost. 1% tail-based (keep slow traces) балансирует
- Missing context propagation — traces дроблятся на single-service. Use propagators для все HTTP/gRPC clients
- Collector down → lose spans. Configure retry + queue в SDK
- Too many attributes per span (full request body) — blow up storage. Hash / redact sensitive
- OTel-LGTM (Grafana stack) бесплатный, но maintenance. Managed (Grafana Cloud, Honeycomb) проще
Больше по теме
Часто задаваемые вопросы
OTel или vendor-specific SDK (Datadog APM)?
OTel: vendor-neutral, migrate backends легко. Datadog APM: deeper integration но vendor lock. Для new projects — OTel, для Datadog-shop — native.
Traces vs Metrics vs Logs?
Traces: request flow через services. Metrics: aggregated numbers (CPU, requests/sec). Logs: discrete events. OTel unifies все три.
Cost?
Self-host Grafana Tempo (free) + S3 storage ~$10/мес для small app. Datadog $15/hostmo. Honeycomb $70+/мес pro tier.
Monitor endpoint?
<a href="/check">Enterno HTTP checker</a> для backend health. <a href="/monitors">Scheduled monitoring</a> для uptime SLA.