OpenTelemetry

01Երեք signal-ները և ինչպես են դրանք կապված

Telemetry-ն գալիս է երեք հիմնական signal-ով։ Trace-ը մեկ request-ի պատմությունն է․ այն span-երի ծառ է, որտեղ յուրաքանչյուր span աշխատանքի մեկ միավոր է (HTTP handler, SQL query, payment API-ի կանչ)՝ սկզբի ժամանակով, տևողությամբ, status-ով և attribute-ներով, ինչպես http.route-ը կամ db.system-ը։ Metric-ները ժամանակի ընթացքում ագրեգացված թվային չափումներ են՝ request-ների հաճախականություն, error rate, latency histogram-ներ, queue-ի խորություն, հիշողություն։ Դրանք էժան է պահել, և հիանալի են dashboard-ների ու alert-ների համար։ Log-երը event-ների timestamp-ով գրառումներ են։ OpenTelemetry-ի ուժը correlation-ն է․ span-ի ներսում գրված log-երը կրում են նրա trace ID-ն և span ID-ն, իսկ metric-ները կարող են կրել exemplar-ներ, որոնք հղում են օրինակելի trace-երին։ Այսպիսով, p95 latency-ի alert-ը քեզ տանում է դանդաղ trace-ի, իսկ trace-ը՝ ճշգրիտ log տողերի։ Trace-երը, metric-ները և log-երը specification-ում stable են, իսկ profiling-ը ավելացվում է որպես չորրորդ signal։

• Trace = span-երի ծառ մեկ request-ի համար։
• Metric-ներ = էժան ագրեգատներ alert-ների և dashboard-ների համար։
• Log-եր = event-ներ, որոնք կապված են trace ID-ով և span ID-ով։

02Ճարտարապետություն՝ API, SDK, exporter-ներ և Collector

OTel-ը պատասխանատվությունները մաքուր է բաժանում։ API-ն այն է, ինչ library-ները և քո կոդը կանչում են span-եր ստեղծելու և metric-ներ գրանցելու համար․ ինքնին այն ոչինչ չի անում, ուստի library-ները կարող են անվտանգ կախված լինել դրանից։ SDK-ն իրականացումն է, որը կարգավորում ես հավելվածում․ այն որոշում է sampling-ը, տվյալները batch է անում և փոխանցում exporter-ներին։ Exporter-ները տվյալները ուղարկում են դուրս, սովորաբար OTLP-ով (OpenTelemetry Protocol), 4317 port-ով gRPC-ի համար կամ 4318-ով HTTP-ի համար։ Instrumentation library-ները patch են անում հայտնի framework-երը և client-ները (Express, Fastify, Next.js, Laravel, pg, mysql, Redis, HTTP client-ներ)՝ span-եր ավտոմատ ստեղծելու համար։ Collector-ը առանձին service է, որը ստանում է telemetry-ն, մշակում այն (batching, ֆիլտրում, զգայուն attribute-ների հեռացում, sampling) և export անում մեկ կամ մի քանի backend։ Կարող ես այն գործարկել որպես agent յուրաքանչյուր հավելվածի կողքին, որպես կենտրոնական gateway կամ երկուսն էլ։ Resource-ները նկարագրում են, թե ով է ուղարկել տվյալները՝ service.name, service.version, deployment.environment.name։

03Node.js service-ի instrumentation

Node.js-ում ամենաարագ սկիզբը SDK-ն է auto-instrumentations փաթեթով։ Տեղադրիր @opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node և OTLP exporter, ապա փոքր setup ֆայլը բեռնիր հավելվածի կոդից առաջ՝ ES module-ների համար օգտագործելով node --import։ Կարգավորիր ստանդարտ environment variable-ներով, ոչ թե hard-coded արժեքներով, որպեսզի նույն image-ը աշխատի բոլոր միջավայրերում՝ OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_RESOURCE_ATTRIBUTES և OTEL_TRACES_SAMPLER։ Next.js-ն ունի ներկառուցված instrumentation.ts hook և @vercel/otel helper-ը։ Laravel-ը և PHP-ն օգտագործում են OpenTelemetry PHP extension-ը և auto-instrumentation package-ներ։ Սկսիր auto-instrumentation-ից, նայիր իրական trace-երին, ապա custom span-եր ավելացրու միայն կարևոր բիզնես քայլերի շուրջ։

