> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/db/couchdb/


# CouchDBクライアント操作に関するセマンティック規約

**ステータス**: [Development][DocumentStatus]

[CouchDB](https://couchdb.apache.org/)に関するセマンティック規約は、[データベースに関するセマンティック規約](/works/otel-specs-ja/semconv/db/)を拡張・オーバーライドします。

## Spans

CouchDBへの呼び出しを表すスパンは、[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に従います。

`db.system.name` は `"couchdb"` に設定しなければならず（MUST）、**スパン作成時に**提供すべきです（SHOULD）。

以下の表は、CouchDBに適用可能なスパン属性の一覧です。

<!-- semconv span.db.couchdb.client -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

CouchDBへの呼び出しを表すスパンは、[データベースクライアントのスパンに関する全般的なセマンティック規約](/works/otel-specs-ja/semconv/db/database-spans/)に従います。

`db.system.name` は `"couchdb"` に設定しなければならず（MUST）、**スパン作成時に**提供すべきです（SHOULD）。

**スパン名**は、全般的な[データベースのスパン名に関する規約](/works/otel-specs-ja/semconv/db/database-spans/#name)に従うべきです（SHOULD）。

**スパン種別**は `CLIENT` にすべきです（SHOULD）。

**スパンステータス**は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`db.namespace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | サーバーアドレスとポートの範囲内で完全修飾された、データベースの名前。 | `customers`; `test.users` |
| [`db.operation.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If readily available. | string | HTTPメソッドと対象のRESTルート。 [1] | `GET /{db}/{docid}` |
| [`db.response.status_code`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [2] | string | 文字列として記録された、CouchDBによって返されたHTTPレスポンスコード。 [3] | `200`; `201`; `429` |
| [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | 操作が終了した際のエラーのクラスを記述する。 [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` |
| [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | サーバーのポート番号。 [6] | `80`; `8080`; `443` |
| [`db.operation.batch.size`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | バッチ操作に含まれるデータベース操作の数。 [7] | `2`; `3`; `4` |
| [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | データベースホストの名前。 [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |

**[1] `db.operation.name`:** **CouchDB** では、`db.operation.name` はAPIリファレンスドキュメントに従い、HTTPメソッドと対象のRESTルートに設定すべきです。たとえば、ドキュメントを取得する場合、`db.operation.name` は（プレースホルダーを具体的な値に置き換えずに、文字どおり）[`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid)に設定されます。

**[2] `db.response.status_code`:** レスポンスを受信し、かつHTTPレスポンスコードが利用可能な場合。

**[3] `db.response.status_code`:** 4xxおよび5xx範囲のHTTPレスポンスコードは、エラーとみなすべきです（SHOULD）。

**[4] `error.type`:** `error.type` は、データベースまたはクライアントライブラリによって返された `db.response.status_code`、または発生した例外の正式名称と一致すべきです（SHOULD）。
正式な例外型名を使用する場合、計装は最も関連性の高い型を報告するよう最善を尽くすべきです（SHOULD）。たとえば、元の例外が汎用的な例外にラップされている場合、元の例外を優先すべきです（SHOULD）。
計装は、`error.type` がどのように設定されるかを文書化すべきです（SHOULD）。

**[5] `server.port`:** このDBMSのデフォルトポート以外のポートを使用しており、かつ `server.address` が設定されている場合。

**[6] `server.port`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.port` は、利用可能であれば、あらゆる中間者（たとえばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[7] `db.operation.batch.size`:** 以下に説明する空のバッチリクエストを除き、バッチ操作は、単一のクライアント呼び出し、プロトコルメッセージ、またはデータベースコマンドの中で、個別の操作として明示的に送信された2つ以上のデータベース操作を含みます。

1つの操作のみを含むバッチAPIへのリクエストは、バッチ操作としてではなく、単一の操作としてモデル化すべきです（SHOULD）。

1つの操作が複数のオペランド（キー、行、ドキュメント、点、その他のデータ要素など。複数のキーを持つRedisの[`MGET`](https://redis.io/docs/latest/commands/mget/)を含む）を受け付けるという理由だけでは、データベース呼び出しはバッチ操作にはなりません。

同じパラメータ化された操作をパラメータセットとともに実行するバッチAPIでは、各パラメータセットが、リクエストがバッチ操作であるかどうかを判定するための1つのデータベース操作を表します。パラメータセットが1つだけのリクエストは、バッチ操作としてではなく、単一の操作としてモデル化すべきです（SHOULD）。

`db.operation.batch.size` は、バッチ内の操作数に設定すべきです（SHOULD）。非バッチ操作に対しては設定すべきではありません（SHOULD NOT）。

操作を含まないバッチ操作を実行するリクエストもバッチ操作として扱うべきであり（SHOULD）、`db.operation.batch.size` は `0` に設定すべきです（SHOULD）。

**[8] `server.address`:** クライアント側から観測され、かつ中間者を介して通信している場合、`server.address` は、利用可能であれば、あらゆる中間者の背後にあるサーバーアドレスを表すべきです（SHOULD）。

以下の属性は、サンプリングの判断を行う上で重要な場合があり、**スパン作成時に**（提供する場合は）提供すべきです（SHOULD）。

* [`db.namespace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/)
* [`db.operation.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/db/)
* [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、以下の既知の値の一覧があります。これらのいずれかが該当する場合、対応する値を使用しなければなりません（MUST）。それ以外の場合は、独自の値を使用してもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Metrics

CouchDBクライアントの計装は、全般的な[データベースクライアントのメトリクスに関するセマンティック規約](/works/otel-specs-ja/semconv/db/database-metrics/)に従ってメトリクスを収集すべきです（SHOULD）。

`db.system.name` は `"couchdb"` に設定しなければなりません（MUST）。

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status