Node.js에서 OpenTelemetry 메트릭 수집하기: HTTP 계측과 OTLP
OpenTelemetry JavaScript SDK로 Express HTTP와 업무 메트릭을 계측하고, 요청 건수와 OTLP/HTTP Protobuf 전송을 로컬에서 확인합니다.
주문 API가 503을 반환하기 시작해도 주문 생성 건수는 거의 그대로일 수 있습니다. HTTP 소요 시간 히스토그램에는 실패한 응답도 기록됩니다. 업무 카운터는 애플리케이션이 주문을 받아들였을 때만 늘어납니다. 두 값을 함께 보면 트래픽 변화와 주문 결과의 변화를 구분할 수 있습니다.
이 글에서는 Express, OpenTelemetry JavaScript Metrics SDK와 로컬 Collector를 사용합니다. SDK가 메트릭을 OTLP/HTTP 배치로 보냅니다. Prometheus가 /metrics를 스크레이프하게 하려면 별도의 Node.js Prometheus 모니터링 가이드를 참고하세요.
로컬 OTLP 수신기 실행하기
다음 설정을 collector.yaml에 저장하고 otelcol-contrib --config=collector.yaml을 실행합니다. HTTP 수신기는 루프백 주소에서 대기하며, debug 익스포터가 수신한 메트릭을 로그에 출력합니다.
receivers:
otlp:
protocols:
http:
endpoint: 127.0.0.1:14318
exporters:
debug:
verbosity: detailed
service:
pipelines:
metrics:
receivers: [otlp]
exporters: [debug]
Node.js 22.16.0, Express 5.3.0, OpenTelemetry Metrics SDK 3.1.1, HTTP 계측과 익스포터 0.301.1, Collector Contrib 0.165.0으로 확인한 예제입니다. 이 OpenTelemetry 패키지 조합은 Node.js 22.15.0 이상이 필요합니다. 빈 디렉터리에서 의존성을 설치합니다.
npm init -y
npm install --save-exact express@5.3.0 \
@opentelemetry/api@1.10.0 @opentelemetry/resources@3.1.1 \
@opentelemetry/sdk-metrics@3.1.1 \
@opentelemetry/instrumentation@0.301.1 \
@opentelemetry/instrumentation-http@0.301.1 \
@opentelemetry/exporter-metrics-otlp-proto@0.301.1
Express를 불러오기 전에 HTTP 계측 등록하기
자동 계측과 직접 작성한 계측에 같은 MeterProvider를 사용합니다. 주기적으로 수집하는 Reader가 OTLP/HTTP 익스포터에 메트릭을 넘기고, 익스포터가 Protobuf로 전송합니다. 코드에 설정된 Collector 주소는 로컬 검증용입니다.
코드를 checkout.cjs에 저장하고 node checkout.cjs를 실행합니다. 프로그램이 합성 요청 두 건을 보내고 응답을 모두 읽은 뒤 201과 503을 출력합니다. 테스트 서버를 닫고 shutdown()을 호출하면 마지막 메트릭 배치를 수집해 전송합니다.
const { once } = require('node:events');
const { MeterProvider, PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const exporter = new OTLPMetricExporter({
url: 'http://127.0.0.1:14318/v1/metrics',
});
const provider = new MeterProvider({
resource: resourceFromAttributes({ 'service.name': 'checkout-node' }),
readers: [new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 30_000 })],
});
const unregister = registerInstrumentations({
meterProvider: provider,
instrumentations: [new HttpInstrumentation()],
});
const express = require('express');
const app = express();
const meter = provider.getMeter('example.com/checkout');
const created = meter.createCounter('orders.created', { unit: '{order}' });
const inFlight = meter.createUpDownCounter('orders.inflight', { unit: '{request}' });
const depth = meter.createGauge('orders.queue.depth', { unit: '{order}' });
const duration = meter.createHistogram('orders.process.duration', {
unit: 's',
advice: { explicitBucketBoundaries: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 5] },
});
app.post('/orders', (req, res) => {
const started = performance.now();
const attributes = { route: '/orders' };
inFlight.add(1, attributes);
res.once('close', () => inFlight.add(-1, attributes));
res.once('finish', () => {
duration.record((performance.now() - started) / 1000, attributes);
});
depth.record(2);
if (req.query.fail === '1') {
res.sendStatus(503);
return;
}
created.add(1, { channel: 'app' });
res.sendStatus(201);
});
async function run() {
const server = app.listen(0, '127.0.0.1');
try {
await once(server, 'listening');
const { port } = server.address();
for (const suffix of ['', '?fail=1']) {
const response = await fetch(`http://127.0.0.1:${port}/orders${suffix}`, {
method: 'POST',
signal: AbortSignal.timeout(5_000),
});
await response.arrayBuffer();
console.log(response.status);
}
} finally {
try {
if (server.listening) {
await new Promise((resolve, reject) => {
server.close(error => error ? reject(error) : resolve());
});
}
} finally {
try {
await provider.shutdown();
} finally {
unregister();
}
}
}
}
run().catch(error => {
console.error(error);
process.exitCode = 1;
});
배포 환경에서도 계측 대상 모듈을 불러오기 전에 계측을 등록합니다. CommonJS에서는 --require로 초기화 파일을 먼저 불러올 수 있습니다. ESM은 실행 환경과 배포 방식에 맞는 SDK 로더 문서를 확인하세요. TypeScript 타입은 계측을 불러오는 순서를 바꾸지 않습니다. Node.js OpenTelemetry 설정(영어)
자동 계측된 HTTP 히스토그램부터 확인하기
Collector 출력에서 service.name=checkout-node와 http.server.request.duration을 찾습니다. 지정한 HTTP 계측 버전에서는 히스토그램 단위가 s이고 두 상태 코드의 Count는 각각 1입니다. 같은 속성 조합에서 Count는 기록된 HTTP 요청 수를 나타냅니다. 업무 카운터 orders.created의 channel=app에는 주문 한 건이 기록됩니다.
라우트 속성이 자동으로 붙는지는 계측과 프레임워크 조합에 따라 다릅니다. 이 예제의 자동 HTTP 히스토그램에는 http.route가 없습니다. 업무 처리 시간 히스토그램에는 고정 라우트 /orders를 사용합니다. /orders/:id처럼 파라미터가 있는 라우트에서는 실제로 매칭된 템플릿을 쓰고 전체 URL과 요청 ID는 메트릭 속성에 넣지 않습니다. 예전 HTTP 계측은 이름과 단위가 다를 수 있으니 기존 대시보드를 재사용하기 전에 실제 출력을 확인합니다. HTTP 계측 패키지 · HTTP 메트릭 규약
측정하려는 값에 맞춰 계측기 고르기
| 알고 싶은 것 | 계측기 | 예제의 기록 방식 |
|---|---|---|
| 주문이 몇 건 생성됐는가 | Counter | 주문이 생성되면 0 이상의 증가분을 더합니다. |
| 처리 중인 요청은 몇 건인가 | UpDownCounter | 들어올 때 더하고 연결 종료나 응답 완료 시 같은 속성으로 뺍니다. |
| 지금 큐에 몇 건이 쌓였는가 | Gauge | 관측값을 기록합니다. 예제에서는 2를 사용합니다. 수집할 때 큐를 읽으려면 ObservableGauge의 addCallback(result => result.observe(value))를 쓰고 콜백에서 현재 값을 가져옵니다. |
| 핸들러가 처리하는 데 몇 초가 걸렸는가 | Histogram | 응답의 finish 이벤트에서 경과 시간을 초 단위로 기록합니다. 두 상태 코드가 모두 포함됩니다. |
finish는 응답 데이터가 전송을 위해 운영체제에 넘어간 시점입니다. 예제는 핸들러 시작부터 서버 쪽 시간을 측정합니다. 연결이 일찍 끊겨도 close에서 처리 중 건수를 차감할 수 있습니다. 업무 처리 시간 히스토그램에는 finish에 도달한 응답만 기록합니다. Node.js 응답 이벤트(영어)
예제에는 250ms 버킷 경계가 있습니다. 여러 복제본을 함께 집계할 때는 버킷 구성을 맞추고 알림 기준 근처에 경계를 둡니다. 복제본에는 같은 서비스 이름을 사용하되, 프로세스별 비교가 필요하면 서로 다른 service.instance.id를 설정합니다. PM2 클러스터도 마찬가지입니다.
같은 메트릭을 Guance로 보내기
DataKit의 OpenTelemetry 입력을 활성화한 뒤 익스포터가 실제 OTLP 수신 주소를 가리키게 합니다. 문서의 DataKit 기본 HTTP 포트는 9529이며 메트릭 경로는 /otel/v1/metrics입니다. 이 예제의 로컬 Collector는 별도 포트에서 /v1/metrics를 사용합니다. 배포 환경에 맞게 TLS와 인증을 설정합니다. DataKit OpenTelemetry 입력 설정
정해진 수만큼 요청을 보내고 Guance가 받은 메트릭 이름, 단위, 속성과 히스토그램 형식을 확인한 뒤 차트와 모니터를 만듭니다. 주문 수와 HTTP 상태별 건수를 함께 확인하면 전체 주문량이 그대로여도 실패가 늘어났는지 알 수 있습니다. Guance 모니터 설정
운영할 때 자주 묻는 질문
트레이스를 내보내지 않고 메트릭만 수집할 수 있나요? 가능합니다. 예제는 메트릭 Reader만 설정합니다. 이미 NodeSDK를 사용하는 앱에서는 기존 설정에 Reader를 추가하고 같은 HTTP 계측을 두 번 등록하지 않도록 합니다.
자동 메트릭과 직접 추가한 메트릭이 겹칠 수 있나요? 같은 대상을 측정하면 겹칠 수 있습니다. 무엇을 측정하는지 드러나는 이름을 쓰고 수신기에서 메트릭의 식별 정보, 단위, 속성을 확인합니다. 업무 카운터와 자동 HTTP 히스토그램의 집계 대상이 다르면 값도 달라집니다.
얼마나 자주 내보내나요? Reader에서 별도로 설정하지 않으면 기본값은 60초입니다. 예제는 실행 중 30초 간격을 사용하고 종료 시에도 수집합니다. 알림의 평가 구간과 트래픽, 수신기 처리 여유를 보고 결정합니다.
프로세스를 종료해도 메트릭이 전송되나요? 운영 환경에서는 종료 신호를 처리해 새 요청을 받지 않고, 유예 시간 안에 진행 중인 작업을 마친 뒤 SDK 종료를 기다립니다. 강제 종료, 전송 시간 초과, 수신 오류가 있으면 마지막 배치가 유실될 수 있습니다.
