# リファレンスアプリケーションの仕様

> このドキュメントは、Getting Started ガイド全体で使用されるリファレンスアプリケーションの仕様を記載しています

---

Site [llms.txt](/ja/llms.txt)

---

リファレンスアプリケーションの目的は、OpenTelemetry SDK が存在するすべての言語で実装できる、標準化されたサンプルアプリケーションを持つことです。

## 一般的な要件 {#general-requirements}

- リファレンスアプリの実装は、OpenTelemetry の API と SDK を実装する言語 SIG が所有します。
  これにより、アプリケーションがその言語のエコシステムのベストプラクティスに従い、アプリケーションの計装方法のブループリントを提供できます。
- アプリケーションには、未計装バージョンと計装済みバージョンの両方が必要です。
  これは、opentelemetry.io の「Getting Started」ガイドで、OpenTelemetry を使用していないアプリから完全に計装されたアプリへ移行する手順を示すために使用されます。
- アプリケーションの両バージョンがビルドおよび実行可能であることを検証する、言語固有の CI アクションが必要です。
- アプリケーションはコマンドラインインターフェイスから実行可能でなければなりません。
- コンテナ化された環境でアプリケーションを実行するための Dockerfile が必要です。
- アプリケーションは単独で実行できなければなりません。
  つまり、それを格納するリポジトリの他のコンテンツにハード依存を持つことはできません。
  これにより、ユーザーは依存関係の管理を解きほぐすことなく、コードを自分のプロジェクトにコピーできます。

## サービス要件 {#service-requirements}

- アプリケーションはデフォルトでポート 8080 で HTTP リクエストを待ち受けなければなりません。
  ポートは環境変数 APPLICATION_PORT で設定可能にする必要があります。
- HTTP リクエストの処理には、計装ライブラリが利用可能なライブラリを使用する必要があります。
  アプリケーションは `GET`（およびオプションで `POST`）で `/rolldice?rolls=<n>` エンドポイントを提供し、以下の HTTP ステータスコードと JSON の結果を返さなければなりません。
  - `rolls` が設定されていないか、有効な入力（0超の正の整数）の場合：ステータスコード `200` で、`rolls` が設定されていないか 1 の場合は 1 から 6 までの単一の数値を、それ以外の場合は `rolls` の値 `n` に対応する 1 から 6 までの数値の配列を返します。
  - `rolls` が無効な入力（数値でない）に設定されている場合：ステータスコード `400` で `{"status": "error", "message": "Parameter rolls must be a positive integer"}` を返します。
  - `rolls` が `0` または負の整数に設定されている場合：ステータスコード `500` で JSON 出力なし。
    このエラー例は、OpenTelemetry を使用してエラーを特定する方法を示すために使用されます。
- `/rolldice` エンドポイントにオプションの属性 `player=name` を指定できます。
- アプリケーションは以下のログ行を出力しなければなりません。
  - ステータスコードが `<400` の各 HTTP リクエストに対する INFO レベルのメッセージ
  - ステータスコードが `400` から `499` の各 HTTP リクエストに対する WARN レベルのメッセージ（JSON の結果で送信されるメッセージを含む）
  - ステータスコードが `499` を超える各 HTTP リクエストに対する ERROR レベルのメッセージ
  - オプションの `player` 属性が設定されている場合、`player` の値とサイコロの出目を出力する DEBUG レベルのメッセージ
  - オプションの `player` 属性が設定されていない場合、静的な値 `anonymous player` とサイコロの出目を出力する DEBUG レベルのメッセージ。
    このログ行は、計装中にログブリッジを追加し、OpenTelemetry が既存のロギングフレームワークに接続する方法を示すために使用されます。
- アプリケーションのコードは2つのファイルに分割しなければなりません。
  - HTTP リクエストの処理を含む `app` ファイル
  - サイコロを振る関数の実装を含む `library` ファイル。
    これらのファイル名は、`app.js` と `roll-the-dice.js` のように、実装言語において慣用的なものにする必要があります。
    重要な点は、2つのファイルを分離することで、`library` は API にのみ依存し、すべての SDK コードは `app` コードで初期化されることを示す点です。
- `rolls` のエラーハンドリングは以下のように分割する必要があります。
  - `app` は `rolls` が定義されているか確認し、定義されていない場合は `1` に設定します。
  - `app` は `rolls` が数値かどうかだけを確認します。
    数値であれば、`library` のサイコロを振る関数を呼び出します。
    数値でなければ、`400` エラーでエラーハンドリングを行います。
  - `library` は `rolls` が正の数かどうかを確認します。
    正の数でなければ、例外をスローします。
    `app` はそのエラーをキャッチし、`500` エラーを返します。
- `library` には、上記のエラーハンドリングを行う外側の関数が必要です。
  外側の関数は `rolls` の値に応じて以下の処理を行います。
  - `rolls == 1`：内側の関数を1回実行し、値を返します。
  - `rolls > 1`：内側の関数を `rolls` 回呼び出すループを実行し、結果を配列で返します。
- `library` の内側の関数は 1 から 6 までのランダムな数値を生成し、その値を返します。

## 計装要件 {#instrumentation-requirements}

- 可能であれば、OpenTelemetry SDK の初期化は別ファイルに含め、`app` ファイル内でインポートする必要があります。
  それ以外の場合は、`app` ファイルの一部とします。
- `process`、`container`、`os` など、一般的なリソース検出器を初期化時にロードする必要があります。
- 「lib」ファイルは OpenTelemetry API にのみ依存しなければなりません。
- `service.*` 属性は環境変数（`OTEL_SERVICE_NAME`、`OTEL_RESOURCE_ATTRIBUTES`）で追加する必要があります。
- その他の `resource detectors` は SDK の初期化に追加する必要があります。
- テレメトリーのエクスポートには、`stdout`/`console` および `otlp` のエクスポーターを使用する必要があります。
- OpenTelemetry コンポーネントの診断ログを有効にするオプションが必要であり、理想的には `OTEL_LOG_LEVEL` などを介して実装されるのが望ましいです。
- 使用する HTTP ライブラリに対する計装ライブラリを追加する方法が必要です。
  この計装ライブラリは HTTP の安定したセマンティック規約を使用する必要があります。
  ほとんどのシグナルをカバーするライブラリが望ましく、理想的にはトレースとメトリクスの両方に対応しているものを選びます。
- 計装ライブラリが利用できない場合にのみ、`app` の `/rolldice` エンドポイントを処理する関数に対して、ユーザーがスパンとメトリクスを追加して手動で計装します。
- 使用するロギング機構に対するログブリッジを用意し、すべてのログが自動的に収集およびエクスポートされるようにする必要があります。
- `library` の外側の関数にスパンを作成する必要があります。
  このスパンは関数の所要時間を追跡します。
  例外がスローされた場合はそれを記録します。
  `rolls` の値や `code.*` などの属性をスパンに追加します。
- `library` の内側の関数にスパンを作成する必要があります。
  このスパンは関数の所要時間を追跡します。
  生成したランダムな数値を属性としてスパンに追加します。
- `library` ファイルでは以下のメトリクスを作成する必要があります。
  - 外側の関数の呼び出し回数のカウンター
  - 結果（1-6）の分布のヒストグラム
  - `rolls` の最終値のゲージ