https://mackerel.io/ja/docs/entry/tracing/installations/python

このページでは、PythonのアプリケーションからトレースをMackerelに送信する方法を解説します。

概要

MackerelはOpenTelemetryの仕組み（計装）を利用してトレースを取得します。OpenTelemetryに対応したトレースはさまざまな方法で取得できますが、今回はゼロコード計装と呼ばれる、アプリケーションの実装を変更せずにトレースを送信する方法を解説します。

📝 補足

Pythonのゼロコード計装は、実行時にライブラリ関数を変更するエージェントを利用して、トレースといったテレメトリーデータを取得できるようにすることで実現されています。

詳しくはOpenTelemetry公式ドキュメントの Pythonゼロコード・計装 | OpenTelemetry をご確認ください。

動作要件

OpenTelemetryの動作要件として、Pythonが指定されたバージョン以上である必要があります。

Python 3.9以上

導入方法

アプリケーションからMackerelへトレースを送信するために、以下をおこないます。

パッケージのインストール
エージェントを経由してアプリケーションを実行

1. パッケージのインストール

以下のコマンドで、PythonでのOpenTelemetry利用に必要なパッケージをインストールします。

pip install opentelemetry-distro opentelemetry-exporter-otlp

つづいて、opentelemetry-bootstrap コマンドを利用して、site-packages フォルダに存在するパッケージに対応する計装ライブラリをインストールします。

opentelemetry-bootstrap -a install

OpenTelemetryはPythonのさまざまなパッケージをサポートしており、パッケージごとに個別の計装ライブラリが用意されています。提供されているパッケージは以下のページで検索できます。

opentelemetry.io

📝 補足

お使いのフレームワークやアプリケーション向けの計測ライブラリが存在しない場合は、独自に計装することもできます。

詳しくはOpenTelemetry公式ドキュメントの Instrumentation | OpenTelemetryをご確認ください。

2. エージェントを経由してアプリケーションを実行

ゼロコード計装を利用する場合、opentelemetry-instrument を経由してPythonアプリケーションを実行することで、アプリケーションから自動でトレースを送信できます。

環境変数 MACKEREL_APIKEY にMackerelのWrite権限を持つAPIキーを設定した状態で以下のように実行することで、my-sample-app というサービス名でMackerelにトレースが送信されます。

opentelemetry-instrument \
    --traces_exporter otlp \
    --metrics_exporter none \
    --logs_exporter none \
    --service_name my-sample-app \
    --exporter_otlp_traces_endpoint https://otlp-vaxila.mackerelio.com/v1/traces \
    --exporter_otlp_traces_headers "Mackerel-Api-Key=${MACKEREL_APIKEY},Accept='*/*'" \
    --exporter_otlp_traces_protocol http/protobuf \
    python myapp.py  # この行は起動したいアプリケーションの起動コマンドに置き換えてください

--traces_exporter を console にするとトレースが標準出力に出力されます。
--service_name はトレースのサービス名（service.name属性の値）になります。
--exporter_otlp_traces_endpoint はトレースの送信先の指定です。
- Mackerelに直接送信する場合は https://otlp-vaxila.mackerelio.com/v1/traces を指定します。
- Collectorを利用して送信する場合は http://<Collectorのアドレス:ポート>/v1/traces を指定します。
${MACKEREL_APIKEY} はMackerelのAPIキーの指定です。APIキーの一覧から、Write権限のあるAPIキーをアプリケーションが動作するシステム内の環境変数に定義してください。
- 環境変数ではなくAPIキーを直接記述しても動作します。

トレースを確認する

送信されたトレースは以下の手順で確認できます。

メニューの「APM」を選択
サービス名を選択
「トレース」タブを選択
トレース一覧からトレースを選択すると詳細が確認できます

以上、Pythonで作成されたアプリケーションにゼロコード計装をおこなって、Mackerelへトレースを投稿する方法のご紹介でした。