자동 계측: 코드 변경 없이 관찰 가능
L'자기 계측 분산된 트랙을 추가할 수 있는 기술, 애플리케이션과 관련된 측정항목 및 로그 소스 코드 한 줄도 변경하지 않고. 잘 알려진 라이브러리 및 프레임워크(HTTP 클라이언트, 데이터베이스 드라이버, 메시지 브로커) 범위, 속성 및 컨텍스트 전파를 자동으로 추가합니다.
많은 조직에서 자체 계측은 이상적인 출발점입니다. OpenTelemetry 채택. 한번의 투자로 서비스 간 흐름에 대한 즉각적인 가시성을 제공합니다. 최소한 몇 분 안에 완전한 분산 트랙을 얻을 수 있습니다.
이 기사에서는 세 가지 주요 생태계에서 자체 계측이 어떻게 작동하는지 분석합니다. 자바 (에이전트 기반), 파이썬 (원숭이 패치) e Node.js (후크 필요) 각 접근 방식의 이점과 한계를 비교합니다.
이 기사에서 배울 내용
- 기술 수준에서 자체 계측이 작동하는 방식
- Spring Boot 및 일반 Java 애플리케이션을 위한 Java 에이전트 설정
- Django, Flask 및 FastAPI용 Python 자동 계측
- Express, Fastify 및 NestJS를 위한 Node.js 자동 계측
- 제로 코드 접근 방식의 이점과 제한 사항
- 수동 계측으로 전환해야 하는 경우
자동 계측 작동 방식
자동 계측에서는 언어별 메커니즘을 사용하여 호출을 가로챕니다. 라이브러리에 투명하게 원격 측정을 추가합니다. 세 가지 주요 메커니즘은 다음과 같습니다.
언어 자동 계측 메커니즘
| 언어 | 기구 | 작동 방식 |
|---|---|---|
| 자바 | Java 에이전트(바이트코드 조작) | 다음을 통해 런타임 시 바이트코드 편집 -javaagent, 라이브러리 메서드를 가로챕니다. |
| 파이썬 | 원숭이 패치 | 라이브러리 함수를 런타임 시 계측된 래퍼로 대체합니다. |
| Node.js | 후크 필요 / 후크 가져오기 | 모듈 로드를 가로채고 내보낸 함수 래핑 |
| .그물 | CLR 프로파일러/시작 후크 | 어셈블리가 로드될 때 CLR API를 사용하여 계측 삽입 |
Java: 에이전트 기반 자동 계측
OpenTelemetry의 Java 에이전트는 가장 성숙하고 완벽합니다. 100개 이상의 라이브러리와 프레임워크를 지원합니다. 서블릿 API에서 Spring Boot로, JDBC에서 Hibernate로, gRPC에서 Kafka로. 추가하면 활성화됩니다. JVM에 대한 단일 플래그이며 코드나 종속성을 변경할 필요가 없습니다.
# Download dell'agent Java OpenTelemetry
curl -L -o opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
# Avvio dell'applicazione con l'agent
java -javaagent:./opentelemetry-javaagent.jar \
-Dotel.service.name=order-service \
-Dotel.exporter.otlp.endpoint=http://otel-collector:4317 \
-Dotel.exporter.otlp.protocol=grpc \
-Dotel.traces.exporter=otlp \
-Dotel.metrics.exporter=otlp \
-Dotel.logs.exporter=otlp \
-Dotel.resource.attributes=deployment.environment=production \
-jar order-service.jar
# Oppure via variabili d'ambiente
export JAVA_TOOL_OPTIONS="-javaagent:./opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="order-service"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
java -jar order-service.jar
# Dockerfile con agent OTel per applicazione Spring Boot
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
# Copiare l'agent OTel
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar /app/opentelemetry-javaagent.jar
# Copiare l'applicazione
COPY target/order-service.jar /app/order-service.jar
# Configurazione OTel via variabili d'ambiente
ENV JAVA_TOOL_OPTIONS="-javaagent:/app/opentelemetry-javaagent.jar"
ENV OTEL_SERVICE_NAME="order-service"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "order-service.jar"]
Python: Monkey-Patching을 사용한 자동 계측
Python 자동 계측에서는 원숭이 패치를 사용하여 라이브러리 함수를 대체합니다.
계측된 래퍼를 사용합니다. 설치에는 두 단계가 필요합니다. 패키지 설치
자동 계측 및 명령으로 애플리케이션 시작 opentelemetry-instrument.
# Installazione dei pacchetti OpenTelemetry per Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
# Installare automaticamente tutte le librerie di instrumentazione
# per le dipendenze trovate nell'ambiente
opentelemetry-bootstrap -a install
# Questo installa automaticamente i pacchetti come:
# opentelemetry-instrumentation-flask
# opentelemetry-instrumentation-django
# opentelemetry-instrumentation-requests
# opentelemetry-instrumentation-sqlalchemy
# opentelemetry-instrumentation-psycopg2
# ... e altri in base alle dipendenze trovate
# Avvio dell'applicazione con auto-instrumentation
export OTEL_SERVICE_NAME="user-service"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_PYTHON_LOG_CORRELATION="true"
opentelemetry-instrument python app.py
# Per Flask
opentelemetry-instrument flask run --host=0.0.0.0
# Per FastAPI con uvicorn
opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000
# Per Django
opentelemetry-instrument python manage.py runserver
Node.js: 후크 필요를 사용한 자동 계측
Node.js 자동 계측은 다음을 통해 모듈 로딩을 차단합니다.
require 후크(CommonJS) 또는 import 후크(ESM). 필요하다
등록코드가 실행되었다는 것 전에 수입의
계측할 모듈의
# Installazione dei pacchetti OpenTelemetry per Node.js
npm install @opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-grpc \
@opentelemetry/exporter-metrics-otlp-grpc
# Avvio con auto-instrumentation via variabili d'ambiente
export OTEL_SERVICE_NAME="api-gateway"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os,process"
# Per CommonJS
node --require @opentelemetry/auto-instrumentations-node/register app.js
# Per ESM (Node.js 18.19+)
node --import @opentelemetry/auto-instrumentations-node/register app.mjs
// instrument.js - Setup programmatico per Node.js (alternativa)
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const sdk = new NodeSDK({
traceExporter: new OTLPTraceExporter({
url: 'http://otel-collector:4317'
}),
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: 'http://otel-collector:4317'
}),
exportIntervalMillis: 60000
}),
instrumentations: [
getNodeAutoInstrumentations({
// Configurazione specifica per librerie
'@opentelemetry/instrumentation-http': {
ignoreIncomingPaths: ['/health', '/ready']
},
'@opentelemetry/instrumentation-express': {
enabled: true
},
'@opentelemetry/instrumentation-pg': {
enhancedDatabaseReporting: true
}
})
]
});
sdk.start();
process.on('SIGTERM', () => {
sdk.shutdown().then(() => process.exit(0));
});
Kubernetes의 구성
Kubernetes 환경에서는 다음을 통해 자동 계측을 중앙에서 관리할 수 있습니다. 는OpenTelemetry 연산자, 에이전트를 Pod에 자동으로 주입합니다. Dockerfile이나 배포 매니페스트를 수정하지 않고 주석을 통해.
# Configurazione OpenTelemetry Operator per Kubernetes
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: otel-instrumentation
namespace: ecommerce
spec:
exporter:
endpoint: http://otel-collector.observability:4317
propagators:
- tracecontext
- baggage
sampler:
type: parentbased_traceidratio
argument: "0.25"
java:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
python:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-python:latest
nodejs:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-nodejs:latest
---
# Annotare il deployment per attivare l'auto-instrumentation
apiVersion: apps/v1
kind: Deployment
metadata:
name: order-service
namespace: ecommerce
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/inject-java: "otel-instrumentation"
spec:
containers:
- name: order-service
image: order-service:latest
자체 계측 언어 라이브러리
- 자바(100+): Spring MVC/WebFlux, JDBC, Hibernate, Kafka, gRPC, Jedis, Lettuce, OkHttp, Apache HttpClient
- 파이썬(40+): Django, Flask, FastAPI, 요청, urllib3, SQLAlchemy, psycopg2, Redis, Celery
- Node.js(30+): Express, Fastify, Koa, HTTP/HTTPS, pg, mysql2, Redis, MongoDB, gRPC
- .NET(20+): ASP.NET Core, HttpClient, SqlClient, EntityFramework, gRPC, MassTransit
자체 계측의 한계
자체 계측은 강력하지만 기대를 피하기 위해 이해해야 할 중요한 제한 사항이 있습니다. 비현실적이다. 수동 계측을 완전히 대체하지는 않지만 보완합니다.
자가 계측만으로는 충분하지 않은 경우
보이지 않는 비즈니스 로직: 자동 계측은 라이브러리 호출을 추적합니다.
(HTTP, DB, 캐시)이지만 서비스 내부 로직을 추적할 수는 없습니다. 주문에 500ms가 걸리는 경우
비즈니스 검증에 400ms가 소요되므로 외부 호출 범위만 볼 수 있습니다.
맞춤 속성이 없습니다.: 다음과 같은 비즈니스 관련 속성은 추가할 수 없습니다.
order.id, user.tier, payment.method 수동 코드 없이.
비즈니스 지표: 맞춤형 카운터, 히스토그램 및 게이지에는 다음이 필요합니다.
항상 수동 SDK입니다. 자동 계측은 표준 기술 측정항목만 생성합니다.
잠재적인 오버헤드: 고성능 시나리오에서는 자동 계측
평가해야 하는 측정 가능한 대기 시간(일반적으로 1~5%)을 추가할 수 있습니다.
하이브리드 접근 방식: 자동 + 수동
권장 접근 방식 e 잡종: 자가 계측부터 시작하여 획득 즉각적인 가시성을 확보한 다음 비즈니스 컨텍스트가 필요한 곳에 수동 계측을 추가합니다. 자동 계측으로 인프라 호출, 수동 계측을 위한 범위 생성 도메인별 범위 및 속성이 풍부해집니다.
결론 및 다음 단계
자체 계측은 분산 시스템에서 관찰 가능성을 달성하는 가장 빠른 방법입니다. 몇 가지 명령이나 Kubernetes 주석을 사용하면 전체에 걸친 완전한 분산 추적을 가질 수 있습니다. HTTP, 데이터베이스, 캐시 및 메시징. 각 언어에는 고유한 메커니즘이 있습니다(Java 에이전트, 원숭이 패치 Python에는 Node.js 후크가 필요하지만 결과는 동일합니다. 코드가 없는 표준 원격 분석입니다.
주요 제한 사항은 비즈니스 컨텍스트가 부족하다는 것입니다. 자체 계측이 응답합니다. "어떤 서비스가 어떤 서비스를 호출했는지"에 대한 정보는 있지만 "어떤 주문, 어느 고객으로부터, 어떤 서비스를 통해 호출되었는지"에 대한 정보는 아닙니다. 지불 방법". 이를 위해서는 SDK를 사용한 수동 계측이 필요합니다.
다음 기사에서는SDK 수동 계측, 만드는 법을 배우다 커스텀 범위, 비즈니스 속성 추가, 예외 로그, 측정항목 정의 OpenTelemetry API를 사용하여 사용자 정의합니다.