diff --git a/content/ja/docs/zero-code/python/configuration.md b/content/ja/docs/zero-code/python/configuration.md index 75d5c40a2efb..bc89c24f6306 100644 --- a/content/ja/docs/zero-code/python/configuration.md +++ b/content/ja/docs/zero-code/python/configuration.md @@ -2,7 +2,9 @@ title: エージェント設定 linkTitle: Configuration weight: 10 -default_lang_commit: 3d737b777f7bfa070f7f14835570add916d4dcb0 +default_lang_commit: 276d7eb3f936deef6487cdd2b1d89822951da6c8 +# prettier-ignore +cSpell:ignore: gevent healthcheck instrumentor myapp pyproject Starlette urllib --- エージェントは次のいずれかの方法で高度に設定可能です。 @@ -118,6 +120,7 @@ export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true - `OTEL_PYTHON_GRPC_EXCLUDED_SERVICES`: gRPC 計装から除外するサービスをカンマ区切りで指定します。 - `OTEL_PYTHON_ID_GENERATOR`: グローバルトレーサプロバイダーに使用する ID ジェネレータを指定します。 - `OTEL_PYTHON_INSTRUMENTATION_SANITIZE_REDIS`: クエリーのサニタイズ処理を有効にします。 +- `OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH`: SDKを初期化する前にgeventモンキーパッチの `patch_all` メソッドを呼び出すために `patch_all` に設定します。 例を挙げましょう。 @@ -127,6 +130,7 @@ export OTEL_PYTHON_ELASTICSEARCH_NAME_PREFIX=my-custom-prefix export OTEL_PYTHON_GRPC_EXCLUDED_SERVICES="GRPCTestServer,GRPCHealthServer" export OTEL_PYTHON_ID_GENERATOR=xray export OTEL_PYTHON_INSTRUMENTATION_SANITIZE_REDIS=true +export OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH=patch_all ``` ## 特定の計装を無効にする {#disabling-specific-instrumentations} diff --git a/content/ja/docs/zero-code/python/operator.md b/content/ja/docs/zero-code/python/operator.md index 57fb8f7effc1..a5dbaaaa9aaf 100644 --- a/content/ja/docs/zero-code/python/operator.md +++ b/content/ja/docs/zero-code/python/operator.md @@ -2,7 +2,8 @@ title: OpenTelemetryオペレーターを使用して自動計装を注入する linkTitle: Operator weight: 30 -default_lang_commit: 3d737b777f7bfa070f7f14835570add916d4dcb0 +default_lang_commit: 276d7eb3f936deef6487cdd2b1d89822951da6c8 +cSpell:ignore: gevent grpcio myapp psutil PYTHONPATH --- KubernetesでPythonサービスを実行する場合、[OpenTelemetryオペレーター](https://github.com/open-telemetry/opentelemetry-operator)を活用することで、各サービスを直接修正することなく自動計装を注入できます。 @@ -27,3 +28,7 @@ Django のように独自の実行ファイルから実行されるアプリケ - `PYTHONPATH` には Django アプリケーションのルートディレクトリへのパスを指定します(例: "/app")。 - `DJANGO_SETTINGS_MODULE` に Django 設定モジュールの名前を指定します(例: "myapp.settings")。 + +#### gevent アプリケーション {#gevent-applications} + +OpenTelemetry Python 1.37.0/0.58b0 リリース以降、デプロイファイルで `OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH` 環境変数を `patch_all` に設定すると、自動計装コードはそれ自体を初期化する前に、同じ名前のgeventのモンキーパッチメソッドを呼び出します。 diff --git a/content/ja/docs/zero-code/python/troubleshooting.md b/content/ja/docs/zero-code/python/troubleshooting.md index e4b38e649ff8..8d14dba4fde8 100644 --- a/content/ja/docs/zero-code/python/troubleshooting.md +++ b/content/ja/docs/zero-code/python/troubleshooting.md @@ -2,7 +2,8 @@ title: Pythonの自動計装に関する問題のトラブルシューティング linkTitle: Troubleshooting weight: 40 -default_lang_commit: 3d737b777f7bfa070f7f14835570add916d4dcb0 +default_lang_commit: 276d7eb3f936deef6487cdd2b1d89822951da6c8 +cSpell:ignore: ASGI gunicorn uvicorn --- ## インストールに関する問題 {#installation-issues} @@ -82,6 +83,96 @@ if __name__ == "__main__": app.run(port=8082, debug=True, use_reloader=False) ``` +### プリフォークサーバーの問題 {#pre-fork-server-issues} + +複数のワーカーを持つGunicornのようなプリフォークサーバーは、次のように実行できます。 + +```sh +gunicorn myapp.main:app --workers 4 +``` + +ただし、複数の `--workers` を指定すると、自動計装を適用した場合にメトリクスの生成が壊れる可能性があります。 +これは、ワーカー/子プロセスの作成であるフォークが、バックグラウンドスレッドとOpenTelemetry SDKの主要なコンポーネントが想定しているロックとの間に、各子プロセス間で不整合を生じさせるためです。 +具体的には、`PeriodicExportingMetricReader` は、データをエクスポーターに定期的にフラッシュするための独自のスレッドを生成します。 +イシュー[#2767](https://github.com/open-telemetry/opentelemetry-python/issues/2767) および [#3307](https://github.com/open-telemetry/opentelemetry-python/issues/3307#issuecomment-1579101152) も参照してください。 +フォーク後、各子プロセスは実際には実行されていないメモリ内のスレッドオブジェクトを探し、元のロックは各子プロセスでアンロックされない可能性があります。 +[Python issue 6721](https://bugs.python.org/issue6721) で説明されているフォークとデッドロックも参照してください。 + +#### 回避策 {#workarounds} + +OpenTelemetryでプリフォークサーバーを使用するためのいくつかの回避策があります。 +次の表は、複数のワーカーでプリフォークされた、さまざまな自動計装Webサーバーゲートウェイスタックによるシグナルエクスポートの現在のサポートをまとめています。 +詳細とオプションについては、以下を参照してください。 + +| 複数ワーカーのスタック | トレース | メトリクス | ログ | +| ------------------------ | -------- | ---------- | ---- | +| Uvicorn | x | | x | +| Gunicorn | x | | x | +| Gunicorn + UvicornWorker | x | x | x | + +##### GunicornとUvicornWorkerでデプロイ {#deploy-with-gunicorn-and-uvicornworker} + +複数のワーカーを持つサーバーを自動計装するには、非同期サーバーゲートウェイインターフェース(ASGI)アプリ(FastAPI、Starletteなど)の場合、`uvicorn.workers.UvicornWorker` を使ったGunicornによるデプロイが推奨されます。 +UvicornWorkerクラスは、バックグラウンドプロセスとスレッドを保持しながらフォークを処理するように特別に設計されています。 +例を挙げましょう。 + +```sh +opentelemetry-instrument gunicorn \ + --workers 4 \ + --worker-class uvicorn.workers.UvicornWorker \ + --bind 0.0.0.0:8000 \ + myapp.main:app +``` + +##### プログラム自動計装の使用 {#use-programmatic-auto-instrumentation} + +`opentelemetry-instrument` のかわりに、サーバーフォーク後のワーカープロセス内で[プログラム自動計装](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/opentelemetry-instrumentation/README.rst#programmatic-auto-instrumentation)を使用してOpenTelemetryを初期化します。 +例を挙げましょう。 + +```python +from opentelemetry.instrumentation.auto_instrumentation import initialize +initialize() + +from your_app import app +``` + +FastAPIを使用している場合、計装がパッチされる方法により、`FastAPI` をインポートする前に `initialize()` を呼び出す必要があることに注意してください。 +例を挙げましょう。 + +```python +from opentelemetry.instrumentation.auto_instrumentation import initialize +initialize() + +from fastapi import FastAPI + +app = FastAPI() + +@app.get("/") +async def root(): + return {"message": "Hello World"} +``` + +その後、次のコマンドでサーバーを実行します。 + +```sh +uvicorn main:app --workers 2 +``` + +##### PrometheusでOTLPを直接使用 {#use-prometheus-with-direct-otlp} + +OTLP メトリクスを直接受信するために、[Prometheus](/docs/languages/python/exporters/#prometheus-setup) の最新バージョンの使用を検討してください。 +`PeriodicExportingMetricReader` とプロセスごとに1つのOTLPワーカーを設定して、Prometheusサーバーにプッシュします。 +フォークでの `PrometheusMetricReader` の使用は推奨しません。 +イシュー[#3747](https://github.com/open-telemetry/opentelemetry-python/issues/3747) を参照してください。 + +##### 単一ワーカーの使用 {#use-a-single-worker} + +または、ゼロコード計装でプリフォークで単一ワーカーを使用します。 + +```sh +opentelemetry-instrument gunicorn your_app:app --workers 1 +``` + ## 接続性の問題 {#connectivity-issues} ### gRPCコネクティビティ {#grpc-connectivity}