Có một buổi chiều mình ngồi nhìn dashboard: endpoint /checkout chậm lên 4 giây, nhưng log của từng service đều bảo "mình xử lý có 80ms". Cộng lại không ra 4 giây. Thời gian đi đâu mất thì không ai biết. Đó là lúc mình thấy log thôi là chưa đủ, cần trace.

Trace, span và context là gì (nói ngắn)

Một trace là hành trình của một request đi qua nhiều service. Mỗi bước trong hành trình là một span: có tên, thời điểm bắt đầu, thời lượng và vài thuộc tính. Các span nối nhau bằng quan hệ cha-con, và nối giữa các service nhờ header traceparent (chuẩn W3C Trace Context) gắn vào HTTP request.

Sợi chỉ sáng đi qua ba hộp server Ảnh: một sợi chỉ sáng xuyên qua ba hộp server xếp chồng, mỗi hộp là một span trong cùng một trace — đây là hình dung nhanh về cách header traceparent giữ request liền mạch giữa các service — ảnh minh hoạ do AI tạo (Grok Imagine)

OpenTelemetry (OTel) là bộ chuẩn + SDK trung lập với nhà cung cấp. Mình viết code một lần, muốn đẩy sang Jaeger, Tempo hay dịch vụ trả phí thì đổi endpoint, không phải sửa code.

Bật tracing cho Node.js trong 20 dòng

Cài vài package:

npm i @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

Tạo file tracing.ts (đây là chỗ nhiều người mắc bẫy, lát nói):

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? 'orders-api',
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', async () => {
  await sdk.shutdown(); // flush span còn trong buffer
  process.exit(0);
});

Chạy app với file này nạp trước mọi thứ khác: node --import ./tracing.js server.js. Auto-instrumentation hoạt động bằng cách vá các module như http, pg, express lúc chúng được import. Nếu tracing nạp sau khi express đã được require thì không có span nào hết, và cũng không báo lỗi gì. Mình mất gần nửa buổi mới nhận ra điều này.

Phần SIGTERM có lý do: span được gom theo lô rồi mới gửi. Tắt app đột ngột là mất lô cuối, y như chuyện mình đã kể ở bài graceful shutdown Node.js.

Tự tạo span cho đoạn code của mình

Auto-instrumentation chỉ thấy HTTP, DB, Redis. Còn logic nghiệp vụ nằm giữa thì phải tự đánh dấu:

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('orders');

export async function calcShipping(orderId: string) {
  return tracer.startActiveSpan('calcShipping', async (span) => {
    try {
      span.setAttribute('order.id', orderId);
      const fee = await fetchCarrierQuote(orderId);
      span.setAttribute('shipping.fee', fee);
      return fee;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end(); // quên dòng này là span treo mãi
    }
  });
}

startActiveSpan gắn span vào context hiện tại, nên các lệnh gọi bên trong tự thành span con. Cơ chế này chạy trên AsyncLocalStorage, cùng thứ mình giải thích ở bài AsyncLocalStorage: context theo request.

Kính lúp soi một đoạn trên thanh thời gian Ảnh: kính lúp soi vào thanh thời gian, một đoạn được tô xanh ngọc là span chậm nhất — đúng cảnh mình ngồi đọc waterfall trong Jaeger để tìm 4 giây biến mất ở đâu — ảnh minh hoạ do AI tạo (Grok Imagine)

Đọc waterfall: 4 giây nằm ở đâu

Quay lại vụ /checkout. Sau khi bật trace, waterfall hiện ra rõ ràng: service orders gọi service pricing, pricing gọi một API đối tác, và API đó chờ trọn 3,5 giây trước khi timeout rồi mới retry. Từng service log "80ms" vì chúng chỉ đo phần việc của mình, không đo thời gian chờ downstream. Không có trace thì chẳng ai thấy được bức tranh ghép.

Cái này liên quan thẳng tới chuyện timeout mình từng gặp ở bài fetch Node.js treo vô hạn: trace cho bạn thấy chỗ treo, còn timeout là thứ chặn nó lại.

Sampling: đừng gửi 100% trên production

Mỗi request sinh ra hàng chục span. Với traffic lớn, gửi hết vừa tốn tiền vừa tốn CPU. Cấu hình sampling theo tỉ lệ:

import { ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';

const sdk = new NodeSDK({
  // ...
  sampler: new ParentBasedSampler({
    root: new TraceIdRatioBasedSampler(0.1), // giữ 10%
  }),
});

ParentBased quan trọng: service đầu chuỗi đã quyết định giữ trace thì các service sau giữ theo, nên bạn không nhận về những trace bị cụt giữa chừng.

Phễu lọc chỉ cho vài chấm sáng đi qua Ảnh: chiếc phễu chỉ cho một ít chấm sáng đi qua còn phần lớn mờ dần — tượng trưng cho sampling 10% trên production để giảm chi phí mà vẫn đủ mẫu — ảnh minh hoạ do AI tạo (Grok Imagine)

Nhược điểm của sampling theo tỉ lệ: trace lỗi hiếm có thể rơi mất. Muốn "giữ mọi trace lỗi hoặc chậm" thì cần tail sampling ở OTel Collector, phức tạp hơn nhiều, mình khuyên làm sau khi đã chạy ổn bản đơn giản.

Vài điều rút ra

  • Nạp tracing trước mọi import khác, nếu không sẽ im lặng không có span.
  • Luôn sdk.shutdown() khi nhận SIGTERM để khỏi mất span cuối.
  • Đặt tên span theo thao tác (calcShipping), đừng nhét ID vào tên. ID để vào attribute, nếu không backend sẽ nổ cardinality.
  • Đừng gắn dữ liệu nhạy cảm (token, email) vào attribute, vì trace thường được nhiều người xem.

Nếu service của bạn đang có log mà vẫn không trả lời được "request này chậm ở đâu", thử bật OTel cho đúng một service trước, xem waterfall một buổi rồi hẵng quyết định mở rộng.

📋 Phụ lục thuật ngữ

Thuật ngữ Giải thích ngắn
Trace Toàn bộ hành trình một request đi qua nhiều service
Span Một bước trong trace, có tên, thời lượng, thuộc tính
traceparent Header chuẩn W3C để truyền trace ID giữa các service
Instrumentation Đoạn code tự động/ thủ công tạo span
Exporter Thành phần gửi span tới backend (Jaeger, Tempo...)
Sampling Chỉ giữ một phần trace để giảm chi phí
Collector Dịch vụ trung gian nhận, xử lý, chuyển tiếp dữ liệu OTel

Xem các bài viết khác