Python

ClickStack 向け Python - ClickHouse オブザーバビリティ スタック

ClickStack は、テレメトリーデータ (ログと トレース) の収集に OpenTelemetry 標準を使用します。トレースは自動インストルメンテーションによって生成されるため、トレーシングの価値を得るのに手動の インストルメンテーションは必要ありません。

このガイドでは、以下を統合します:

• ログ
• メトリクス
• トレース

​

はじめに

​

ClickStack OpenTelemetry インストルメンテーション パッケージをインストールする

次のコマンドで、ClickStack OpenTelemetry パッケージをインストールします。

pip install hyperdx-opentelemetry

Python アプリケーションで使用しているパッケージ向けの OpenTelemetry 自動インストルメンテーション ライブラリをインストールします。OpenTelemetry Python SDK に付属する opentelemetry-bootstrap ツールを使用してアプリケーションのパッケージをスキャンし、利用可能なライブラリの一覧を生成することをおすすめします。

opentelemetry-bootstrap -a install

​

環境変数を設定する

次に、OpenTelemetry Collector 経由でテレメトリーを ClickStack に送信するため、シェルで以下の環境変数を設定する必要があります。

Managed ClickStack

OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

ClickStack Open Source

export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

OTEL_SERVICE_NAME 環境変数は、HyperDX アプリ内でサービスを識別するために使用されます。値には任意の名前を指定できます。

​

OpenTelemetry Pythonエージェントを使用してアプリケーションを実行する

これで、OpenTelemetry Pythonエージェント (opentelemetry-instrument) を使用してアプリケーションを実行できます。

opentelemetry-instrument python app.py

​

Gunicorn、uWSGI、uvicorn を使用している場合

この場合、OpenTelemetry Pythonエージェントを動作させるには追加の設定変更が必要です。

pre-fork Webサーバーモードを使用するアプリケーションサーバーで OpenTelemetry を設定するには、post-fork フック内で configure_opentelemetry メソッドを呼び出してください。

Gunicorn

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

uWSGI

from hyperdx.opentelemetry import configure_opentelemetry
from uwsgidecorators import postfork

@postfork
def init_tracing():
    configure_opentelemetry()

uvicorn

OpenTelemetry は現在、--reload フラグを付けて実行した uvicorn、またはマルチワーカー (--workers) では 動作しません。 テスト時にはこれらのフラグを無効にするか、Gunicorn を使用することを推奨します。

​

高度な設定

​

ネットワークキャプチャ

ネットワークキャプチャ機能を有効にすると、開発者は HTTPリクエストのヘッダーやボディ内のペイロードを効果的にデバッグできるようになります。これは HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE フラグを 1 に設定するだけで 実現できます。

export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1

​

トラブルシューティング

​

ログレベルが原因でログが表示されない

デフォルトでは、OpenTelemetry のログ用ハンドラーは logging.NOTSET レベルを使用しており、実際には WARNING レベルとして扱われます。ロガーの作成時にログレベルを指定できます:

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

​

コンソールへのエクスポート

OpenTelemetry Python SDK は通常、エラーが発生するとその内容をコンソールに表示します。 ただし、エラーは発生していないのに、データが想定どおり HyperDX に表示されない場合は、 デバッグモードを有効にすることもできます。 デバッグモードを有効にすると、すべてのテレメトリーがコンソールに出力されるため、 アプリケーションが想定どおりのデータを出力するよう適切にインストルメントされているかを確認できます。

export DEBUG=true

Python OpenTelemetry のインストルメンテーションの詳細については、こちらをご覧ください。 https://opentelemetry.io/docs/instrumentation/python/manual/