コード不要の計装は、起動時にエージェントをアプリケーションにアタッチします。エージェントは、HTTP のサーバーとクライアント、データベースドライバー、メッセージキューなどの一般的なライブラリにパッチを当て、ソースを変更せずに、トレース、メトリクス、ログを生成します。設定は、標準の OTEL_* 環境変数と、いくつかの言語固有のものなので、全体のセットアップは、Dockerfile の 1 行と、いくつかの変数だけです。このガイドでは、Java、Python、Node.js を扱います。

前提：データの送り先

Collector をリッスンさせておきます。たとえば Docker Compose のガイドのもので、otel-collector:4318（HTTP）または :4317（gRPC）です。以下のすべての例は、OTEL_EXPORTER_OTLP_ENDPOINT でそれに向けます。

Java

エージェントの JAR を 1 度ダウンロードし、-javaagent でアタッチします。

curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=checkout \
     -jar myapp.jar

コンテナでは、環境変数が好まれることが多く、JAVA_TOOL_OPTIONS がフラグを運ぶことで、entrypoint を変更せずに済みます。

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY myapp.jar .
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/<version>/opentelemetry-javaagent.jar /otel/opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/otel/opentelemetry-javaagent.jar"
CMD ["java", "-jar", "myapp.jar"]

ビルドを再現可能にするために、latest ではなく、ダウンロード URL のエージェントのバージョンを固定します。その後、実行時に設定します。

OTEL_SERVICE_NAME=checkout \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging \
java -jar myapp.jar

エージェントは、3 つの方法で設定できます。システムプロパティ（-Dotel.service.name=...）、環境変数、または OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/file.properties（または -Dotel.javaagent.configuration-file）で参照されるプロパティファイルです。設定が多い場合は、プロパティファイルを Git に保管してください。エージェント自体のデバッグには OTEL_JAVAAGENT_DEBUG=true を設定し、非常に冗長な出力を想定してください。エージェントは、宣言的な YAML の設定ファイルもサポートしています。Java エージェントのドキュメントを参照してください。

Python

ディストリビューション、OTLP exporter、インストール済みのパッケージに合う計装ライブラリをインストールします。

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-bootstrap -a install は、環境をスキャンして、見つかったものの計装をインストールします。たとえば Flask がインストールされている場合は、Flask の計装です。インストールせずに推奨を確認するには、引数なしで opentelemetry-bootstrap を実行します。アプリケーションは、opentelemetry-instrument を通じて起動します。

OTEL_SERVICE_NAME=checkout \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
opentelemetry-instrument python myapp.py

末尾のバックスラッシュに注意してください。各変数は、opentelemetry-instrument と同じ論理的なコマンドライン上にある必要があり、そうでないとプロセスに届きません。Gunicorn や Uvicorn のようなサーバーでは、サーバーのコマンドを包みます。opentelemetry-instrument gunicorn app:app。uv パッケージマネージャーを使う一部の構成では、bootstrap のステップに回避策が必要で、それは Python のトラブルシューティングのページに記載されています。Python ではログのエクスポートはオプトインなので、ログが表示されない場合は、Python のドキュメントのロギングのセクションを確認してください。

Dockerfile のパターン：

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt \
 && pip install opentelemetry-distro opentelemetry-exporter-otlp \
 && opentelemetry-bootstrap -a install
COPY . .
CMD ["opentelemetry-instrument", "python", "myapp.py"]

Node.js

API と自動計装のバンドルをインストールします。

npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

アプリケーションの前に、--require か、NODE_OPTIONS で読み込みます。

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_NODE_RESOURCE_DETECTORS=env,host,os
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js

OTEL_NODE_RESOURCE_DETECTORS は、どの resource detector を実行するかを制限します（デフォルトではすべて有効）。OTEL_NODE_ENABLED_INSTRUMENTATIONS は、どの計装を読み込むかを制限します。モジュールの設定ページを参照してください。OTEL_LOG_LEVEL は、none、error、warn、info、debug、verbose、all を受け付け、デフォルトは info です。デバッグ出力はパフォーマンスを損なうため、本番では info のままにしてください。ES モジュールのアプリケーションには、追加の loader オプションが必要な場合があります。お使いのモジュールシステムに対する Node.js のドキュメントに従ってください。

.NET、Go、その他

.NET には、同じように設定されるコード不要のエージェントがあります（環境変数と起動スクリプト）。Go は、特権のあるサイドカーとして動作し、対象の実行ファイルのパスを必要とする eBPF ベースのエージェントを使うため、主に Operator を通じて使われます。それぞれについては、ドキュメントのコード不要のセクションを参照してください。

得られるものと、得られないもの

受信と送信の HTTP、データベース呼び出し、一般的なメッセージングライブラリのスパンが得られ、一部の言語では、ランタイムのメトリクスも得られます。エージェントはそれについて知ることができないため、「割引を計算する」のような、ビジネスレベルのスパンは得られません。追加の詳細が価値を持つところには、OpenTelemetry の API でいくつかの手作業のスパンや属性を追加し、それ以外のすべてには、エージェントを使い続けてください。

動作することを確認する

1. Collector の debug exporter を有効にして、アプリケーションを起動します。
2. リクエストを送ります：curl http://localhost:8080/。
3. Collector のログで、service.name を持つスパンを探します。

docker compose logs otel-collector | grep -i 'service.name'

何も届かない場合は、次の順に確認します。エンドポイントとポートがプロトコルと一致しているか、シグナルの Collector のパイプラインが otlp receiver を列挙しているか、アプリケーションが Collector のホスト名を解決できるか、OTEL_SDK_DISABLED が設定されていないか。トラブルシューティングのガイドで、それぞれを詳しく説明します。

本番での注意

• エージェントとディストリビューションのバージョンを固定し、意図的に更新します。
• ダッシュボードがそれらに依存するため、すべてのサービスに service.name、service.version、deployment.environment.name を設定します。
• すべてを保持するのではなく、サンプリング比率から始めます（サンプリングのガイドを参照）。
• Kubernetes では、すべての Dockerfile を編集する代わりに、Operator を使って、アノテーションでエージェントを注入します。