From 5f04642d5c482919ea7cc7726325ab11affb0e2c Mon Sep 17 00:00:00 2001 From: Msksgm Date: Sat, 27 Sep 2025 08:32:27 +0900 Subject: [PATCH 1/8] fix: drifted files of content/ja/docs/zero-code/python/ --- .../ja/docs/zero-code/python/configuration.md | 6 +- content/ja/docs/zero-code/python/operator.md | 7 +- .../docs/zero-code/python/troubleshooting.md | 93 ++++++++++++++++++- 3 files changed, 103 insertions(+), 3 deletions(-) diff --git a/content/ja/docs/zero-code/python/configuration.md b/content/ja/docs/zero-code/python/configuration.md index 75d5c40a2efb..c05070deb0ba 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 monkeypatch 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 monkeypatch `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..404445d61d4e 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 monkeypatch 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 monkeyPatchメソッドを呼び出します。 diff --git a/content/ja/docs/zero-code/python/troubleshooting.md b/content/ja/docs/zero-code/python/troubleshooting.md index e4b38e649ff8..142dee283820 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} From 2c00f323acb6c23bf6e0d2a694cca7ed88492c35 Mon Sep 17 00:00:00 2001 From: Masaki Sugimoto <49427230+Msksgm@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:00:34 +0900 Subject: [PATCH 2/8] Update content/ja/docs/zero-code/python/configuration.md Co-authored-by: Kohei Sugimoto <18735471+kohbis@users.noreply.github.com> --- content/ja/docs/zero-code/python/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/zero-code/python/configuration.md b/content/ja/docs/zero-code/python/configuration.md index c05070deb0ba..e55bd7253fa7 100644 --- a/content/ja/docs/zero-code/python/configuration.md +++ b/content/ja/docs/zero-code/python/configuration.md @@ -120,7 +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 monkeypatch `patch_all` メソッドを呼び出すために `patch_all` に設定します。 +- `OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH`: SDKを初期化する前にgeventモンキーパッチの `patch_all` メソッドを呼び出すために `patch_all` に設定します。 例を挙げましょう。 From 1db92ebd04a1f497431bc4584733edcac7df3f0c Mon Sep 17 00:00:00 2001 From: Masaki Sugimoto <49427230+Msksgm@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:00:42 +0900 Subject: [PATCH 3/8] Update content/ja/docs/zero-code/python/operator.md Co-authored-by: Kohei Sugimoto <18735471+kohbis@users.noreply.github.com> --- content/ja/docs/zero-code/python/operator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/zero-code/python/operator.md b/content/ja/docs/zero-code/python/operator.md index 404445d61d4e..d216c7de6a75 100644 --- a/content/ja/docs/zero-code/python/operator.md +++ b/content/ja/docs/zero-code/python/operator.md @@ -31,4 +31,4 @@ Django のように独自の実行ファイルから実行されるアプリケ #### gevent アプリケーション {#gevent-applications} -OpenTelemetry Python 1.37.0/0.58b0 リリース以降、デプロイファイルで `OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH` 環境変数を `patch_all` に設定すると、自動計装コードはそれ自体を初期化する前に、同じ名前のgevent monkeyPatchメソッドを呼び出します。 +OpenTelemetry Python 1.37.0/0.58b0 リリース以降、デプロイファイルで `OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH` 環境変数を `patch_all` に設定すると、自動計装コードはそれ自体を初期化する前に、同じ名前のgeventのモンキーパッチメソッドを呼び出します。 From f0417ad5f26f0ba00d7e2c9e36255a68e681a106 Mon Sep 17 00:00:00 2001 From: Masaki Sugimoto <49427230+Msksgm@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:01:13 +0900 Subject: [PATCH 4/8] Update content/ja/docs/zero-code/python/troubleshooting.md Co-authored-by: Kohei Sugimoto <18735471+kohbis@users.noreply.github.com> --- content/ja/docs/zero-code/python/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/zero-code/python/troubleshooting.md b/content/ja/docs/zero-code/python/troubleshooting.md index 142dee283820..a18f7cfc8db8 100644 --- a/content/ja/docs/zero-code/python/troubleshooting.md +++ b/content/ja/docs/zero-code/python/troubleshooting.md @@ -92,7 +92,7 @@ gunicorn myapp.main:app --workers 4 ``` ただし、複数の `--workers` を指定すると、自動計装を適用した場合にメトリクスの生成が壊れる可能性があります。 -これは、ワーカー/子プロセスの作成であるフォークが、OpenTelemetry SDKの主要コンポーネントが想定するバックグラウンドスレッドとロック間で、各子プロセス間で不整合を生成するためです。 +これは、ワーカー/子プロセスの作成であるフォークが、バックグラウンドスレッドと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) も参照してください。 フォーク後、各子プロセスは実際には実行されていないメモリ内のスレッドオブジェクトを探し、元のロックは各子プロセスでアンロックされない可能性があります。 From 5c22c3ce9f208670cf5407f14b993592017bfc4d Mon Sep 17 00:00:00 2001 From: Masaki Sugimoto <49427230+Msksgm@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:01:21 +0900 Subject: [PATCH 5/8] Update content/ja/docs/zero-code/python/troubleshooting.md Co-authored-by: Kohei Sugimoto <18735471+kohbis@users.noreply.github.com> --- content/ja/docs/zero-code/python/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/zero-code/python/troubleshooting.md b/content/ja/docs/zero-code/python/troubleshooting.md index a18f7cfc8db8..153ec83d52dd 100644 --- a/content/ja/docs/zero-code/python/troubleshooting.md +++ b/content/ja/docs/zero-code/python/troubleshooting.md @@ -93,7 +93,7 @@ gunicorn myapp.main:app --workers 4 ただし、複数の `--workers` を指定すると、自動計装を適用した場合にメトリクスの生成が壊れる可能性があります。 これは、ワーカー/子プロセスの作成であるフォークが、バックグラウンドスレッドとOpenTelemetry SDKの主要なコンポーネントが想定しているロックとの間に、各子プロセス間で不整合を生じさせるためです。 -特に、`PeriodicExportingMetricReader` は、データをエクスポーターに定期的にフラッシュするための独自のスレッドを生成します。 +具体的には、`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) で説明されているフォークとデッドロックも参照してください。 From 2f45075368c2195957d5e96d72973dcce999b794 Mon Sep 17 00:00:00 2001 From: Masaki Sugimoto <49427230+Msksgm@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:01:50 +0900 Subject: [PATCH 6/8] Update content/ja/docs/zero-code/python/troubleshooting.md Co-authored-by: Kohei Sugimoto <18735471+kohbis@users.noreply.github.com> --- content/ja/docs/zero-code/python/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/zero-code/python/troubleshooting.md b/content/ja/docs/zero-code/python/troubleshooting.md index 153ec83d52dd..5ceefe8e7746 100644 --- a/content/ja/docs/zero-code/python/troubleshooting.md +++ b/content/ja/docs/zero-code/python/troubleshooting.md @@ -112,7 +112,7 @@ OpenTelemetryでプリフォークサーバーを使用するためのいくつ ##### GunicornとUvicornWorkerでデプロイ {#deploy-with-gunicorn-and-uvicornworker} -複数のワーカーでサーバーを自動計装するには、ASGI（非同期サーバーゲートウェイインターフェース）アプリ（FastAPI、Starletteなど）の場合、`uvicorn.workers.UvicornWorker` を使用してGunicornでデプロイすることを推奨します。 +複数のワーカーを持つサーバーを自動計装するには、非同期サーバーゲートウェイインターフェース（ASGI）アプリ（FastAPI、Starletteなど）の場合、`uvicorn.workers.UvicornWorker` を使ったGunicornによるデプロイが推奨されます。 UvicornWorkerクラスは、バックグラウンドプロセスとスレッドの保持でフォークを処理するように特別に設計されています。 例を挙げましょう。 From 6a1d56aec800d7e59bc9d59925add477f9a60a71 Mon Sep 17 00:00:00 2001 From: Masaki Sugimoto <49427230+Msksgm@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:02:01 +0900 Subject: [PATCH 7/8] Update content/ja/docs/zero-code/python/troubleshooting.md Co-authored-by: Kohei Sugimoto <18735471+kohbis@users.noreply.github.com> --- content/ja/docs/zero-code/python/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/zero-code/python/troubleshooting.md b/content/ja/docs/zero-code/python/troubleshooting.md index 5ceefe8e7746..8d14dba4fde8 100644 --- a/content/ja/docs/zero-code/python/troubleshooting.md +++ b/content/ja/docs/zero-code/python/troubleshooting.md @@ -113,7 +113,7 @@ OpenTelemetryでプリフォークサーバーを使用するためのいくつ ##### GunicornとUvicornWorkerでデプロイ {#deploy-with-gunicorn-and-uvicornworker} 複数のワーカーを持つサーバーを自動計装するには、非同期サーバーゲートウェイインターフェース（ASGI）アプリ（FastAPI、Starletteなど）の場合、`uvicorn.workers.UvicornWorker` を使ったGunicornによるデプロイが推奨されます。 -UvicornWorkerクラスは、バックグラウンドプロセスとスレッドの保持でフォークを処理するように特別に設計されています。 +UvicornWorkerクラスは、バックグラウンドプロセスとスレッドを保持しながらフォークを処理するように特別に設計されています。 例を挙げましょう。 ```sh From bf493a133fd02eaab53f03058002c75564309f84 Mon Sep 17 00:00:00 2001 From: otelbot <197425009+otelbot@users.noreply.github.com> Date: Mon, 6 Oct 2025 23:05:18 +0000 Subject: [PATCH 8/8] Results from /fix directive --- content/ja/docs/zero-code/python/configuration.md | 2 +- content/ja/docs/zero-code/python/operator.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ja/docs/zero-code/python/configuration.md b/content/ja/docs/zero-code/python/configuration.md index e55bd7253fa7..bc89c24f6306 100644 --- a/content/ja/docs/zero-code/python/configuration.md +++ b/content/ja/docs/zero-code/python/configuration.md @@ -4,7 +4,7 @@ linkTitle: Configuration weight: 10 default_lang_commit: 276d7eb3f936deef6487cdd2b1d89822951da6c8 # prettier-ignore -cSpell:ignore: gevent healthcheck instrumentor monkeypatch myapp pyproject Starlette urllib +cSpell:ignore: gevent healthcheck instrumentor myapp pyproject Starlette urllib --- エージェントは次のいずれかの方法で高度に設定可能です。 diff --git a/content/ja/docs/zero-code/python/operator.md b/content/ja/docs/zero-code/python/operator.md index d216c7de6a75..a5dbaaaa9aaf 100644 --- a/content/ja/docs/zero-code/python/operator.md +++ b/content/ja/docs/zero-code/python/operator.md @@ -3,7 +3,7 @@ title: OpenTelemetryオペレーターを使用して自動計装を注入する linkTitle: Operator weight: 30 default_lang_commit: 276d7eb3f936deef6487cdd2b1d89822951da6c8 -cSpell:ignore: gevent grpcio monkeypatch myapp psutil PYTHONPATH +cSpell:ignore: gevent grpcio myapp psutil PYTHONPATH --- KubernetesでPythonサービスを実行する場合、[OpenTelemetryオペレーター](https://github.com/open-telemetry/opentelemetry-operator)を活用することで、各サービスを直接修正することなく自動計装を注入できます。