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

ステータス: Development

HBase に関するセマンティック規約は、データベースのセマンティック規約を拡張し、上書きします。

Spans

Status:

HBaseデータベースへの呼び出しを表すスパンは、データベースクライアントのスパンに関する全般的なセマンティック規約に従います。

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

スパン名は、全般的なデータベースのスパン名に関する規約に従うべきです（SHOULD）。

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

スパンステータスは、エラーの記録の文書に従うべきです（SHOULD）。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`db.operation.name`	`Required`	string	実行されている操作またはコマンドの名前。 [1]	`findAndModify`; `HMSET`; `SELECT`
`db.collection.name`	`Conditionally Required` If applicable.	string	HBaseのテーブル名。 [2]	`mytable`; `ns:table`
`db.namespace`	`Conditionally Required` If applicable.	string	HBaseの名前空間。 [3]	`mynamespace`
`db.response.status_code`	`Conditionally Required` If response was received.	string	文字列として記録された、プロトコル固有の応答コード。 [4]	`200`; `409`; `14`
`error.type`	`Conditionally Required` If and only if the operation failed.	string	操作が終了した際のエラーのクラスを記述する。 [5]	`timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`
`server.port`	`Conditionally Required` [6]	int	サーバーのポート番号。 [7]	`80`; `8080`; `443`
`db.operation.batch.size`	`Recommended`	int	バッチ操作に含まれるデータベース操作の数。 [8]	`2`; `3`; `4`
`server.address`	`Recommended`	string	データベースホストの名前。 [9]	`example.com`; `10.1.2.80`; `/tmp/my.sock`

[1] db.operation.name: 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。

バッチ操作については、個々の操作が同じ操作名を持つことがわかっている場合、その操作名の前に BATCH を付けて使用すべきです（SHOULD）。そうでない場合、db.operation.name は BATCH にすべきです（SHOULD）。

[2] db.collection.name: 値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。テーブル名に名前空間が含まれる場合、db.collection.name は完全なテーブル名に設定すべきです（SHOULD）。

[3] db.namespace: データベースシステムが複数の名前空間コンポーネントを持つ場合、それらはコンポーネント間の区切り文字として | を使い、最も一般的なものから最も特定的なものへと連結すべきです（SHOULD）。欠落しているコンポーネント（およびそれに対応する区切り文字）は省略すべきです（SHOULD）。個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて db.namespace が何を意味するかを文書化すべきです（SHOULD）。値は、大文字小文字の正規化を試みずに、アプリケーションから提供されたとおりに取得することが推奨されます（RECOMMENDED）。

[4] db.response.status_code: データベースによって返されたステータスコード。通常はエラーコードを表しますが、部分的な成功、警告、または様々な種類の成功結果の区別を表すこともあります。個々のデータベースシステムに関するセマンティック規約は、そのシステムにおいて db.response.status_code が何を意味するかを文書化すべきです（SHOULD）。

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

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

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

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

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

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

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

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

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

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

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

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

Value	Description	Stability
`_OTHER`	計装が独自の値を定義していない場合に使用するフォールバックのエラー値。

Metrics

HBaseクライアントの計装は、全般的なデータベースクライアントのメトリクスに関するセマンティック規約に従ってメトリクスを収集すべきです（SHOULD）。

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