1// instrumentation.mjs: run with  node --import ./instrumentation.mjs server.mjs
2import { NodeSDK } from "@opentelemetry/sdk-node";
3import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
4import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
5import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
6import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
7 
8// Endpoint and service name come from OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_SERVICE_NAME
9const sdk = new NodeSDK({
10  traceExporter: new OTLPTraceExporter(),
11  metricReader: new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }),
12  instrumentations: [getNodeAutoInstrumentations({ "@opentelemetry/instrumentation-fs": { enabled: false } })],
13});
14 
15sdk.start();
16process.on("SIGTERM", () => sdk.shutdown().finally(() => process.exit(0)));

04Custom span-եր և attribute-ներ

Auto-instrumentation-ը ցույց է տալիս HTTP և բազայի կանչերը, բայց ոչ քո բիզնես տրամաբանությունը։ Span ավելացրու իմաստալից քայլերի շուրջ, ինչպես «գնի հաշվարկ», «պաշարի ամրագրում» կամ «invoice PDF-ի գեներացում», և կցիր attribute-ներ, որոնք հետո կօգնեն որոնել՝ order.items_count, tenant.tier, cache.hit։ Տարածված անունների համար հետևիր semantic convention-ներին (http.request.method, db.system.name, messaging.system), որպեսզի backend-երը հասկանան դրանք։ Հիշիր attribute-ների cardinality-ի մասին․ order ID-ն span-ի վրա նորմալ է, քանի որ span-ը մեկ event է, բայց երբեք user ID-ներ կամ ID-ներով URL-ներ մի դիր metric attribute-ների մեջ, որովհետև յուրաքանչյուր եզակի արժեք նոր time series է ստեղծում։ Exception-ները գրանցիր span-ի վրա և դիր error status, որպեսզի ձախողված request-ները հեշտ գտնվեն։ Երբեք գաղտնաբառեր, token-ներ կամ քարտերի ամբողջական համարներ մի դիր attribute-ներում։

1import { trace, SpanStatusCode } from "@opentelemetry/api";
2 
3const tracer = trace.getTracer("checkout");
4 
5export async function placeOrder(cart: { items: unknown[] }) {
6  return tracer.startActiveSpan("checkout.place_order", async (span) => {
7    span.setAttribute("order.items_count", cart.items.length);
8    try {
9      const order = await saveOrder(cart); // pg / HTTP calls become child spans
10      span.setAttribute("order.id", order.id);
11      return order;
12    } catch (err) {
13      span.recordException(err as Error);
14      span.setStatus({ code: SpanStatusCode.ERROR });
15      throw err;
16    } finally {
17      span.end();
18    }
19  });
20}

05Collector-ի գործարկում

Telemetry-ն հավելվածներից ուղիղ vendor ուղարկելը աշխատում է, բայց մեջտեղում Collector-ը քեզ վերահսկողություն է տալիս։ Հավելվածները OTLP-ն արագ ուղարկում են լոկալ Collector և վերադառնում աշխատանքի․ Collector-ը batch, retry և buffer է անում, եթե backend-ը դանդաղ է, ուստի հավելվածդ չի տուժում։ Դա ճիշտ վայրն է միջավայրի attribute-ներ ավելացնելու, health check-երի նման աղմկոտ span-երը հեռացնելու, զգայուն տվյալները մաքրելու և tail sampling կիրառելու համար։ Այն կարող է նաև scrape անել Prometheus metric-ներ և կարդալ log ֆայլեր, ուստի դառնում է քո միակ telemetry pipeline-ը։ Processor-ների և exporter-ների ամբողջական հավաքածուի համար օգտագործիր contrib distribution-ը (otelcol-contrib) կամ OpenTelemetry Collector Builder-ով կառուցիր մինիմալը։ Յուրաքանչյուր pipeline-ում memory_limiter processor-ը միշտ դիր առաջինը, իսկ batch-ը՝ վերջինը, և հետևիր Collector-ի սեփական metric-ներին՝ կորած տվյալների համար։

