open-telemetry · chalin · Mar 11, 2025 · Jan 8, 2025 · Jan 8, 2025 · Feb 13, 2025
@@ -0,0 +1,19 @@
+---
+title: デプロイメント
+description: OpenTelemetryコレクターをデプロイするために適用できるパターン
+weight: 3
+default_lang_commit: b34ebe22b71962da96b898eb39a666ed57d447fe
+---
+
+OpenTelemetryコレクターは、さまざまな方法で、さまざまなユースケースに使用できる単一のバイナリから構成されています。
+このセクションでは、デプロイメントパターン、それらのユースケース、および長所と短所、クロス環境およびマルチバックエンドデプロイメントにおけるコレクター設定のベストプラクティスについて説明します。
+デプロイメントのセキュリティに関する考慮事項については、[コレクターホスティングのベストプラクティス][security]を参照してください。
+
+## リソース {#resources}
+
+- KubeCon NA 2021の[OpenTelemetryコレクターデプロイメントパターン][y-patterns]に関する講演
+- 講演に付随する[デプロイメントパターン][gh-patterns]
+
+[security]: /docs/security/hosting-best-practices/
+[gh-patterns]: https://github.com/jpkrohling/opentelemetry-collector-deployment-patterns/
+[y-patterns]: https://www.youtube.com/watch?v=WhRrwSHDBFs
@@ -0,0 +1,126 @@
+---
+title: エージェント
+description: コレクターにシグナルを送信し、そこからバックエンドに送信する理由と方法
+weight: 2
+default_lang_commit: b34ebe22b71962da96b898eb39a666ed57d447fe
+cSpell:ignore: prometheusremotewrite
+---
+
+コレクターのエージェントデプロイメントパターンは、OpenTelemetry SDKを使用して[計装された][instrumentation]アプリケーション（[OpenTelemetryプロトコル（OTLP）][otlp]を使用）や、他のコレクター（OTLPエクスポーターを使用）が、テレメトリーシグナルを[コレクター][collector]インスタンスに送信する構成です。
+このコレクターインスタンスは、アプリケーションと同じホストまたはアプリケーションの横に配置されたサイドカーやデーモンセットとして動作します。
+
+各クライアント側SDKまたはダウンストリームコレクターは、コレクターの場所を設定します。
+
+![分散型コレクターデプロイメント概念](../../img/otel-agent-sdk.svg)
+
+1. アプリケーションで、SDKがOTLPデータをコレクターに送信するように設定されます。
+1. コレクターは、テレメトリーデータを1つ以上のバックエンドに送信するように設定されます。
+
+## 例 {#example}
+
+コレクターのエージェントデプロイメントパターンの具体例は以下のようになります。
+たとえば、[Javaアプリケーションを計装してメトリクスをエクスポート][instrument-java-metrics]するためにOpenTelemetry Java SDKを使用します。
+アプリケーションのコンテキスト内で、`OTEL_METRICS_EXPORTER`を`otlp`（デフォルト値）に設定し、[OTLPエクスポーター][otlp-exporter]をコレクターのアドレスで設定します。たとえば、Bashまたは`zsh`シェルでは、次のように設定します。
+
+```shell
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318
+```
+
+`collector.example.com:4318` で動作するコレクターは次のように設定されます。
+
+{{< tabpane text=true >}} {{% tab Traces %}}
+
+```yaml
+receivers:
+  otlp: # アプリケーションがトレースを送信するOTLPレシーバー
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+
+exporters:
+  otlp/jaeger: # JaegerはOTLPを直接サポートしています
+    endpoint: https://jaeger.example.com:4317
+
+service:
+  pipelines:
+    traces/dev:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/jaeger]
+```
+
+{{% /tab %}} {{% tab Metrics %}}
+
+```yaml
+receivers:
+  otlp: # アプリケーションがメトリクスを送信するOTLPレシーバー
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+
+exporters:
+  prometheusremotewrite: # PRWエクスポーター、メトリクスをバックエンドに取り込む
+    endpoint: https://prw.example.com/v1/api/remote_write
+
+service:
+  pipelines:
+    metrics/prod:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [prometheusremotewrite]
+```
+
+{{% /tab %}} {{% tab Logs %}}
+
+```yaml
+receivers:
+  otlp: # アプリケーションがログを送信するOTLPレシーバー
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+
+exporters:
+  file: # ファイルエクスポーター、ログをローカルファイルに取り込む
+    path: ./app42_example.log
+    rotation:
+
+service:
+  pipelines:
+    logs/dev:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [file]
+```
+
+{{% /tab %}} {{< /tabpane >}}
+
+実際に試してみたい場合は、エンドツーエンドの[Java][java-otlp-example]や[Python][py-otlp-example]の例で確認できます。
+
+## トレードオフ {#tradeoffs}
+
+長所：
+
+- 始めやすい
+- アプリケーションとコレクターの間に明確な1:1のマッピング
+
+短所：
+
+- スケーラビリティ（人的および負荷面）
+- 柔軟性に欠ける
+
+[instrumentation]: /docs/languages/
+[otlp]: /docs/specs/otel/protocol/
+[collector]: /docs/collector/
+[instrument-java-metrics]: /docs/languages/java/api/#meterprovider
+[otlp-exporter]: /docs/specs/otel/protocol/exporter/
+[java-otlp-example]: https://github.com/open-telemetry/opentelemetry-java-docs/tree/main/otlp
+[py-otlp-example]: https://opentelemetry-python.readthedocs.io/en/stable/examples/metrics/instruments/README.html
@@ -0,0 +1,245 @@
+---
+title: ゲートウェイ
+description: シグナルを単一のOTLPエンドポイントに送信し、そこからバックエンドに送信する理由と方法
+weight: 3
+default_lang_commit: b34ebe22b71962da96b898eb39a666ed57d447fe
+# prettier-ignore
+cSpell:ignore: filelogreceiver hostmetricsreceiver hostnames loadbalancer loadbalancing resourcedetectionprocessor
+---
+
+コレクターのゲートウェイデプロイメントパターンは、アプリケーション（または他のコレクター）がテレメトリーシグナルを単一のOTLPエンドポイントに送信し、そのエンドポイントが実行されている1つ以上のコレクターインスタンスによって処理される構成です。
+このコレクターインスタンスは、通常、クラスターごと、データセンターごと、またはリージョンごとに単独のサービス（たとえばKubernetesのデプロイメント）として実行されます。
+
+一般的なケースでは、アウトオブボックスのロードバランサーを使用して、コレクター間で負荷を分散できます。
+
+![ゲートウェイデプロイメント概念](../../img/otel-gateway-sdk.svg)
+
+テレメトリーデータの処理が特定のコレクターで行われる必要があるユースケースでは、2層の設定を使用します。
+1層目のコレクターは、[Trace ID/サービス名を意識したロードバランシングエクスポーター][lb-exporter]を使用して設定され、2層目ではスケールアウトを処理するコレクターが使用されます。
+たとえば、[テイルサンプリングプロセッサー][tailsample-processor]を使用する場合、すべてのスパンが同じコレクターインスタンスに到達し、そこでそのサンプリングポリシーが適用されるように、ロードバランシングエクスポーターを使用する必要があります。
+
+ロードバランシングエクスポーターを使用する場合の例を見てみましょう。
+
+![ロードバランシングエクスポーターを使用したゲートウェイデプロイメント](../../img/otel-gateway-lb-sdk.svg)
+
+1. アプリケーションで、SDKがOTLPデータを中央の場所に送信するように設定されます。
+2. ロードバランシングエクスポーターを使用して設定されたコレクターが、シグナルを複数のコレクターに分散します。
+3. コレクターはテレメトリーデータを1つ以上のバックエンドに送信するように設定されます。
+
+## 例 {#examples}
+
+### NGINXを「アウトオブボックス」のロードバランサーとして使用 {#nginx-as-an-out-of-the-box-load-balancer}
+
+2つのコレクター（`collector1`と`collector2`）が設定され、NGINXを使用してその間でトラフィックをロードバランシングしたい場合、次の設定を使用できます。
+
+```nginx
+server {
+    listen 4317 http2;
+    server_name _;
+
+    location / {
+            grpc_pass      grpc://collector4317;
+            grpc_next_upstream     error timeout invalid_header http_500;
+            grpc_connect_timeout   2;
+            grpc_set_header        Host            $host;
+            grpc_set_header        X-Real-IP       $remote_addr;
+            grpc_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+
+server {
+    listen 4318;
+    server_name _;
+
+    location / {
+            proxy_pass      http://collector4318;
+            proxy_redirect  off;
+            proxy_next_upstream     error timeout invalid_header http_500;
+            proxy_connect_timeout   2;
+            proxy_set_header        Host            $host;
+            proxy_set_header        X-Real-IP       $remote_addr;
+            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+
+upstream collector4317 {
+    server collector1:4317;
+    server collector2:4317;
+}
+
+upstream collector4318 {
+    server collector1:4318;
+    server collector2:4318;
+}
+```
+
+### ロードバランシングエクスポーター {#load-balancing-exporter}
+
+コレクターの中央集権型デプロイメントパターンの具体的な例として、まずロードバランシングエクスポーターについて詳しく見ていきましょう。
+これには2つの主な設定項目があります：
+
+- `resolver`は、下流のコレクター（またはバックエンド）をどこで見つけるかを決定します。
+  ここで`static`サブキーを使用すると、コレクターのURLを手動で列挙する必要があります。
+  他のサポートされているリゾルバーはDNSリゾルバーで、定期的に更新を確認し、IPアドレスを解決します。
+  このリゾルバータイプでは、`hostname`サブキーがIPアドレスのリストを取得するために問い合わせるホスト名を指定します。
+- `routing_key`フィールドを使用するとロードバランシングエクスポーターがスパンを特定の下流のコレクターにルーティングするように指示します。
+  このフィールドを`traceID`（デフォルト）に設定すると、ロードバランシングエクスポーターは`traceID`に基づいてスパンをエクスポートします。
+  その他の場合、`routing_key`に`service`を設定すると、サービス名に基づいてスパンをエクスポートします。
+  これは、[スパンメトリクスコネクター][spanmetrics-connector]のようなコネクターを使用する際に有用で、サービスのすべてのスパンが同じ下流のコレクターに送信され、メトリクス収集が行われ、正確な集約が保証されます。
+
+OTLPエンドポイントを提供する最初の層のコレクターは次のように設定されます。
+
+{{< tabpane text=true >}} {{% tab Static %}}
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+exporters:
+  loadbalancing:
+    protocol:
+      otlp:
+        tls:
+          insecure: true
+    resolver:
+      static:
+        hostnames:
+          - collector-1.example.com:4317
+          - collector-2.example.com:5317
+          - collector-3.example.com
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [loadbalancing]
+```
+
+{{% /tab %}} {{% tab DNS %}}
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+exporters:
+  loadbalancing:
+    protocol:
+      otlp:
+        tls:
+          insecure: true
+    resolver:
+      dns:
+        hostname: collectors.example.com
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [loadbalancing]
+```
+
+{{% /tab %}} {{% tab "DNS with service" %}}
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+exporters:
+  loadbalancing:
+    routing_key: service
+    protocol:
+      otlp:
+        tls:
+          insecure: true
+    resolver:
+      dns:
+        hostname: collectors.example.com
+        port: 5317
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [loadbalancing]
+```
+
+{{% /tab %}} {{< /tabpane >}}
+
+ロードバランシングエクスポーターは、`otelcol_loadbalancer_num_backends`や`otelcol_loadbalancer_backend_latency`などのメトリクスを出力し、これらを使用してOTLPエンドポイントコレクターのヘルスとパフォーマンスを監視できます。
+
+## エージェントとゲートウェイのコレクターの組み合わせたデプロイメント {#combined-deployment-of-collectors-as-agents-and-gateways}
+
+複数のOpenTelemetryコレクターをデプロイする場合、エージェントとしてもゲートウェイとしてもコレクターを実行することがよくあります。
+
+以下の図は、このような組み合わせたデプロイメントのアーキテクチャを示しています。
+
+- エージェントデプロイメントパターンで実行されるコレクター（各ホストで実行され、Kubernetesデーモンセットのように）を使用して、ホスト上で実行されるサービスからのテレメトリーとホストのテレメトリー（ホストメトリクスやスクラップログなど）を収集します。
+- ゲートウェイデプロイメントパターンで実行されるコレクターを使用して、データの処理（たとえばフィルタリング、サンプリング、バックエンドへのエクスポートなど）を行います。
+
+![ゲートウェイ](otel-gateway-arch.svg)
+
+この組み合わせたデプロイメントパターンは、コレクター内でホストごとにユニークである必要があるコンポーネントや、アプリケーションが実行されている同じホストにしか利用できない情報を消費するコンポーネントを使用する場合に必要です。
+
+- [`hostmetricsreceiver`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver)や[`filelogreceiver`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver)のようなレシーバーは、ホストインスタンスごとにユニークである必要があります。
+  これらのレシーバーを複数実行すると、データが重複します。
+
+- [`resourcedetectionprocessor`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor)のようなプロセッサーは、ホスト、コレクター、アプリケーションの情報を追加するために使用されます。
+  リモートマシン上のコレクター内でこれらを実行すると、不正確なデータが生成されます。
+
+## トレードオフ {#tradeoffs}
+
+長所：
+
+- 中央で管理された認証情報などの関心事を分離できる
+- 中央集権型でポリシー（たとえば、特定のログのフィルタリングやサンプリング）を管理できる
+
+短所：
+
+- 管理し、失敗する可能性があるものがさらに一つ増える（複雑さ）
+- 階層型コレクターの場合、追加のレイテンシーがかかる
+- 全体的なリソース使用量が増加する（コスト）
+
+[lb-exporter]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/loadbalancingexporter
+[tailsample-processor]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor
+[spanmetrics-connector]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector
+
+## 複数のコレクターとシングルライター原則 {#multiple-collectors-and-the-single-writer-principle}
+
+OTLP内のすべてのメトリクスデータストリームには、[シングルライター](/docs/specs/otel/metrics/data-model/#single-writer)が必要です。
+ゲートウェイ構成で複数のコレクターをデプロイする際は、すべてのメトリクスデータストリームに対してシングルライターとグローバルにユニークなIDを確保することが重要です。
+
+### 潜在的な問題 {#potential-problems}
+
+複数のアプリケーションが同じデータを変更または報告する並列アクセスは、データ損失やデータ品質の劣化を引き起こす可能性があります。
+たとえば、リソース上で複数のソースから一貫性のないデータを確認する場合があります。
+異なるソースがリソースをユニークに識別できないため、上書きされることがあります。
+
+データにパターンがあれば、これが発生しているかどうかを確認できます。
+たとえば、同じシリーズにおいて説明のつかないギャップやジャンプがある場合、複数のコレクターが同じサンプルを送信している可能性があります。
+また、バックエンドでエラーを見つけることもあります。
+たとえば、Prometheusバックエンドでは次のようなエラーが表示されることがあります。
+
+`Error on ingesting out-of-order samples`
+
+このエラーは、2つのジョブに同じターゲットが存在し、タイムスタンプの順序が間違っていることを示唆している可能性があります。
+たとえば：
+
+- メトリクス`M1`は、13:56:04のタイムスタンプで`100`という値を持って受信された
+- メトリクス`M1`は、13:56:24のタイムスタンプで`120`という値を持って受信された
+- メトリクス`M1`は、13:56:04のタイムスタンプで`110`という値を持って受信された
+- メトリクス`M1`は、13:56:24のタイムスタンプで`120`という値を持って受信された
+- メトリクス`M1`は、13:56:04のタイムスタンプで`110`という値を持って受信された
+
+### ベストプラクティス {#best-practices}
+
+- [Kubernetes属性プロセッサー](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/k8sattributesprocessor)を使用して、異なるKubernetesリソースにラベルを追加します。
+- [リソース検出プロセッサー](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md)を使用して、ホストからリソース情報を検出し、リソースメタデータを収集します。