OpenTelemetry Python¶

OpenTelemetry Python Agent は、実行時のモンキーパッチにより、サポート対象の Python ライブラリおよびフレームワークにテレメトリ機能を注入します。opentelemetry-instrument を使用してアプリケーションを起動すると、ビジネスコードを変更することなく、Web リクエスト、HTTP クライアント、データベース、メッセージキューなどの呼び出しを収集できます。

本ドキュメントでは、DataKit の OpenTelemetry コレクターを使用して OTLP データを受信し、Guance に転送します。

Python アプリケーション + OpenTelemetry Python Agent -> OTLP -> DataKit -> Guance

前提条件¶

• Python 3.10 以降
• pip および利用可能な Python 仮想環境
• DataKit がインストールされ、対象の Guance ワークスペースに接続されていること
• Python アプリケーションから DataKit へのネットワーク到達性があること。OTLP/HTTP は DataKit HTTP ポート 9529 を使用し、OTLP/gRPC はデフォルトで 4317 を使用します。

一、OpenTelemetry コレクターを有効にする¶

DataKit のインストールディレクトリ配下の conf.d/opentelemetry に移動します。コレクター設定がまだ作成されていない場合は、サンプルファイルをコピーします。

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf に少なくとも以下の受信設定が含まれていることを確認します。

[[inputs.opentelemetry]]
  # Guance でタグとして保持するカスタム属性をホワイトリストに追加します。
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

受信アドレスは次のとおりです。

Python アプリケーションと DataKit が同一ホスト上にない場合は、実際のデプロイに合わせて DataKit のリスニングアドレス、ファイアウォール、その他のネットワークアクセス制御を調整してください。gRPC では、addr をアプリケーションからアクセス可能なリスニングアドレス（例: 0.0.0.0:4317）に変更できます。OTLP 受信ポートをパブリックネットワークに直接公開しないでください。

DataKit を再起動し、サービスを確認します。

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

二、アプリケーションの OpenTelemetry 接続¶

仮想環境の作成¶

OpenTelemetry Agent、アプリケーション、およびインストルメンテーションパッケージは、同じ Python 環境にインストールする必要があります。アプリケーションには個別の仮想環境を使用することをお勧めします。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

まず、アプリケーション自身の依存関係をインストールします。例:

python -m pip install -r requirements.txt

Agent、Exporter、およびインストルメンテーションパッケージのインストール¶

Python Package Index の公式パッケージソースから OpenTelemetry Distro と OTLP exporter をインストールします。

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

opentelemetry-distro は、SDK、opentelemetry-bootstrap、および opentelemetry-instrument を提供します。opentelemetry-bootstrap -a install は、現在の環境にインストールされているアプリケーションの依存関係を確認し、一致するインストルメンテーションパッケージをインストールします。例えば、環境に Flask が存在する場合、opentelemetry-instrumentation-flask がインストールされます。

アプリケーションの依存関係をインストールしてから、bootstrap を実行する必要があります。アプリケーションにフレームワーク、データベースドライバー、HTTP クライアントなどの依存関係を追加またはアップグレードした後は、以下のコマンドを再実行することをお勧めします。

opentelemetry-bootstrap -a install

インストールせずに、インストールされるインストルメンテーションパッケージを事前に確認する場合は、次のコマンドを実行します。

opentelemetry-bootstrap

アプリケーションの設定と起動¶

以下は OTLP/HTTP + Protobuf の例で、デフォルトで Trace に接続し、Metric と Log は一時的に無効にします。

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION="false"

opentelemetry-instrument python app.py