1# otel-collector.yaml
2receivers:
3  otlp:
4    protocols:
5      grpc: { endpoint: 0.0.0.0:4317 }
6      http: { endpoint: 0.0.0.0:4318 }
7processors:
8  memory_limiter: { check_interval: 1s, limit_percentage: 80, spike_limit_percentage: 20 }
9  attributes/scrub:
10    actions: [{ key: http.request.header.authorization, action: delete }]
11  batch: {}
12exporters:
13  otlphttp: { endpoint: https://otlp.example.com }
14service:
15  pipelines:
16    traces: { receivers: [otlp], processors: [memory_limiter, attributes/scrub, batch], exporters: [otlphttp] }
17    metrics: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlphttp] }

06Tail sampling մեծ մասշտաբով

Tail sampling-ը պահում է ամբողջական trace-եր՝ ելնելով նրանից, թե ինչ է տեղի ունեցել դրանցում, բայց trace-ի span-երը գալիս են շատ service-ներից տարբեր ժամանակներում։ Collector-ը span-երը պահում է հիշողության մեջ որոշման սպասման ժամանակահատվածում (հաճախ 10–30 վայրկյան), ապա գնահատում policy-ները՝ status_code ERROR, latency շեմից բարձր, կոնկրետ attribute-ներ կամ probabilistic տոկոս մնացածի համար։ Մի քանի Collector replica-ի դեպքում մեկ trace-ի բոլոր span-երը պետք է հասնեն նույն instance-ին, ուստի գործարկում ես երկու շերտ՝ agent-ներ կամ առաջին gateway շերտ, որն օգտագործում է load-balancing exporter-ը՝ key արված ըստ trace ID-ի, ապա sampling շերտ։ Հիշողությունը չափիր traffic × սպասման ժամանակ բանաձևով և հետևիր processor-ի dropped-traces metric-ներին։ Հիշիր, որ sample-ից դուրս մնացած trace-երը ազդում են նաև span-երից ստացված metric-ների վրա․ RED metric-ները (rate, errors, duration) գեներացրու spanmetrics connector-ով sampling-ից առաջ, որպեսզի dashboard-ները ճշգրիտ մնան։

1processors:
2  tail_sampling:
3    decision_wait: 15s
4    num_traces: 100000
5    policies:
6      - { name: errors, type: status_code, status_code: { status_codes: [ERROR] } }
7      - { name: slow, type: latency, latency: { threshold_ms: 1000 } }
8      - { name: baseline, type: probabilistic, probabilistic: { sampling_percentage: 5 } }

07Propagation queue-ների և async աշխատանքի միջով

Ավտոմատ propagation-ը ծածկում է սինխրոն HTTP-ն և gRPC-ն։ Ասինխրոն աշխատանքը ուշադրություն է պահանջում։ Երբ job ես publish անում Redis, RabbitMQ կամ Kafka, ակտիվ context-ը ներդրիր message header-ների մեջ, երբ worker-ը վերցնում է այն, extract արա և սկսիր consumer span։ Semantic convention-ները սա մոդելավորում են producer և consumer span kind-երով։ Երկար հետաձգված job-ը դիզայնի հարց է առաջացնում․ արդյո՞ք job-ի span-երը պետք է լինեն այն ստեղծած request-ի child-եր։ Կարճ pipeline-ների համար՝ այո, բայց մեկ ժամ անց աշխատող job-ը տարօրինակ, շատ երկար trace է ստեղծում։ Այլընտրանքը նոր trace-ն է՝ span link-ով դեպի սկզբնական context, ինչը պահպանում է կապը՝ առանց trace-ը ձգելու։ Batch consumer-ները պետք է օգտագործեն link-եր դեպի շատ producer context-ներ։ Baggage-ը կարող է service-ների միջով կրել արժեքներ, ինչպես tenant ID-ն, բայց այն ուղարկվում է յուրաքանչյուր request-ով, ուստի փոքր պահիր և երբեք secret-ներ մի դիր դրա մեջ։

