diff --git a/content/ja/docs/concepts/signals/_index.md b/content/ja/docs/concepts/signals/_index.md new file mode 100644 index 000000000000..d136ab668f9e --- /dev/null +++ b/content/ja/docs/concepts/signals/_index.md @@ -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 diff --git a/content/ja/docs/concepts/signals/baggage.md b/content/ja/docs/concepts/signals/baggage.md new file mode 100644 index 000000000000..bfb927eceabf --- /dev/null +++ b/content/ja/docs/concepts/signals/baggage.md @@ -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 diff --git a/content/ja/docs/concepts/signals/logs.md b/content/ja/docs/concepts/signals/logs.md new file mode 100644 index 000000000000..56b2a121bebb --- /dev/null +++ b/content/ja/docs/concepts/signals/logs.md @@ -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 diff --git a/content/ja/docs/concepts/signals/metrics.md b/content/ja/docs/concepts/signals/metrics.md new file mode 100644 index 000000000000..1eba182065b2 --- /dev/null +++ b/content/ja/docs/concepts/signals/metrics.md @@ -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)を参照してください。 diff --git a/content/ja/docs/concepts/signals/traces.md b/content/ja/docs/concepts/signals/traces.md new file mode 100644 index 000000000000..90ab6ea4cc3f --- /dev/null +++ b/content/ja/docs/concepts/signals/traces.md @@ -0,0 +1,339 @@ +--- +title: トレース +weight: 1 +cSpell:ignore: Guten +description: アプリケーションを通過するリクエストの経路 +default_lang_commit: 9b5e318 +--- + +**トレース** は、リクエストがアプリケーションに投げられたときに何が起こるかの全体像を教えてくれます。 +あなたのアプリケーションが、単一のデータベースを持つモノリスであろうと、洗練されたメッシュサービスであろうと、トレースは、リクエストがアプリケーションの中でたどる完全な「経路」を理解するために不可欠です。 + +[スパン](#spans)で表現される以下の3つのJSONデータで、これを探ってみましょう。 + +{{% alert title="Note" %}} + +以下のJSONの例は、特定のフォーマット、特に[OTLP/JSON](/docs/specs/otlp/#json-protobuf-encoding)を表すものではありません。OTLP/JSONは、より冗長です。 + +{{% /alert %}} + +`hello` スパンは次のとおりです。 + +```json +{ + "name": "hello", + "context": { + "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2", + "span_id": "0x051581bf3cb55c13" + }, + "parent_id": null, + "start_time": "2022-04-29T18:52:58.114201Z", + "end_time": "2022-04-29T18:52:58.114687Z", + "attributes": { + "http.route": "some_route1" + }, + "events": [ + { + "name": "Guten Tag!", + "timestamp": "2022-04-29T18:52:58.114561Z", + "attributes": { + "event_attributes": 1 + } + } + ] +} +``` + +これはルートスパンであり、オペレーション全体の始まりと終わりを示します。 +トレースを示す `trace_id` フィールドがありますが、`parent_id` がないことに注意してください。 +これがルートスパンであることを示します。 + +`hello-greetings` スパンは次のとおりです。 + +```json +{ + "name": "hello-greetings", + "context": { + "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2", + "span_id": "0x5fb397be34d26b51" + }, + "parent_id": "0x051581bf3cb55c13", + "start_time": "2022-04-29T18:52:58.114304Z", + "end_time": "2022-04-29T22:52:58.114561Z", + "attributes": { + "http.route": "some_route2" + }, + "events": [ + { + "name": "hey there!", + "timestamp": "2022-04-29T18:52:58.114561Z", + "attributes": { + "event_attributes": 1 + } + }, + { + "name": "bye now!", + "timestamp": "2022-04-29T18:52:58.114585Z", + "attributes": { + "event_attributes": 1 + } + } + ] +} +``` + +このスパンは、挨拶(`greetings`)のような特定のタスクをカプセル化していて、その親は `hello` スパンです。 +このスパンはルートスパンと同じ `trace_id` を共有していて、同じトレースの一部であることを示しています。 +さらに、 `hello` スパンの `span_id` と一致する `parent_id` を持っています。 + +`hello-salutations` スパンは次のとおりです。 + +```json +{ + "name": "hello-salutations", + "context": { + "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2", + "span_id": "0x93564f51e1abe1c2" + }, + "parent_id": "0x051581bf3cb55c13", + "start_time": "2022-04-29T18:52:58.114492Z", + "end_time": "2022-04-29T18:52:58.114631Z", + "attributes": { + "http.route": "some_route3" + }, + "events": [ + { + "name": "hey there!", + "timestamp": "2022-04-29T18:52:58.114561Z", + "attributes": { + "event_attributes": 1 + } + } + ] +} +``` + +このスパンはこのトレースにおける3つ目の操作を表し、前のスパンと同様に`hello`スパンの子です。 +また、`hello-greetings`スパンの兄弟でもあります。 + +これらの3つのJSONブロックはすべて同じ `trace_id` を共有していて、`parent_id` フィールドは階層を表しています。 +これは1つのトレースになります! + +もうひとつ、各スパンが構造化されたログのように見えることにお気づきでしょう。 +それはその通りだからです!トレースについて考える一つの方法は、トレースはコンテキスト、相関関係、階層構造などを持つ構造化されたログの集まりであるということです。 +しかし、これらの「構造化されたログ」は、異なるプロセス、サービス、VM、データセンターなどから来る可能性があります。 +これにより、トレースはあらゆるシステムのエンドツーエンドのビューを表現できます。 + +OpenTelemetryでのトレースがどのように機能するかを理解するために、コードの計装の一翼を担う一連のコンポーネントを見てみましょう。 + +## トレーサープロバイダー {#tracer-provider} + +トレーサープロバイダー(`TracerProvider` と呼ばれることもあります)は `Tracer` のファクトリーです。 +ほとんどのアプリケーションでは、トレーサープロバイダーは一度だけ初期化され、そのライフサイクルはアプリケーションのライフサイクルと一致します。 +トレーサープロバイダーの初期化には、リソースとエクスポーターの初期化も含まれます。 +これは通常、OpenTelemetry によるトレースの最初のステップです。 +いくつかの言語SDKでは、グローバルなトレーサープロバイダーがすでに初期化されています。 + +## トレーサー {#tracer} + +トレーサーは、サービス内のリクエストなど、与えられた操作で何が起こっているかについての詳細な情報を含むスパンを作成します。 +トレーサーはトレーサープロバイダーから作成されます。 + +## トレースエクスポーター {#trace-exporters} + +トレースエクスポーターはトレースをコンシューマーに送信します。 +このコンシューマーは、デバッグや開発時間用の標準出力、OpenTelemetryコレクター、あるいは任意のオープンソースやベンダーのバックエンドです。 + +## コンテキスト伝搬 {#context-propagation} + +コンテキスト伝搬(プロパゲーション)は、分散トレースを可能にする中心となる概念です。 +コンテキスト伝搬を使用すると、スパンがどこで生成されたかに関係なく、スパンを相互に関連付け、トレースとして組み立てられます。 +このトピックについては、[コンテキスト伝搬](/docs/concepts/context-propagation)の概要を参照してください。 + +## スパン {#spans} + +**スパン** は、作業や操作の単位を表します。 +スパンはトレースの構成要素です。 +OpenTelemetryでは、以下の情報を含みます。 + +- 名前 +- 親のスパンID(ルートスパンなら空) +- 開始と終了のタイムスタンプ +- [スパンコンテキスト](#span-context) +- [属性](#attributes) +- [スパンイベント](#span-events) +- [スパンリンク](#span-links) +- [スパンステータス](#span-status) + +次はスパンの例です。(訳注:JSON形式で表現しているだけで、必ずしもJSONではありません) + +```json +{ + "name": "/v1/sys/health", + "context": { + "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d", + "span_id": "086e83747d0e381e" + }, + "parent_id": "", + "start_time": "2021-10-22 16:04:01.209458162 +0000 UTC", + "end_time": "2021-10-22 16:04:01.209514132 +0000 UTC", + "status_code": "STATUS_CODE_OK", + "status_message": "", + "attributes": { + "net.transport": "IP.TCP", + "net.peer.ip": "172.17.0.1", + "net.peer.port": "51820", + "net.host.ip": "10.177.2.152", + "net.host.port": "26040", + "http.method": "GET", + "http.target": "/v1/sys/health", + "http.server_name": "mortar-gateway", + "http.route": "/v1/sys/health", + "http.user_agent": "Consul Health Check", + "http.scheme": "http", + "http.host": "10.177.2.152:26040", + "http.flavor": "1.1" + }, + "events": [ + { + "name": "", + "message": "OK", + "timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC" + } + ] +} +``` + +スパンは、親スパンIDの存在によって暗示されるように、入れ子にできます。 +これによって、スパンはアプリケーションで行われる作業をより正確に把握できます。 + +### スパンコンテキスト {#span-context} + +スパンコンテキストは、各スパンの不変オブジェクトであり、以下を含みます。 + +- スパンが属するトレースを表すトレースID +- スパンのスパンID +- トレースフラグ。これはトレースに関する情報を含むバイナリエンコーディングです。 +- ベンダ固有のトレース情報を保持するキーと値のペアのリスト + +スパンコンテキストは、[分散コンテキスト](#context-propagation)や[バゲッジ](/docs/concepts/signals/baggage)と共にシリアライズされ、伝搬されるスパンの一部です。 + +スパンコンテキストにはトレースIDが含まれているため、[スパンリンク](#span-links)を作成する際に使用されます。 + +### 属性 {#attributes} + +属性(アトリビュート)はキーと値のペアで、スパンに注釈を付けるためのメタデータを含んでいます。このメタデータは追跡している操作に関する情報を伝えるためのものです。 + +たとえば、eコマースシステムでユーザーのショッピングカートに商品を追加する操作をスパンが追跡する場合、ユーザーのID、カートに追加する商品のID、カートIDを捕捉できます。 + +スパンには、スパン作成中または作成後に属性を追加できます。 +SDKでのサンプリングで属性を利用できるようにするには、スパン作成時に属性を追加することをおすすめします。 +スパン作成後に値を追加する必要がある場合は、その値でスパンを更新してください。 + +属性には、各言語SDKが実装する以下のルールがあります。 + +- キーは非NULL文字列値でなければならない +- 値は、非NULL文字列、ブール値、浮動小数点値、整数、またはこれらの値の配列でなければならない + +さらに、[セマンティック属性](/docs/specs/semconv/general/trace/)があり、これは一般的な操作に通常存在するメタデータのための既知の命名規則です。 +システム間で共通の種類のメタデータが標準化されるように、可能な限りセマンティック属性の命名を使用することは有用です。 + +### スパンイベント {#span-events} + +スパンイベントは、スパン上の構造化ログメッセージ(または注釈)と考えられます。通常、スパンの期間中、意味のある特異な時点を示すために使われます。 + +たとえば、ウェブブラウザでの2つのシナリオを考えてみましょう。 + +1. ページ読み込みの追跡 +2. ページがインタラクティブになるタイミングを示す + +スパンは、開始と終了がある操作なので、最初のシナリオに最も適しています。 + +スパンイベントは、意味のある特定の時点を表すため、2つ目のシナリオを追跡するのに最も適しています。 + +#### スパンイベントとスパン属性の使い分け + +スパンイベントにも属性が含まれるため、属性のかわりにいつイベントを使用するかという質問には、必ずしも明白な答えがあるとは限りません。 +決定するための参考として、特定のタイムスタンプに意味があるかどうかを考えてみてください。 + +たとえば、スパンで操作を追跡していて、操作が完了した時、操作からのデータをテレメトリーに追加したいと思うかもしれません。 + +- 操作が完了したタイムスタンプに意味がある場合、または関連性がある場合は、データをスパンイベントに添付する。 +- タイムスタンプに意味がない場合は、スパン属性としてデータを添付する。 + +### スパンリンク {#span-links} + +リンクは、あるスパンと別の1つ以上のスパンを関連付け、因果関係を示唆するために存在します。 +たとえば、ある操作がトレースによって追跡される分散システムがあるとしましょう。 + +これらの操作のいくつかに対して、追加の操作がキューに入れられ実行されますが、その実行は非同期です。 +この後続の操作もトレースで追跡できます。 + +後続の操作のトレースを最初のトレースに関連付けたいと思っても、後続の操作がいつ始まるかは予測できません。 +この2つのトレースを関連付ける必要があるので、スパンリンクを使用します。 + +最初のトレースの最後のスパンを、2番目のトレースの最初のスパンにリンクできます。 +これで、これらのスパンは互いに因果関係があることになります。 + +リンクは必須ではありませんが、トレーススパン同士を関連付ける良い方法として役立ちます。 + +### スパンステータス {#span-status} + +各スパンにはステータスがあります。可能な値は以下の3つです。 + +- `Unset` +- `Error` +- `Ok` + +デフォルト値は `Unset` です。 +スパンのステータスが `Unset` である場合は、追跡した操作がエラーなしで正常に完了したということです。 + +スパンのステータスが `Error` である場合、そのスパンが追跡する操作で何らかのエラーが発生したことを意味します。 +たとえば、リクエストを処理するサーバーでHTTP 500エラーが発生した場合などです。 + +スパンのステータスが `Ok` である場合、そのスパンはアプリケーションの開発者によって明示的にエラーなしとマークされたことを意味します。 +これは直感的ではありませんが、スパンがエラーなく完了したことが分かっている場合、スパンのステータスを `Ok` とする必要はありません。 +これは `Unset` でカバーされるからです。 +`Ok`は、ユーザーによって明示的に設定されたスパンのステータスの明確な「最終決定」を表すものです。 +これは、開発者がスパンの解釈を「成功した」以外のものにはしないことを望む場合に役立ちます。 + +もう一度確認します。 +`Unset` はエラーなしで完了したスパンを表します。 +`Ok` は、開発者が明示的にスパンを成功とマークした場合を表します。 +ほとんどの場合、スパンを明示的に `Ok` とマークする必要はありません。 + +### スパンの種類(SpanKind) {#span-kind} + +スパンが作成されると、`Client(クライアント)`、 `Server(サーバー)`、 `Internal(内部)`、 `Producer(プロデューサー)`、 `Consumer(コンシューマー)` のいずれかとなります。 +このスパンの種類は、トレースがどのように組み立てられるべきかのヒントをトレースバックエンドに提供します。 +OpenTelemetryの仕様によると、サーバースパンの親はリモートクライアントスパンであることが多く、クライアントスパンの子は通常サーバースパンです。 +同様に、コンシューマースパンの親は、常にプロデューサであり、プロデューサースパンの子は、常にコンシューマである。提供されない場合、スパンの種類は内部的なものとみなされます。 + +SpanKindの詳細については、[SpanKind](/docs/specs/otel/trace/api/#spankind)を参照してください。 + +#### Client(クライアント) {#client} + +クライアントスパンは、発信HTTPリクエストやデータベース呼び出しのような、同期的な発信リモート呼び出しを表します。 +この文脈では、「同期」は `async/await` を指すのではなく、後の処理のためにキューに入れることが出来ない、ということを指すことに注意してください。 + +#### Server(サーバー) {#server} + +サーバースパンは、HTTPリクエストやリモートプロシージャコールのような、 同期的に着信するリモートコールを表します。 + +#### Internal(内部) {#internal} + +内部スパンは、プロセス境界を越えない操作を表します。 +関数呼び出しやNode.jsのExpressミドルウェアの計装などで、内部スパンを使用することがあります。 + +#### Producer(プロデューサー) {#producer} + +プロデューサースパンは、後で非同期に処理される可能性のあるジョブの作成を表します。 +それは、ジョブキューに挿入されるようなリモートジョブかもしれないし、イベントリスナーによって処理されるローカルジョブかもしれません。 + +#### Consumer(コンシューマー) {#consumer} + +コンシューマースパンは、プロデューサーが作成したジョブの処理を表し、プロデューサースパンがすでに終了したずっと後に開始されることがあります。 + +## 仕様 {#specification} + +詳細は[トレース仕様](/docs/specs/otel/overview/#tracing-signal)を参照してください。