Skip to content

Commit 4ba9013

Browse files
katzchangymotongpoo
katzchang
and
ymotongpoo
authored
[ja] translate collector/deployment into ja (#5900)
Co-authored-by: Yoshi Yamaguchi <yoshiyyy@amazon.co.jp>
1 parent e330a3d commit 4ba9013

File tree

4 files changed

+420
-0
lines changed

4 files changed

+420
-0
lines changed

‎content/ja/docs/collector/deployment/_index.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: デプロイメント
3+
description: OpenTelemetryコレクターをデプロイするために適用できるパターン
4+
weight: 3
5+
default_lang_commit: b34ebe22b71962da96b898eb39a666ed57d447fe
6+
---
7+
8+
OpenTelemetryコレクターは、さまざまな方法で、さまざまなユースケースに使用できる単一のバイナリから構成されています。
9+
このセクションでは、デプロイメントパターン、それらのユースケース、および長所と短所、クロス環境およびマルチバックエンドデプロイメントにおけるコレクター設定のベストプラクティスについて説明します。
10+
デプロイメントのセキュリティに関する考慮事項については、[コレクターホスティングのベストプラクティス][security]を参照してください。
11+
12+
## リソース {#resources}
13+
14+
- KubeCon NA 2021の[OpenTelemetryコレクターデプロイメントパターン][y-patterns]に関する講演
15+
- 講演に付随する[デプロイメントパターン][gh-patterns]
16+
17+
[security]: /docs/security/hosting-best-practices/
18+
[gh-patterns]: https://github.com/jpkrohling/opentelemetry-collector-deployment-patterns/
19+
[y-patterns]: https://www.youtube.com/watch?v=WhRrwSHDBFs

‎content/ja/docs/collector/deployment/agent.md

+126
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: エージェント
3+
description: コレクターにシグナルを送信し、そこからバックエンドに送信する理由と方法
4+
weight: 2
5+
default_lang_commit: b34ebe22b71962da96b898eb39a666ed57d447fe
6+
cSpell:ignore: prometheusremotewrite
7+
---
8+
9+
コレクターのエージェントデプロイメントパターンは、OpenTelemetry SDKを使用して[計装された][instrumentation]アプリケーション（[OpenTelemetryプロトコル（OTLP）][otlp]を使用）や、他のコレクター（OTLPエクスポーターを使用）が、テレメトリーシグナルを[コレクター][collector]インスタンスに送信する構成です。
10+
このコレクターインスタンスは、アプリケーションと同じホストまたはアプリケーションの横に配置されたサイドカーやデーモンセットとして動作します。
11+
12+
各クライアント側SDKまたはダウンストリームコレクターは、コレクターの場所を設定します。
13+
14+
![分散型コレクターデプロイメント概念](../../img/otel-agent-sdk.svg)
15+
16+
1. アプリケーションで、SDKがOTLPデータをコレクターに送信するように設定されます。
17+
1. コレクターは、テレメトリーデータを1つ以上のバックエンドに送信するように設定されます。
18+
19+
## 例 {#example}
20+
21+
コレクターのエージェントデプロイメントパターンの具体例は以下のようになります。
22+
たとえば、[Javaアプリケーションを計装してメトリクスをエクスポート][instrument-java-metrics]するためにOpenTelemetry Java SDKを使用します。
23+
アプリケーションのコンテキスト内で、`OTEL_METRICS_EXPORTER`を`otlp`（デフォルト値）に設定し、[OTLPエクスポーター][otlp-exporter]をコレクターのアドレスで設定します。たとえば、Bashまたは`zsh`シェルでは、次のように設定します。
24+
25+
```shell
26+
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318
27+
```
28+
29+
`collector.example.com:4318` で動作するコレクターは次のように設定されます。
30+
31+
{{< tabpane text=true >}} {{% tab Traces %}}
32+
33+
```yaml
34+
receivers:
35+
otlp: # アプリケーションがトレースを送信するOTLPレシーバー
36+
protocols:
37+
http:
38+
endpoint: 0.0.0.0:4318
39+
40+
processors:
41+
batch:
42+
43+
exporters:
44+
otlp/jaeger: # JaegerはOTLPを直接サポートしています
45+
endpoint: https://jaeger.example.com:4317
46+
47+
service:
48+
pipelines:
49+
traces/dev:
50+
receivers: [otlp]
51+
processors: [batch]
52+
exporters: [otlp/jaeger]
53+
```
54+
55+
{{% /tab %}} {{% tab Metrics %}}
56+
57+
```yaml
58+
receivers:
59+
otlp: # アプリケーションがメトリクスを送信するOTLPレシーバー
60+
protocols:
61+
http:
62+
endpoint: 0.0.0.0:4318
63+
64+
processors:
65+
batch:
66+
67+
exporters:
68+
prometheusremotewrite: # PRWエクスポーター、メトリクスをバックエンドに取り込む
69+
endpoint: https://prw.example.com/v1/api/remote_write
70+
71+
service:
72+
pipelines:
73+
metrics/prod:
74+
receivers: [otlp]
75+
processors: [batch]
76+
exporters: [prometheusremotewrite]
77+
```
78+
79+
{{% /tab %}} {{% tab Logs %}}
80+
81+
```yaml
82+
receivers:
83+
otlp: # アプリケーションがログを送信するOTLPレシーバー
84+
protocols:
85+
http:
86+
endpoint: 0.0.0.0:4318
87+
88+
processors:
89+
batch:
90+
91+
exporters:
92+
file: # ファイルエクスポーター、ログをローカルファイルに取り込む
93+
path: ./app42_example.log
94+
rotation:
95+
96+
service:
97+
pipelines:
98+
logs/dev:
99+
receivers: [otlp]
100+
processors: [batch]
101+
exporters: [file]
102+
```
103+
104+
{{% /tab %}} {{< /tabpane >}}
105+
106+
実際に試してみたい場合は、エンドツーエンドの[Java][java-otlp-example]や[Python][py-otlp-example]の例で確認できます。
107+
108+
## トレードオフ {#tradeoffs}
109+
110+
長所：
111+
112+
- 始めやすい
113+
- アプリケーションとコレクターの間に明確な1:1のマッピング
114+
115+
短所：
116+
117+
- スケーラビリティ（人的および負荷面）
118+
- 柔軟性に欠ける
119+
120+
[instrumentation]: /docs/languages/
121+
[otlp]: /docs/specs/otel/protocol/
122+
[collector]: /docs/collector/
123+
[instrument-java-metrics]: /docs/languages/java/api/#meterprovider
124+
[otlp-exporter]: /docs/specs/otel/protocol/exporter/
125+
[java-otlp-example]: https://github.com/open-telemetry/opentelemetry-java-docs/tree/main/otlp
126+
[py-otlp-example]: https://opentelemetry-python.readthedocs.io/en/stable/examples/metrics/instruments/README.html

‎content/ja/docs/collector/deployment/gateway/index.md

+245
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
title: ゲートウェイ
3+
description: シグナルを単一のOTLPエンドポイントに送信し、そこからバックエンドに送信する理由と方法
4+
weight: 3
5+
default_lang_commit: b34ebe22b71962da96b898eb39a666ed57d447fe
6+
# prettier-ignore
7+
cSpell:ignore: filelogreceiver hostmetricsreceiver hostnames loadbalancer loadbalancing resourcedetectionprocessor
8+
---
9+
10+
コレクターのゲートウェイデプロイメントパターンは、アプリケーション（または他のコレクター）がテレメトリーシグナルを単一のOTLPエンドポイントに送信し、そのエンドポイントが実行されている1つ以上のコレクターインスタンスによって処理される構成です。
11+
このコレクターインスタンスは、通常、クラスターごと、データセンターごと、またはリージョンごとに単独のサービス（たとえばKubernetesのデプロイメント）として実行されます。
12+
13+
一般的なケースでは、アウトオブボックスのロードバランサーを使用して、コレクター間で負荷を分散できます。
14+
15+
![ゲートウェイデプロイメント概念](../../img/otel-gateway-sdk.svg)
16+
17+
テレメトリーデータの処理が特定のコレクターで行われる必要があるユースケースでは、2層の設定を使用します。
18+
1層目のコレクターは、[Trace ID/サービス名を意識したロードバランシングエクスポーター][lb-exporter]を使用して設定され、2層目ではスケールアウトを処理するコレクターが使用されます。
19+
たとえば、[テイルサンプリングプロセッサー][tailsample-processor]を使用する場合、すべてのスパンが同じコレクターインスタンスに到達し、そこでそのサンプリングポリシーが適用されるように、ロードバランシングエクスポーターを使用する必要があります。
20+
21+
ロードバランシングエクスポーターを使用する場合の例を見てみましょう。
22+
23+
![ロードバランシングエクスポーターを使用したゲートウェイデプロイメント](../../img/otel-gateway-lb-sdk.svg)
24+
25+
1. アプリケーションで、SDKがOTLPデータを中央の場所に送信するように設定されます。
26+
2. ロードバランシングエクスポーターを使用して設定されたコレクターが、シグナルを複数のコレクターに分散します。
27+
3. コレクターはテレメトリーデータを1つ以上のバックエンドに送信するように設定されます。
28+
29+
## 例 {#examples}
30+
31+
### NGINXを「アウトオブボックス」のロードバランサーとして使用 {#nginx-as-an-out-of-the-box-load-balancer}
32+
33+
2つのコレクター（`collector1`と`collector2`）が設定され、NGINXを使用してその間でトラフィックをロードバランシングしたい場合、次の設定を使用できます。
34+
35+
```nginx
36+
server {
37+
listen 4317 http2;
38+
server_name _;
39+
40+
location / {
41+
grpc_pass grpc://collector4317;
42+
grpc_next_upstream error timeout invalid_header http_500;
43+
grpc_connect_timeout 2;
44+
grpc_set_header Host $host;
45+
grpc_set_header X-Real-IP $remote_addr;
46+
grpc_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
47+
}
48+
}
49+
50+
server {
51+
listen 4318;
52+
server_name _;
53+
54+
location / {
55+
proxy_pass http://collector4318;
56+
proxy_redirect off;
57+
proxy_next_upstream error timeout invalid_header http_500;
58+
proxy_connect_timeout 2;
59+
proxy_set_header Host $host;
60+
proxy_set_header X-Real-IP $remote_addr;
61+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
62+
}
63+
}
64+
65+
upstream collector4317 {
66+
server collector1:4317;
67+
server collector2:4317;
68+
}
69+
70+
upstream collector4318 {
71+
server collector1:4318;
72+
server collector2:4318;
73+
}
74+
```
75+
76+
### ロードバランシングエクスポーター {#load-balancing-exporter}
77+
78+
コレクターの中央集権型デプロイメントパターンの具体的な例として、まずロードバランシングエクスポーターについて詳しく見ていきましょう。
79+
これには2つの主な設定項目があります：
80+
81+
- `resolver`は、下流のコレクター（またはバックエンド）をどこで見つけるかを決定します。
82+
ここで`static`サブキーを使用すると、コレクターのURLを手動で列挙する必要があります。
83+
他のサポートされているリゾルバーはDNSリゾルバーで、定期的に更新を確認し、IPアドレスを解決します。
84+
このリゾルバータイプでは、`hostname`サブキーがIPアドレスのリストを取得するために問い合わせるホスト名を指定します。
85+
- `routing_key`フィールドを使用するとロードバランシングエクスポーターがスパンを特定の下流のコレクターにルーティングするように指示します。
86+
このフィールドを`traceID`（デフォルト）に設定すると、ロードバランシングエクスポーターは`traceID`に基づいてスパンをエクスポートします。
87+
その他の場合、`routing_key`に`service`を設定すると、サービス名に基づいてスパンをエクスポートします。
88+
これは、[スパンメトリクスコネクター][spanmetrics-connector]のようなコネクターを使用する際に有用で、サービスのすべてのスパンが同じ下流のコレクターに送信され、メトリクス収集が行われ、正確な集約が保証されます。
89+
90+
OTLPエンドポイントを提供する最初の層のコレクターは次のように設定されます。
91+
92+
{{< tabpane text=true >}} {{% tab Static %}}
93+
94+
```yaml
95+
receivers:
96+
otlp:
97+
protocols:
98+
grpc:
99+
endpoint: 0.0.0.0:4317
100+
101+
exporters:
102+
loadbalancing:
103+
protocol:
104+
otlp:
105+
tls:
106+
insecure: true
107+
resolver:
108+
static:
109+
hostnames:
110+
- collector-1.example.com:4317
111+
- collector-2.example.com:5317
112+
- collector-3.example.com
113+
114+
service:
115+
pipelines:
116+
traces:
117+
receivers: [otlp]
118+
exporters: [loadbalancing]
119+
```
120+
121+
{{% /tab %}} {{% tab DNS %}}
122+
123+
```yaml
124+
receivers:
125+
otlp:
126+
protocols:
127+
grpc:
128+
endpoint: 0.0.0.0:4317
129+
130+
exporters:
131+
loadbalancing:
132+
protocol:
133+
otlp:
134+
tls:
135+
insecure: true
136+
resolver:
137+
dns:
138+
hostname: collectors.example.com
139+
140+
service:
141+
pipelines:
142+
traces:
143+
receivers: [otlp]
144+
exporters: [loadbalancing]
145+
```
146+
147+
{{% /tab %}} {{% tab "DNS with service" %}}
148+
149+
```yaml
150+
receivers:
151+
otlp:
152+
protocols:
153+
grpc:
154+
endpoint: 0.0.0.0:4317
155+
156+
exporters:
157+
loadbalancing:
158+
routing_key: service
159+
protocol:
160+
otlp:
161+
tls:
162+
insecure: true
163+
resolver:
164+
dns:
165+
hostname: collectors.example.com
166+
port: 5317
167+
168+
service:
169+
pipelines:
170+
traces:
171+
receivers: [otlp]
172+
exporters: [loadbalancing]
173+
```
174+
175+
{{% /tab %}} {{< /tabpane >}}
176+
177+
ロードバランシングエクスポーターは、`otelcol_loadbalancer_num_backends`や`otelcol_loadbalancer_backend_latency`などのメトリクスを出力し、これらを使用してOTLPエンドポイントコレクターのヘルスとパフォーマンスを監視できます。
178+
179+
## エージェントとゲートウェイのコレクターの組み合わせたデプロイメント {#combined-deployment-of-collectors-as-agents-and-gateways}
180+
181+
複数のOpenTelemetryコレクターをデプロイする場合、エージェントとしてもゲートウェイとしてもコレクターを実行することがよくあります。
182+
183+
以下の図は、このような組み合わせたデプロイメントのアーキテクチャを示しています。
184+
185+
- エージェントデプロイメントパターンで実行されるコレクター（各ホストで実行され、Kubernetesデーモンセットのように）を使用して、ホスト上で実行されるサービスからのテレメトリーとホストのテレメトリー（ホストメトリクスやスクラップログなど）を収集します。
186+
- ゲートウェイデプロイメントパターンで実行されるコレクターを使用して、データの処理（たとえばフィルタリング、サンプリング、バックエンドへのエクスポートなど）を行います。
187+
188+
![ゲートウェイ](otel-gateway-arch.svg)
189+
190+
この組み合わせたデプロイメントパターンは、コレクター内でホストごとにユニークである必要があるコンポーネントや、アプリケーションが実行されている同じホストにしか利用できない情報を消費するコンポーネントを使用する場合に必要です。
191+
192+
- [`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)のようなレシーバーは、ホストインスタンスごとにユニークである必要があります。
193+
これらのレシーバーを複数実行すると、データが重複します。
194+
195+
- [`resourcedetectionprocessor`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor)のようなプロセッサーは、ホスト、コレクター、アプリケーションの情報を追加するために使用されます。
196+
リモートマシン上のコレクター内でこれらを実行すると、不正確なデータが生成されます。
197+
198+
## トレードオフ {#tradeoffs}
199+
200+
長所：
201+
202+
- 中央で管理された認証情報などの関心事を分離できる
203+
- 中央集権型でポリシー（たとえば、特定のログのフィルタリングやサンプリング）を管理できる
204+
205+
短所：
206+
207+
- 管理し、失敗する可能性があるものがさらに一つ増える（複雑さ）
208+
- 階層型コレクターの場合、追加のレイテンシーがかかる
209+
- 全体的なリソース使用量が増加する（コスト）
210+
211+
[lb-exporter]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/loadbalancingexporter
212+
[tailsample-processor]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor
213+
[spanmetrics-connector]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector
214+
215+
## 複数のコレクターとシングルライター原則 {#multiple-collectors-and-the-single-writer-principle}
216+
217+
OTLP内のすべてのメトリクスデータストリームには、[シングルライター](/docs/specs/otel/metrics/data-model/#single-writer)が必要です。
218+
ゲートウェイ構成で複数のコレクターをデプロイする際は、すべてのメトリクスデータストリームに対してシングルライターとグローバルにユニークなIDを確保することが重要です。
219+
220+
### 潜在的な問題 {#potential-problems}
221+
222+
複数のアプリケーションが同じデータを変更または報告する並列アクセスは、データ損失やデータ品質の劣化を引き起こす可能性があります。
223+
たとえば、リソース上で複数のソースから一貫性のないデータを確認する場合があります。
224+
異なるソースがリソースをユニークに識別できないため、上書きされることがあります。
225+
226+
データにパターンがあれば、これが発生しているかどうかを確認できます。
227+
たとえば、同じシリーズにおいて説明のつかないギャップやジャンプがある場合、複数のコレクターが同じサンプルを送信している可能性があります。
228+
また、バックエンドでエラーを見つけることもあります。
229+
たとえば、Prometheusバックエンドでは次のようなエラーが表示されることがあります。
230+
231+
`Error on ingesting out-of-order samples`
232+
233+
このエラーは、2つのジョブに同じターゲットが存在し、タイムスタンプの順序が間違っていることを示唆している可能性があります。
234+
たとえば：
235+
236+
- メトリクス`M1`は、13:56:04のタイムスタンプで`100`という値を持って受信された
237+
- メトリクス`M1`は、13:56:24のタイムスタンプで`120`という値を持って受信された
238+
- メトリクス`M1`は、13:56:04のタイムスタンプで`110`という値を持って受信された
239+
- メトリクス`M1`は、13:56:24のタイムスタンプで`120`という値を持って受信された
240+
- メトリクス`M1`は、13:56:04のタイムスタンプで`110`という値を持って受信された
241+
242+
### ベストプラクティス {#best-practices}
243+
244+
- [Kubernetes属性プロセッサー](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/k8sattributesprocessor)を使用して、異なるKubernetesリソースにラベルを追加します。
245+
- [リソース検出プロセッサー](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md)を使用して、ホストからリソース情報を検出し、リソースメタデータを収集します。

0 commit comments

Comments
 (0)