Python のゼロコード計装¶

Beacon Python のゼロコードフローは Python 3.10 から 3.14 に対応します。アプリケーションと同じ仮想環境にインストールしてください。

接続前に共通設定を完了し、DataKit OpenTelemetry コレクターを有効にしてください。以下は Linux/macOS のシェルの例で、アプリケーションと DataKit が同じホストにあることを前提とします。別ホストやコンテナに配置する場合は、127.0.0.1 を置き換え、リッスンアドレスを調整してください。

インストール¶

アプリケーションのフレームワークに合う extra を選んでください。

# FastAPI。Flask または requests の場合は対応する extra に置き換えます。
pip install 'beacon-otel[fastapi]'

起動¶

export OTEL_SERVICE_NAME=my-python-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
beacon uvicorn myapp:app

uvicorn myapp:app を既存のアプリケーション起動コマンドに置き換えてください。beacon --version で有効なバージョンを確認できます。

デバッグと診断¶

Beacon Python のゼロコードエントリーポイントには、SDK のデバッグログを一括で有効にするスイッチはありません。OTEL_LOG_LEVEL=debug だけでは Python の logging レベルは自動設定されません。詳細なログが必要な場合は、アプリケーションの既存のログ設定で opentelemetry Logger を DEBUG に設定し、出力 Handler を構成してください。

アプリケーションのソースコードを変更しない初期診断として、OTLP エクスポートを維持したままコンソールへの Span 出力を追加できます。

beacon --version
OTEL_TRACES_EXPORTER=otlp,console \
  beacon uvicorn myapp:app > beacon-python-diagnostic.log 2>&1

上記のサービス名、OTLP アドレス、プロトコルを保持し、対応するフレームワークの API にアクセスして、ファイル内の Span を確認してください。コンソールのコピーは、Span が生成されていない場合と受信側へのエクスポートに失敗している場合を切り分けるのに役立ちますが、OTLP 配信の成功を証明するものではなく、SDK のデバッグログでもありません。

調査後は通常の起動コマンドに戻し、追加した console エクスポーターを削除して、アプリケーションのログレベルも元に戻してください。

Profile¶

先に DataKit Profile コレクターを有効にし、以下の変数を設定して、上記の起動方法を引き続き使用してください。Profile は独立した HTTP アップロード先を使用し、OTLP Trace のアドレスとは共用しません。

アプリケーションの仮想環境に profiling extra をインストールします。

pip install 'beacon-otel[fastapi,profiling]'

fastapi はアプリケーションで実際に使用するコンポーネントに置き換えてください。

HTTP で pprof をアップロード¶

export OTEL_SERVICE_NAME=my-python-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=pprof_http
export OTEL_PROFILING_PPROF_UPLOAD_URL=http://127.0.0.1:9529/profiling/v1/input
beacon uvicorn myapp:app

認証が必要な場合は、OTEL_PROFILING_PPROF_HEADERS にカンマ区切りの name:value HTTP ヘッダーを設定できます。

ローカル pprof ファイルに書き込む¶

export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=pprof
export OTEL_PROFILING_PPROF_PATH="$PWD/profiles"
beacon uvicorn myapp:app

先に出力先ディレクトリを作成し、デプロイ環境のファイル保持方針に含めてください。

追加のコレクター¶

Profile を有効にすると、既定でスタックサンプリングが行われます。必要に応じて、ほかのコレクターを追加してください。

export OTEL_PROFILING_MEMORY_ENABLED=true
export OTEL_PROFILING_LOCK_ENABLED=true
# Python 3.12 以降のみ
export OTEL_PROFILING_EXCEPTION_ENABLED=true

既定のエクスポート間隔は 60 秒です。定期アップロードを行うには、プロセスをその間隔より長く実行する必要があります。

パラメーターリファレンス¶

環境変数名は大文字と小文字を区別します。ランタイムの表にある間隔の単位は秒です。

ランタイムとコレクター¶

環境変数	型 / 設定値	既定値	説明
`OTEL_PROFILING_ENABLED`	真偽値	`false`	自動計装の初期化時に Profiler を起動します。
`OTEL_PROFILING_EXPORTER`	`none`、`pprof`、`pprof_http`、`otlp`	自動選択	エクスポーターを選択します。未設定で pprof アップロード URL がある場合は `pprof_http`、それ以外は `otlp` が選択されます。
`OTEL_PROFILING_SAMPLE_INTERVAL`	正の数	`0.01`	呼び出しスタックのサンプリング間隔。
`OTEL_PROFILING_EXPORT_INTERVAL`	正の数	`60`	Profile のフラッシュとエクスポートの間隔。
`OTEL_PROFILING_MAX_FRAMES`	正の整数	`64`	1 回のサンプルで取得するスタックフレームの最大数。
`OTEL_PROFILING_INCLUDE_TRACE_CONTEXT`	真偽値	`true`	取得できる場合は、現在の Trace と Span のコンテキストを追加します。
`OTEL_PROFILING_EXCEPTION_ENABLED`	真偽値	`false`	例外の Profile を有効にします。
`OTEL_PROFILING_EXCEPTION_SAMPLING_INTERVAL`	正の整数	`100`	例外サンプリングの間引き間隔。
`OTEL_PROFILING_EXCEPTION_COLLECT_MESSAGE`	真偽値	`false`	例外メッセージを収集します。有効にする前に機密データへの影響を確認してください。
`OTEL_PROFILING_LOCK_ENABLED`	真偽値	`false`	threading と asyncio のロックコレクターを有効にします。
`OTEL_PROFILING_MEMORY_ENABLED`	真偽値	`false`	メモリーの Profile を有効にします。
`OTEL_PROFILING_MEMORY_INTERVAL`	正の数	エクスポート間隔	メモリーの収集間隔。
`OTEL_PROFILING_MEMORY_TOP_STATS`	正の整数	`200`	各メモリー収集で保持する統計項目の最大数。
`OTEL_PROFILING_MEMORY_IGNORE_PROFILER`	真偽値	`true`	Profiler 自身によるメモリー割り当てを除外します。

pprof エクスポート¶

環境変数	型 / 設定値	既定値	説明
`OTEL_PROFILING_PPROF_PATH`	ファイルパスのプレフィックス	`otel-profiles`	生成する `.pprof` ファイルのパスプレフィックス。どちらの pprof エクスポーターもローカルコピーを保持します。
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	`http://localhost:8126/profiling/v1/input`	`pprof_http` のアップロード先。エクスポーターが未設定の場合、この変数を設定すると `pprof_http` が選択されます。
`OTEL_PROFILING_PPROF_HEADERS`	カンマ区切りの `name:value`	空	追加の HTTP リクエストヘッダー。

Security¶

同じ beacon-otel wheel に任意で有効化する Security が含まれています。標準 GIL の CPython 3.11 から 3.14 に対応します。Python Security ガイドを参照してください。

接続の確認¶

対応するフレームワークやライブラリを経由するリクエストをアプリケーションの API に送り、Guance の「APM > トレース」で上記のサービス名を絞り込んでください。確認手順の詳細は共通設定を、データがない場合はトラブルシューティングを参照してください。