OTEL_EXPORTER_OTLP_ENDPOINT はベースアドレスです。OTLP/HTTP exporter は、データタイプに応じて自動的に /v1/traces、/v1/metrics、または /v1/logs を追加し、最終的に DataKit の /otel/v1/* ルートに対応します。

実際のアプリケーションプロセスを起動するには、opentelemetry-instrument を使用する必要があります。環境変数を設定した後に python app.py を直接実行しても、ゼロコードの自動インストルメンテーションは有効になりません。

一般的な起動方法¶

Flask 開発サーバー:

opentelemetry-instrument flask --app app run --host 0.0.0.0 --port 8080

Gunicorn:

opentelemetry-instrument gunicorn --workers 1 --bind 0.0.0.0:8080 app:app

Gunicorn などのプリフォークサーバーで複数のワーカーを使用する場合、自動インストルメンテーションと Metric のエクスポートは、プロセスの fork 動作の影響を受ける可能性があります。最初はシングルワーカーで検証することをお勧めします。本番環境でマルチプロセスが必要な場合は、使用するフレームワークとシグナルタイプに基づいて、公式のプリフォークデプロイメント方式を評価してください。

Django 開発サーバー:

opentelemetry-instrument python manage.py runserver 0.0.0.0:8080

本番環境で Supervisor、systemd、またはその他のプロセスマネージャーを使用する場合は、環境変数と opentelemetry-instrument を実際の起動コマンドに記述し、アプリケーションを再起動してください。

OTLP/gRPC の使用¶

インストールされた opentelemetry-exporter-otlp には、OTLP exporter がすでに含まれています。gRPC を使用する場合は、プロトコルとエンドポイントを変更します。

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"

gRPC エンドポイントには、/v1/traces などの HTTP パスを追加しないでください。

三、データ送信パラメータ¶

Python Agent は、コマンドライン引数と環境変数をサポートしています。コマンドライン引数名を環境変数に変換する場合は、大文字に変換して OTEL_ プレフィックスを追加する必要があります。たとえば、--service_name は OTEL_SERVICE_NAME に対応します。同じパラメータがコマンドラインと環境変数の両方で設定されている場合、コマンドライン引数が優先されます。

基本パラメータ¶

service.name は、Guance でのサービス所属に使用されます。env と version も設定し、環境とバージョンでフィルタリングできるようにすることをお勧めします。その他のカスタムリソース属性は、DataKit の customer_tags ホワイトリストに追加した場合にのみタグとして保持されます。属性名の . は _ に変換されます。

Python 自動インストルメンテーションパラメータ¶

OTLP パラメータ¶

DataKit の OTLP/HTTP コレクションは Protobuf のみをサポートしています。http/protobuf を使用し、http/json は使用しないでください。共通エンドポイントと特定のデータタイプのエンドポイントが両方存在する場合、特定のデータタイプの設定が優先されます。

サンプリングとバッチ送信パラメータ¶

本番環境では、トラフィックとデータバジェットに基づいてサンプリングレートを設定する必要があります。アプリケーション側のヘッドサンプリングと DataKit 側のサンプリングを同時に有効にすると、最終的な保持率が相乗的に低下します。サンプリングの場所は統一して計画する必要があります。

接続の確認¶

インストルメンテーションライブラリがインストールされたアプリケーションのルートにリクエストを送信し、DataKit ホストで受信ログを確認します。

curl http://127.0.0.1:8080/
sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces への POST リクエストが表示され、応答コードが 200 の場合、DataKit が Trace を受信したことを示します。次に、Guance の「APM > トレース」に移動し、service:order-service でクエリを実行します。

データがない場合は、以下の項目を順に確認してください。アプリケーションと OpenTelemetry が同じ仮想環境にインストールされているか、アプリケーションの依存関係インストール後に opentelemetry-bootstrap -a install を実行したか、opentelemetry-instrument で起動したか、実際のコードパスがサポート対象のインストルメンテーションライブラリに該当するか、OTLP エンドポイントに到達可能か。

参考¶

• OpenTelemetry コレクター設定
• OpenTelemetry Python ゼロコードインストルメンテーション
• OpenTelemetry Python Agent 設定
• OpenTelemetry Python 自動インストルメンテーション例
• OpenTelemetry Python Distro
• OpenTelemetry OTLP Exporter 設定