Merge branch 'open-telemetry:main' into main

svrnm · Jul 5, 2024 · 62ed4ac · 62ed4ac
2 parents 21d1d00 + a740b0a
commit 62ed4ac
Show file tree

Hide file tree

Showing 55 changed files with 749 additions and 67 deletions.
diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md
@@ -1,45 +1,83 @@
 ---
 title: Site localization
-description:
-  Guidance on creating and maintaining site page in non-English localizations.
+description: Creating and maintaining site pages in non-English localizations.
 linkTitle: Localization
 weight: 25
+cSpell:ignore: shortcodes
 ---
 
-{{% pageinfo color="warning" %}}
-
-🚧 This DRAFT page is under active development. 🚧
-
-{{% /pageinfo %}}
-
-This website uses Hugo's [multilingual framework] to support page localizations.
+The OTel website uses Hugo's [multilingual framework] to support page localizations.
 English is the default language, with US English as the default (implicit) localization.
 A growing number of other localizations are supported, as can be seen from the languages
 dropdown menu in the top nav.
 
-## Translation tips
+## Translation guidance
+
+We recommend that you follow the guidance offered in this section when
+translating pages.
+
+### Heading anchors
+
+To ensure that heading anchor targets are uniform across localizations, when
+translating headings:
+
+- Preserve the heading's explicit ID if it has one. [Heading ID syntax] is
+  written after the heading text using syntax like `{ #some-id }`.
+- Otherwise, explicitly declare a heading ID corresponding to the autogenerated
+  ID of the original English heading.
+
+{{% alert title="Note" %}}
+
+We leave it to the discretion of localization authors to decide if they add an
+explicit heading ID to all headings of translated pages, or whether this is only
+done for known intra-site heading targets, as reported by the link checker. The
+former option is more uniform and more work. It better supports having
+site-external targets into localization pages and avoids having to revisit
+previously translated pages as new heading targets are used.
 
-When you translate page content, follow this guidance:
+{{% /alert %}}
+
+[Heading ID syntax]:
+  https://github.com/yuin/goldmark/blob/master/README.md#headings
+
+### Links
 
-- To ensure that heading anchor targets are uniform across localizations, when
-  translating headings:
-  - If the heading has an explicit ID (which is of the form `{ #some-id }` and
-    comes after the heading text), then preserve the given ID
-  - Otherwise, include a heading ID corresponding to the original English
-    heading text.
-- For link references that are local paths, preserve the path _as is_.
+For link references to local paths (as opposed to external links), preserve the
+path _as is_. This holds true for links to website pages or section-local
+resources such as images.
 
 {{% alert title="Note" %}}
 
-This repository has a custom render-link hook that Hugo uses to convert
-**absolute link paths to documentation pages** that are of the form
-`/docs/some-page`, to be locale specific, by prefixing the path with page
+The OTel website repository has a custom render-link hook that Hugo uses to
+convert **absolute link paths to documentation pages**. Links of the form
+`/docs/some-page` are made locale specific by prefixing the path with the page
 language code when rendering the link. For example, the previous sample path
 would become `/ja/docs/some-page` when rendered from a Japanese page.
 
 {{% /alert %}}
 
-## Keeping track of localized page drift {#track-changes}
+### Images
+
+Hugo is smart in the way that it renders page images that are shared across site
+localizations. That is, in the generated site folder, Hugo will output a
+_single_ image file that is then shared across localizations.
+
+So as a general rule, _do not_ make copies of image files in your localization
+unless you actually change the image.
+
+### Shortcodes
+
+Some of the base shortcodes contain English text that you might need to localize
+-- this is particularly true of those contained in [layouts/shortcodes/docs].
+
+If you need to create a localized version of a shortcode, place it under
+`layouts/shortcodes/xx`, where `xx` is your localization's language code. From
+there, use the same relative path as the original base shortcode.
+
+[layouts/shortcodes/docs]:
+  https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs
+
+## Keeping track of localized-page drift {#track-changes}
 
 One of the main challenges of maintaining localized pages, is identifying when
 the corresponding English language pages have been updated. This section

diff --git a/content/en/docs/languages/go/getting-started.md b/content/en/docs/languages/go/getting-started.md
@@ -262,7 +262,7 @@ func newLoggerProvider() (*log.LoggerProvider, error) {
 ```
 <!-- prettier-ignore-end -->
 
-If you're only using tracing or metrics, you can omit the code the corresponding
+If you're only using tracing or metrics, you can omit the corresponding
 TracerProvider or MeterProvider initialization code.
 
 ### Instrument the HTTP server

diff --git a/content/en/ecosystem/registry/adding.md b/content/en/ecosystem/registry/adding.md
@@ -10,9 +10,17 @@ feature your project in the [registry](../)!
 To add your project, submit a [pull request][]. You'll need to create a data file
 in [data/registry][] for your project, by using the following template: [registry-entry.yml][].
 
+Make sure that your project names and descriptions follow our [marketing
+guidelines][] and are in line with the Linux Foundation’s branding and [trademark
+usage
+guidelines][].
+
 [data/registry]:
   https://github.com/open-telemetry/opentelemetry.io/tree/main/data/registry
 [pull request]:
   https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
 [registry-entry.yml]:
   https://github.com/open-telemetry/opentelemetry.io/tree/main/templates/registry-entry.yml
+[marketing guidelines]: /community/marketing-guidelines/
+[trademark usage guidelines]:
+  https://www.linuxfoundation.org/legal/trademark-usage
diff --git a/content/en/ecosystem/vendors.md b/content/en/ecosystem/vendors.md
@@ -12,6 +12,11 @@ Some organizations provide a [distribution](/ecosystem/distributions/) (of
 customized OpenTelemetry components), that provides additional capabilities or
 for improved ease of use.
 
+Open Source (OSS) refers to a vendor who has an observability product that is
+[open source](https://opensource.org/osd). The vendor may still have other
+products that are closed source, such as a SaaS offering that hosts an open
+source product for their customers.
+
 {{% ecosystem/vendor-table %}}
 
 ## Add your organization

diff --git a/content/ja/docs/concepts/signals/_index.md 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
@@ -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
@@ -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