自動インストルメンテーション: コードを変更せずに可観測性を実現
L'自己計測 分散トラックを追加できる技術、 アプリケーションに関連するメトリクスとログ ソースコード行を変更せずに。 これは、よく知られたライブラリやフレームワーク (HTTP クライアント、データベース ドライバー、 メッセージ ブローカー)、スパン、属性、コンテキストの伝播を自動的に追加します。
多くの組織にとって、自己計測は理想的な出発点です。 OpenTelemetryの採用。 1 回の投資でサービス間のフローを即座に可視化します。 最小限で、完全な分散トラックをわずか数分で入手できます。
この記事では、次の 3 つの主要なエコシステムで自己計測がどのように機能するかを分析します。 ジャワ (エージェントベース)、 パイソン (モンキーパッチング) e Node.js (フックが必要)、各アプローチの利点と制限を比較します。
この記事で学べること
- 技術レベルでの自己計測の仕組み
- Spring Boot および一般的な Java アプリケーション用の Java エージェントのセットアップ
- Django、Flask、および FastAPI の Python 自動インストルメンテーション
- Express、Fastify、NestJS の Node.js 自動インストルメンテーション
- ゼロコードアプローチの利点と制限
- 手動計装に切り替える時期
自動計測の仕組み
自動インスツルメンテーションは言語固有のメカニズムを使用して呼び出しをインターセプトします ライブラリに追加し、透過的にテレメトリを追加します。主なメカニズムは次の 3 つです。
言語の自動計測メカニズム
| 言語 | 機構 | 仕組み |
|---|---|---|
| ジャワ | 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: モンキーパッチによる自動インスツルメンテーション
Python の自動インスツルメンテーションは、モンキーパッチを使用してライブラリ関数を置き換えます
インストルメント化されたラッパーを使用します。インストールには 2 つの手順が必要です。 パッケージをインストールする
自動インスツルメンテーションを実行し、コマンドでアプリケーションを起動します。 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: Require フックを使用した自動インストルメンテーション
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 オペレーター、エージェントをポッドに自動的に挿入します。 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
言語用の自己実装ライブラリ
- Java (100+): Spring MVC/WebFlux、JDBC、Hibernate、Kafka、gRPC、Jedis、Lettuce、OkHttp、Apache HttpClient
- Python (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、キャッシュ) ですが、サービスの内部ロジックをトレースすることはできません。注文に500ミリ秒かかる場合
ビジネス検証に 400 ミリ秒が費やされると、外部呼び出しの範囲のみが表示されます。
カスタム属性がありません: 次のようなビジネス関連の属性を追加することはできません。
order.id, user.tier, payment.method マニュアルコードなし。
ビジネス指標: カスタムカウンター、ヒストグラム、ゲージが必要です
常に手動 SDK を使用します。自動インスツルメンテーションは、標準的な技術指標のみを生成します。
潜在的なオーバーヘッド: 高パフォーマンスのシナリオでは、自動インストルメンテーション
測定可能な遅延 (通常 1 ～ 5%) が追加される可能性があるため、評価する必要があります。
ハイブリッドアプローチ: 自動 + 手動
推奨されるアプローチ ハイブリッド: 取得する自己計測から開始します すぐに可視化できるため、ビジネス コンテキストが必要な場合には手動の計測を追加できます。 自動インスツルメンテーションによりインフラストラクチャ コールのスパンが作成され、手動インスツルメンテーションが行われます。 ドメイン固有のスパンと属性で強化します。
結論と次のステップ
自己計測は、分散システムで可観測性を実現する最速の方法です。 いくつかのコマンドまたは Kubernetes アノテーションを使用すると、複数の範囲にわたる完全な分散トレースを取得できます。 HTTP、データベース、キャッシュ、メッセージング。各言語には独自のメカニズム (Java エージェント、モンキーパッチ) があります。 Python、Node.js のフックが必要) ですが、結果は同じで、コードなしの標準テレメトリです。
主な制限は、ビジネス コンテキストが欠如していることです。自己計測が応答する 「どのサービスがどのサービスに電話をかけたか」には関係しますが、「どの注文、どの顧客から、どの相手に電話をかけたか」には関係ありません。 支払い方法」。このためには、SDK を使用した手動のインストルメンテーションが必要です。
次の記事では、SDK 手動インストルメンテーション、創造することを学ぶ カスタム スパン、ビジネス属性の追加、例外のログ記録、メトリクスの定義 OpenTelemetry API を使用してカスタム。