Skip to content

Commit

Permalink
[ja] add translation of signals (#4782)
Browse files Browse the repository at this point in the history
  • Loading branch information
Yoshi Yamaguchi authored Jul 5, 2024
1 parent a37e423 commit ebedee0
Show file tree
Hide file tree
Showing 5 changed files with 597 additions and 0 deletions.
16 changes: 16 additions & 0 deletions content/ja/docs/concepts/signals/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: シグナル
description: OpenTelemetryがサポートするテレメトリーのカテゴリについて学ぶ
weight: 11
default_lang_commit: 9b5e318
---

OpenTelemetryの目的は、**[シグナル][signals]** を収集、処理、エクスポートすることです。
シグナルは、オペレーティングシステムやプラットフォーム上で動作しているアプリケーションの基本的な活動を記述するシステム出力です。
シグナルは、温度やメモリ使用量のような特定の時点で測定したいもの、またはあなたが追跡したい分散システムのコンポーネントを通過するイベントです。
異なるシグナルをグループ化して、同じテクノロジーの内部動作を異なる角度から観察することもできる。

OpenTelemetry は現在、[トレース](/docs/concepts/signals/traces)[メトリクス](/docs/concepts/signals/metrics)[ログ](/docs/concepts/signals/logs)[バゲッジ](/docs/concepts/signals/baggage)をサポートしています。
_イベント_ は特定の種類のログで、_プロファイル_ はProfiling Working Groupによって[現在策定中](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0212-profiling-vision.md)です。

[signals]: /docs/specs/otel/glossary/#signals
57 changes: 57 additions & 0 deletions content/ja/docs/concepts/signals/baggage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
title: バゲッジ
weight: 4
description: シグナル間でやり取りされるコンテキスト情報
default_lang_commit: 9b5e318
---

OpenTelemetryでは、バゲッジ(Baggage)はコンテキストの隣にあるコンテキスト情報です。
バゲッジはキーバリューストアなので、[コンテキスト](/docs/concepts/context-propagation/#context)と一緒に好きなデータを[伝搬](/docs/concepts/context-propagation/#propagation)できます。

バゲッジは、サービスやプロセス間でデータを受け渡し、それらのサービス内の[トレース](/docs/concepts/signals/traces/)[メトリクス](/docs/concepts/signals/metrics/)[ログ](/docs/concepts/signals/logs/)に追加できるようにします。

## 例 {#example}

バゲッジは、トレースで、サービス間で追加データを伝播するためによく使用されます。

たとえば、リクエストの最初に `clientId` があるとします。
しかし、そのIDをトレース内のすべてのスパン、別のサービスのいくつかのメトリクス、そして途中のいくつかのログで利用できるようにしたいとします。
トレースは複数のサービスにまたがる可能性があるため、 `clientId` を多くのサービスにコピーすることなくデータを伝播する方法が必要です。
`clientId` をコードベースのあちこちにコピーすることなく、そのデータを伝播する方法が必要です。

[コンテキスト伝搬](/docs/concepts/signals/traces/#context-propagation)を使用して、これらのサービス間でバゲッジを渡すことで、 `clientId` を追加のスパン、メトリクス、またはログに追加できます。
さらに、計装は自動的にバゲッジを伝搬してくれます。

![OTel Baggage](/img/otel-baggage.svg)

## OTelバゲッジの使い道 {#what-should-otel-baggage-be-used-for}

バゲッジは、通常リクエストの開始時にのみ利用可能な情報を、さらに下流に含めるために使用するのが最適です。
これはたとえば、アカウント識別子、ユーザーID、製品ID、オリジンIPのようなものを含められます。

バゲッジを使ってこの情報を伝播することで、バックエンドのテレメトリーをより深く分析できます。
たとえば、データベース呼び出しを追跡するスパンにユーザーIDのような情報を含めると、「どのユーザーがもっとも遅いデータベース呼び出しを経験しているか」のような質問に、より簡単に答えられます。
また、下流の操作に関する情報をログに記録し、同じユーザーIDをログデータに含めることもできます。

![OTel Baggage](/img/otel-baggage-2.svg)

## バゲッジのセキュリティに関する懸念事項 {#baggage-security-considerations}

機密性の高いバゲッジのアイテムは、サードパーティのAPIなど、意図しないリソースと共有される可能性があります。
これは、自動計装が、サービスのネットワークリクエストのほとんどにバゲッジを含むためです。
具体的には、バゲッジやトレースコンテキストの他の部分はHTTPヘッダーで送信されるため、ネットワークトラフィックを検査する誰もがそれを見ることができます。
トラフィックがネットワーク内で制限されている場合は、このリスクは適用されないかもしれませんが、下流のサービスがバゲッジをネットワーク外に伝播する可能性があることに留意してください。

また、バゲッジのアイテムがあなたのものであることを確認するための完全性チェックは組み込まれていません。そのため、読み取る際には注意が必要です。

## バゲッジは属性とは異なる {#baggage-is-not-the-same-as-attributes}

バゲッジについて注意すべき重要な点は、バゲッジは独立したキーバリューストアであり、明示的に追加しない限り、スパン、メトリクス、ログの属性と関連付けられないということです。

バゲッジの要素を各テレメトリーの属性に追加するには、明示的にバゲッジからデータを読み取り、スパン、メトリクス、またはログに属性として追加する必要があります。

バゲッジの一般的な使用例は、トレース全体にわたって[スパン属性](/docs/concepts/signals/traces/#attributes)にデータを追加することなので、いくつかの言語には、スパン作成時にバゲッジからデータを属性として追加するバゲッジスパンプロセッサがあります。

> 詳細は[バゲッジ仕様][baggage specification]を参照のこと。
[baggage specification]: /docs/specs/otel/overview/#baggage-signal
89 changes: 89 additions & 0 deletions content/ja/docs/concepts/signals/logs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
title: ログ
weight: 3
description: イベントの記録
default_lang_commit: 9b5e318
---

**ログ**は、構造化(推奨)または非構造化された、メタデータを含む、タイムスタンプ付きのテキストレコードです。
すべてのテレメトリーシグナルの中で、ログは最も大きな遺産を持っています。
ほとんどのプログラミング言語には、組み込みのログ機能があるか、もしくはよく知られ、広く使われているログライブラリがあります。
ログは独立したデータソースですが、スパンに添付することもできます。
OpenTelemetryでは、分散トレースやメトリクスの一部でないデータはすべてログです。
たとえば、_イベント_ は特定の種類のログです。
ログは多くの場合、操作への入力、操作の結果、その操作をサポートするメタデータなどの詳細なデバッグ/診断情報を含んでいます。

トレースとメトリクスに関して、OpenTelemetryはゼロから設計するアプローチを取り、新しいAPIを指定し、このAPIの完全な実装を複数の言語SDKで提供します。

OpenTelemetryのログに対するアプローチは異なります。
既存のロギングソリューションは、言語や運用のエコシステムに広く普及しているので、OpenTelemetryは、それらのログ、トレースやメトリクスシグナル、そして、他のOpenTelemetryコンポーネント間の「ブリッジ」として機能します。
実際、ログのためのAPIは、この理由から「Logs Bridge API」と呼ばれています。

[ログ仕様][logs specification]には、この哲学の詳細が記載されています。

OpenTelemetry でのロギングの仕組みを理解するために、コードの計装の一翼を担うコンポーネントのリストを見てみましょう。

## ログアペンダー(Log Appender)/ブリッジ(Bridge) {#log-appender--bridge}

アプリケーション開発者としては、**Log Bridge API** はログアペンダー/ブリッジを構築するためのロギングライブラリ作者のために提供されているので、直接呼び出すべきではありません。
かわりに、好みのロギングライブラリを使い、OpenTelemetryのログレコードエクスポーターにログを出力できるログアペンダー(またはログブリッジ)を使うように設定するだけです。

OpenTelemetry言語SDKはこの機能を提供します。

## ロガープロバイダー {#logger-provider}

> **Logs Bridge API**の一部であり、ロギングライブラリの作者である場合にのみ使用すべきです。
ロガープロバイダー( `LoggerProvider` と呼ばれることもある)は `ロガー` のファクトリーです。
ほとんどの場合、ロガープロバイダは一度初期化され、そのライフサイクルはアプリケーションのライフサイクルと一致します。
ロガープロバイダーの初期化には、リソースとエクスポーターの初期化も含まれます。

## ロガー {#logger}

> **Logs Bridge API**の一部であり、ロギングライブラリの作者である場合にのみ使用すべきです。
ロガーはログレコードを作成します。ロガーはログプロバイダーから作成されます。

## ログレコードエクスポーター {#log-record-exporter}

ログレコードエクスポーターは、ログレコードをコンシューマーに送信します。
このコンシューマーは、デバッグや開発時間用の標準出力、OpenTelemetryコレクター、あるいは、お好みのオープンソースやベンダーのバックエンドです。

## ログレコード {#log-record}

ログレコードはイベントの記録を表します。
OpenTelemetryでは、ログレコードには2種類のフィールドがあります。

- 特定の型と意味を持つ名前付きトップレベルフィールド
- 任意の値と型のリソースと属性フィールド

トップレベルのフィールドは以下の通りです。

| フィールド名 | 説明 |
| -------------------- | ---------------------------------------- |
| Timestamp | イベントが発生した時刻 |
| ObservedTimestamp | イベントが観測された時刻 |
| TraceId | リクエストトレースID |
| SpanId | リクエストスパンID |
| TraceFlags | W3Cトレースフラグ |
| SeverityText | 重要度テキスト(ログレベルとも呼ばれる) |
| SeverityNumber | 重要度の数値 |
| Body | ログレコードの本文 |
| Resource | ログのソース |
| InstrumentationScope | ログを出力したスコープ |
| Attributes | イベントに関する追加情報 |

ログレコードとログフィールドの詳細については、[ログデータモデル](/docs/specs/otel/logs/data-model/) を参照してください。

## 言語サポート {#language-support}

ログは OpenTelemetry 仕様の [stable](/docs/specs/otel/versioning-and-stability/#stable) シグナルです。
ログAPIとSDKの各言語固有の実装については、ステータスは以下の通りです。

{{% signal-support-table "logs" %}}

## 仕様 {#specification}

OpenTelemetryのログについての詳細は、[ログ仕様][logs specification] を参照してください。

[logs specification]: /docs/specs/otel/overview/#log-signal
96 changes: 96 additions & 0 deletions content/ja/docs/concepts/signals/metrics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
title: メトリクス
weight: 2
description: 実行時に取得された測定値
default_lang_commit: 9b5e318
---

**メトリクス**とは、実行時に取得されるサービスの**測定値**のことです。
測定値を取得した瞬間は**メトリックイベント**として知られており、測定値そのものだけでなく、キャプチャした時刻と関連するメタデータから構成されます。

アプリケーションとリクエストのメトリクスは、可用性とパフォーマンスの重要な指標です。
カスタムメトリクスは、可用性指標がユーザー体験やビジネスにどのような影響を与えるかについての洞察を提供できます。
収集したデータを使用して、障害を警告したり、需要が高まったときにデプロイを自動的にスケールアップするスケジューリング決定をトリガーしたりできます。

OpenTelemetryのメトリクスがどのように機能するのかを理解するために、コードの計装の一部を担うコンポーネントのリストを見てみましょう。

## メータープロバイダー {#meter-provider}

メータープロバイダー(`MeterProvider` と呼ばれることもあります)は、`Meter`のファクトリーです。
ほとんどのアプリケーションでは、メータープロバイダーは一度だけ初期化され、そのライフサイクルはアプリケーションのライフサイクルと一致します。
メータープロバイダーの初期化には、リソースとエクスポータの初期化も含まれます。
これは通常、OpenTelemetryを使った計測の最初のステップです。
いくつかの言語SDKでは、グローバルなメータープロバイダーがすでに初期化されています。

## メーター {#meter}

メーターは[メトリクス計装](#metric-instruments)を作成し、実行時にサービスに関する測定値を取得します。
メーターはメータープロバイダーから作成されます。

## メトリクスエクスポーター {#metric-exporter}

メトリクスエクスポーターはメトリクスデータをコンシューマーに送ります。
このコンシューマーは、開発中のデバッグのための標準出力、OpenTelemetryコレクター、あるいは、あなたが選んだオープンソースやベンダーのバックエンドです。

## メトリクス計装 {#metric-instruments}

OpenTelemetryでは、計測は **メトリクス計装** によって行われます。メトリクス計装は以下のように定義されます。

- 名前
- 種類
- 単位(オプション)
- 説明(オプション)

名前、単位、説明は、開発者が自分で定義するか、リクエストやプロセスメトリクスのような一般的なものについては、[セマンティック規約](/docs/specs/semconv/general/metrics/)を介して定義されます。

計装の種類は以下のいずれかです。

- **Counter(カウンター)**: 時間とともに蓄積される値。これは車のオドメーターのようなものだと考えられます。
- **Asynchronous Counter(非同期カウンター)****カウンター** と同じですが、各エクスポートに対して一度だけ収集されます。
連続したインクリメントにアクセスできず、集約された値のみにアクセスできる場合に使用できます。
- **UpDownCounter(アップダウンカウンター)**: 時間の経過とともに蓄積されるけれども、減少することもある値。
たとえば、キューの長さは、キュー内のワークアイテムの数によって増減します。
- **Asynchronous UpDownCounter(非同期アップダウンカウンター)**: **アップダウンカウンター**と同じですが、各エクスポートに対して一度だけ収集されます。
連続的な変更にアクセスできず、集約された値(たとえば、現在のキューのサイズ)のみにアクセスできる場合に使用できます。
- **Gauge(ゲージ)**: 読み取った時点での現在の値を測定します。たとえば、自動車の燃料計など。ゲージは非同期です。
- **Histogram(ヒストグラム)**: リクエストのレイテンシーなどの値をクライアント側で集約したもの。
値の統計に興味がある場合は、ヒストグラムが良いでしょう。
たとえば、どれくらいのリクエストが1秒未満か、といった疑問に答えてくれます。

同期と非同期の計装、またどの種類の計装があなたのユースケースにもっとも適しているかについては、[補足ガイドライン](/docs/specs/otel/metrics/supplementary-guidelines/)を参照してください。

## 集約(アグリゲーション) {#aggregation}

メトリクス計装に加えて、**集約(アグリゲーション)**という概念も理解すべき重要なものです。
集約とは、多数の測定値を組み合わせて、ある時間ウィンドウの間に発生したメトリクスイベントに関する正確な統計値または推定統計値にする手法です。
OTLPプロトコルは、このような集約されたメトリクスを伝送します。
OpenTelemetry APIは、各計装に対してデフォルトの集約を提供します。これはビューを使ってオーバーライドできます。
OpenTelemetryプロジェクトは、ビジュアライザーやテレメトリーバックエンドでサポートされるデフォルトの集計を提供することを目指しています。

[リクエストトレース](/docs/concepts/signals/traces/)が、リクエストのライフサイクルを捕捉し、リクエストの個々の部分にコンテキストを提供することを意図しているのとは異なり、メトリクスは、集約された統計情報を提供することを意図しています。
メトリクスの使用例には、次のようなものがあります。

- プロトコルの種類ごとに、サービスによって読み取られた総バイト数を報告する。
- 読み込んだ総バイト数とリクエストごとのバイト数を報告する。
- システムコールの継続時間を報告する。
- 傾向を把握するためにリクエストサイズを報告する。
- プロセスのCPUまたはメモリ使用量を報告する。
- 口座の平均残高値を報告する。
- 現在処理中のアクティブなリクエストを報告する。

## ビュー {#views}

ビューは、SDKによって出力されるメトリクスをカスタマイズする柔軟性をSDKのユーザーに提供します。
どのメトリクス計装を処理するか、または無視するかをカスタマイズできます。
また、集約をカスタマイズしたり、メトリクスにどのような属性をレポートするかをカスタマイズすることもできます。

## 言語サポート {#language-support}

メトリクスはOpenTelemetry仕様の[stable](/docs/specs/otel/versioning-and-stability/#stable)シグナルです。
Metrics APIとSDKの各言語固有の実装については、ステータスは以下の通りです。

{{% signal-support-table "metrics" %}}

## 仕様 {#specification}

OpenTelemetryのメトリクスの詳細については、[メトリクス仕様](/docs/specs/otel/overview/#metric-signal)を参照してください。
Loading

0 comments on commit ebedee0

Please sign in to comment.