このドキュメントでは、Python エージェントに関するよくある質問にお答えします。
aliyun-bootstrap -a install によるインストール失敗
aliyun-bootstrap -a install コマンドでエージェントをインストールすると、次のエラーが発生することがあります。
Installation aborted due to download failure.この失敗には、通常 2 つの原因のいずれかが考えられます。
-
ネットワークの問題により、エージェントが OSS エンドポイントに到達できません。ネットワーク接続を確認してください。
Starting Aliyun Python Agent installation...
agent download url: https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz
Checking network connectivity...
Downloading agent from https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz...
Downloading: 100%|████████████████████████████████████████████████████████████| 1.00M/1.00M [00:00<00:00, 6.21MB/s]
Extracting wheels from archive...
Extracting files: 100%|███████████████████████████████████████████████████████| 27/27 [00:00<00:00, 2151.05file/s]
Found 27 wheel files
Installing 27 packages...
Installing packages: 0%| | 0/27 [00:00<?, ?pkg/s]
Installing packages: 0%| | 0/27 [00:00<?, ?pkg/s]-
お使いの Python インタープリターに SSL モジュールがありません。
python3 -m sslこのコマンドでエラーが発生した場合、お使いの Python インタープリターに SSL モジュールがないことを意味します。aliyun-bootstrap スクリプトは依存関係をダウンロードするためにこのモジュールを必要とするため、お使いの Python 環境にインストールする必要があります。
起動エラー：No module named 'aliyun'
このエラーは、エージェントが、アプリケーションのランタイムから参照できない場所にインストールされたことを示します。アプリケーション環境の Python インタープリターが Python エージェントの依存関係を見つけられるようにする必要があります。
アプリケーションの環境で次のコマンドを実行して、aliyun-bootstrap がエージェントパッケージを検索可能なパスにインストールしたことを確認してください。
python3 -m siteこのコマンドは、Python インタープリターがパッケージを見つけるために使用する検索パスを出力します。以下のディレクトリ構造の例に示すように、これらのパスのいずれにも Python エージェントの依存関係が見つからない場合、インストールの場所が正しくありません。
.venv
bin
lib
python3.12
site-packages library root
_distutils_hack
aliyun
instrumentation
opentelemetry
sdk
semconv
__init__.py
aliyun_instrumentation_dashscope-1.0.0.dist-info
aliyun_instrumentation_dify-1.1.0.dist-info
aliyun_instrumentation_langchain-1.1.0.dist-info
aliyun_instrumentation_llama_index-1.0.3.dev0.dist-info
aliyun_instrumentation_openai-1.0.1.dist-info
aliyun_instrumentation_vllm-0.1.0.dist-info
aliyun_opentelemetry_exporter_otlp_proto_common-1.25.0.dist-info
aliyun_opentelemetry_exporter_otlp_proto_grpc-1.25.0.dist-info
aliyun_opentelemetry_exporter_otlp_proto_http-1.25.0.dist-info
aliyun_opentelemetry_instrumentation-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_aiohttp_client-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_asgi-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_django-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_fastapi-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_flask-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_httpx-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_logging-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_redis-0.46b0.dev0.dist-info次のコマンドを使用して、aliyun-bootstrap パッケージのインストール場所を指定できます。
aliyun-bootstrap -a install -t ${TARGET_PATH}${TARGET_PATH} をお使いの環境の正しいパスに置き換えてください。たとえば、パスは /root/demo/venv/lib/python3.12/site-packages となります。
Flask アプリケーションのデータ未報告
デバッグモードが有効になっている場合、aliyun-instrument メソッドを使用して Flask アプリケーションを統合することはできません。代わりに、Flask アプリケーションのエントリファイルに次のステートメントを追加して、Python エージェントを手動でインポートする必要があります。これにより、aliyun-instrument プレフィックスを追加せずにアプリケーションを起動できます。
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomizeDjango アプリケーションの起動失敗
Django アプリケーションの起動に失敗し、AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF' のようなエラーが表示される場合は、DJANGO_SETTINGS_MODULE 環境変数をプロジェクトの設定モジュールに設定してください。
export DJANGO_SETTINGS_MODULE=instrumentation_example.settingsDjango アプリケーションのデータ未報告
Django のホットリロード機能は、python manage.py runserver 0.0.0.0:8080 のようなコマンドでデフォルトで有効になりますが、エージェントのデータ報告を妨げる可能性があります。これを修正するには、--noreload オプションを追加してホットリロードを無効にしてください。
python manage.py runserver 0.0.0.0:8080 --noreloadUvicorn アプリケーションのデータ未報告
Uvicorn サーバーでホットリロード (--reload パラメーター) または複数のワーカー (--workers パラメーター) を使用すると、エージェントがデータを報告できなくなることがあります。これを解決するには、アプリケーションのエントリファイルに次の行を追加して、Python エージェントを手動でインポートする必要があります。アプリケーションの起動時に aliyun-instrument プレフィックスを使用しないでください。
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomizeエージェントのアンインストール
Python エージェントをアンインストールするには、次のコマンドを実行してください。
aliyun-bootstrap -a uninstall特定のリージョンとバージョンのインストール
最適なパフォーマンスを得るために、最も近いリージョンから特定バージョンのエージェントをインストールする必要がある場合があります。次の手順に従ってください。
-
ARMS_REGION_ID環境変数を設定して、エージェントを取得するリージョンを指定してください。
export ARMS_REGION_ID=cn-beijingサポートされているリージョンの一覧については、「利用可能なリージョン」をご参照ください。
-
次のコマンドで特定のバージョンの Python エージェントをインストールしてください。別のバージョンのエージェントがインストールされている場合は、まずそれをアンインストールすることを推奨します。
# ${version} をターゲットのバージョン番号に置き換えます
aliyun-bootstrap -a install -v ${version}「Container Service for Kubernetes (ACK) と Container Compute Service (ACS) でack-onepilotコンポーネントを使用してPythonエージェントをインストールする」で説明されている非侵入的な方法を使用して Python エージェントをインストールした場合は、aliyun.com/agent-version ラベルを追加してエージェントのバージョンを指定できます。詳細については、「エージェントのバージョンを個別に制御する」をご参照ください。
公開されているすべての Python エージェントのバージョンの一覧については、「Python エージェントのリリースノート」をご参照ください。
ログディレクトリの指定
お使いの Python エージェントのバージョンが 1.6.0 以降であることを確認してください。その後、APSARA_APM_AGENT_WORKSPACE_DIR 環境変数を設定できます。エージェントは、ログファイルを ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs ディレクトリに保存します。
デフォルトでは、エージェントは次の優先順位に従ってログディレクトリを決定します。
-
/home/admin/.opt/.apsara-apm/python/logs(ack-onepilot コンポーネントのボリュームディレクトリ) -
~/.apsara-apm/python/logs(ユーザーのホームディレクトリ) -
./.apsara-apm/python/logs(メインの Python エントリファイルと同じディレクトリ)
ログファイル名は aliyun-python-agent-{PID}.log の形式に従います。ここで、{PID} はプロセス ID です (例： aliyun-python-agent-5921.log)。同じディレクトリには、diagnose-{PID}.log 診断ログファイルも含まれます。
ネットワークレポートモードの指定
エージェントのバージョンが 1.6.0 以降の場合は、PROFILER_NETWORK_STRATEGY 環境変数を設定してネットワークレポートモードを指定できます。
-
internal：内部ネットワーク経由のレポートを強制します。 -
public：パブリックネットワーク経由のレポートを強制します。 -
auto：ネットワークモードを自動的に検出します (デフォルトの動作)。
OpenAI ストリーミングにおけるトークン使用量の未表示
詳細については、「ストリーミング出力」をご参照ください。デフォルトでは、OpenAI プロトコルはストリーミングコールでトークン使用量を返しません。この情報を受け取るには、stream_options={"include_usage": true} を設定して、最後のデータチャンクにトークン使用量の詳細を含める必要があります。
子プロセスへのエージェントのインジェクション防止
ターゲットアプリケーションによって作成された子プロセスにエージェントがインジェクションされるのを防ぐには、APSARA_APM_INSTRUMENTATION_CHILD_PROCESS 環境変数を false に設定してください。