1import { context, propagation, trace } from "@opentelemetry/api";
2 
3// Producer: carry the trace context inside the job payload
4export function withTraceHeaders<T extends object>(payload: T) {
5  const headers: Record<string, string> = {};
6  propagation.inject(context.active(), headers);
7  return { ...payload, otel: headers };
8}
9 
10// Consumer: continue the trace when the job runs
11export function runJob(job: { otel?: Record<string, string> }, work: () => Promise<void>) {
12  const parent = propagation.extract(context.active(), job.otel ?? {});
13  return context.with(parent, () =>
14    trace.getTracer("worker").startActiveSpan("job.process", (span) => work().finally(() => span.end())),
15  );
16}

08Metric-ների դիզայն՝ instrument-ներ, temporality և cardinality

OTel metric-ները օգտագործում են instrument-ներ՝ Counter միայն աճող բաների համար (request-ներ, ուղարկված byte-եր), UpDownCounter աճող և նվազող արժեքների համար (queue-ի չափ, ակտիվ connection-ներ), Histogram բաշխումների համար (latency, payload-ի չափ) և Gauge-ներ ընթացիկ արժեքների համար։ Histogram-ներն են, որ տալիս են p95 և p99․ exponential histogram-ները լավ ճշգրտություն են տալիս ավելի քիչ bucket-ներով։ Temporality-ն կարևոր է export անելիս․ Prometheus-ի ոճի backend-երը սպասում են cumulative արժեքներ, մինչդեռ որոշ vendor-ներ նախընտրում են delta, և exporter-ը կարելի է կարգավորել երկու ձևով էլ։ Cardinality-ն արժեքի հիմնական շարժիչն է․ attribute արժեքների յուրաքանչյուր եզակի համադրություն առանձին time series է։ http.route=/orders/:id-ն նորմալ է, իսկ հում URL-ը՝ /orders/123, աղետ է։ Օգտագործիր view-եր attribute-ները հեռացնելու կամ վերանվանելու և histogram-ի bucket-ները փոխելու համար՝ առանց instrumentation կոդին դիպչելու։

09Overhead, անվտանգություն և աստիճանական ներդրում

Instrumentation-ը անվճար չէ, բայց սովորաբար փոքր է՝ CPU-ի մի քանի տոկոս, հիմնականում span-եր ստեղծելուց և export անելուց։ Այն ցածր պահիր batch span processor-ով (երբեք simple processor-ը production-ում), sampling-ով և աղմկոտ instrumentation-ների անջատմամբ, ինչպես file system-ի կամ DNS-ի span-երը։ Export-ը երբեք չպետք է block անի request-ները․ եթե backend-ը անջատված է, SDK-ն տվյալները դեն է նետում իր queue-ի լցվելուց հետո՝ հավելվածը դանդաղեցնելու փոխարեն։ Զգայուն տվյալները մաքրիր երկու մակարդակում՝ խուսափիր դրանք կոդում հավաքելուց և Collector-ում հեռացրու header-ները, query string-երը և SQL պարամետրերը։ Ներդրիր service առ service՝ սկսելով edge-ից և ամենակրիտիկական ճանապարհից, և համեմատիր latency-ն առաջ և հետո։ Collector-ին վերաբերվիր որպես production ենթակառուցվածքի՝ health check-եր, resource limit-ներ, հորիզոնական scaling և alert-ներ կորած span-երի վրա։