Cassandra 客户端操作的语义约定

状态: 开发中

Cassandra 的语义约定扩展并覆盖了 Cassandra 的 数据库语义约定。

Span

状态:

表示对 Cassandra 数据库调用的 span 遵循通用的 数据库客户端 span 语义约定。

db.system.name 必须设置为 "cassandra"，并且应在**创建 span 时**提供。

span 名称应遵循通用的 数据库 span 名称约定。

**Span 类型**应为 CLIENT。

**Span 状态**应遵循 记录错误文档。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
db.collection.name		有条件地必需 [1]	字符串	操作正在进行的 Cassandra 表的名称。[2]	public.users; customers
db.namespace		有条件必需 如果可用。	字符串	与会话关联的 keyspace。[3]	mykeyspace
db.operation.name		有条件地必需 [4]	字符串	正在执行的操作或命令的名称。[5]	findAndModify; HMSET; SELECT
db.response.status_code		有条件地必需 [6]	字符串	表示为字符串的 Cassandra 协议错误代码。[7]	102; 40020
error.type		有条件必需 仅在操作失败时。	字符串	描述操作结束时的一类错误。[8]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
server.port		有条件地必需 [9]	int	服务器端口号。[10]	80; 8080; 443
cassandra.consistency.level		推荐	字符串	查询的一致性级别。基于 CQL 中的一致性值。	all; each_quorum; quorum
cassandra.coordinator.dc		推荐	字符串	查询协调节点的所在数据中心。	us-west-2
cassandra.coordinator.id		推荐	字符串	查询协调节点的 ID。	be13faa2-8574-4d71-926d-27f16cf8a7af
cassandra.page.size		推荐	int	用于分页的 fetch size，即一次返回多少行。	5000
cassandra.query.idempotent		推荐	布尔值	查询是否是幂等的。
cassandra.speculative_execution.count		推荐	int	查询被推测执行的次数。如果查询未被推测执行，则不设置或设置为 0。	0; 2
db.operation.batch.size		推荐	int	批量操作中包含的查询数量。[11]	2; 3; 4
db.query.summary		推荐 [12]	字符串	数据库查询的低基数摘要。[13]	SELECT wuser_table; INSERT shipping_details SELECT orders; get user by id
db.query.text		推荐 [14]	字符串	正在执行的数据库查询。[15]	SELECT * FROM wuser_table where username = ?; SET mykey ?
db.response.returned_rows		推荐	int	操作返回的行数。	10; 30; 1000
network.peer.address		推荐	字符串	执行操作的数据库节点的对等地址。[16]	10.1.2.80；/tmp/my.sock
network.peer.port		推荐，当且仅当设置了 network.peer.address 时。	int	网络连接的对等端口号。	65123
server.address		推荐	字符串	数据库主机的名称。[17]	example.com；10.1.2.80；/tmp/my.sock
db.query.parameter.<key>		选择加入	字符串	数据库查询参数，其中 <key> 是参数名称，属性值是参数值的字符串表示。[18]	someval; 55

[1] db.collection.name: 如果容易获取，并且数据库调用是对单个集合执行的。

[2] db.collection.name: 建议捕获应用程序提供的原始值，而不尝试进行任何大小写规范化。

对于批量操作，如果已知各个操作具有相同的集合名称，则应使用该集合名称。

[3] db.namespace: 如果数据库系统有多个命名空间组件，应从最通用到最具体的命名空间组件进行连接，使用 | 作为组件之间的分隔符。任何缺失的组件（及其关联的分隔符）都应被省略。特定数据库系统的语义约定应记录 db.namespace 在该系统中的含义。建议捕获应用程序提供的原始值，而不尝试进行任何大小写规范化。

[4] db.operation.name: 如果容易获取，并且有一个单一的操作名称可以描述数据库调用。

[5] db.operation.name: 建议捕获应用程序提供的原始值，而不尝试进行任何大小写规范化。

当数据库系统支持包含多个操作的查询文本时，不应从 db.query.text 中提取操作名称（对于非批量操作）。

如果操作名称中可能出现空格，则应将多个连续空格规范化为单个空格。

对于批量操作，如果已知各个操作具有相同的操作名称，则应在前面加上 BATCH ，否则 db.operation.name 应为 BATCH 或其他更适用的数据库系统特定术语。

[6] db.response.status_code: 如果操作失败且状态码可用。

[7] db.response.status_code: 所有 Cassandra 协议错误代码都应被视为错误。

[8] error.type: error.type 应与数据库或客户端库返回的 db.response.status_code 匹配，或者与发生的异常的规范名称匹配。使用规范异常类型名称时，仪器应尽最大努力报告最相关的类型。例如，如果原始异常被包装在通用异常中，则应优先选择原始异常。仪器应记录 error.type 的填充方式。

[9] server.port: 如果使用的是非 DBMS 默认端口，并且设置了 server.address。

[10] server.port: 当从客户端观察到并且通过中间件通信时，server.port 应代表任何中间件（例如代理）之后的服务器端口，如果可用。

[11] db.operation.batch.size: 仅当操作包含两个或更多操作时才视为批量操作，因此 db.operation.batch.size 永远不应为 1。

[12] db.query.summary: 如果通过仪器钩子可用，或者仪器支持生成查询摘要。

[13] db.query.summary: 查询摘要描述了一类数据库查询，并可用作分组键，尤其是在分析涉及复杂查询的数据库调用的遥测数据时。

摘要可能通过仪器化钩子或其他方式提供给仪器化。如果不可用，支持查询解析的仪器化应遵循 生成查询摘要 部分来生成摘要。

[14] db.query.text: 默认不应收集非参数化查询文本，除非进行了清理操作（例如通过删除查询文本中的所有字面值）以排除敏感数据。请参阅 db.query.text 的清理。默认应收集参数化查询文本（查询参数值本身是选择加入的，请参阅 db.query.parameter.<key>）。

[15] db.query.text: 有关清理，请参阅 db.query.text 的清理。对于批量操作，如果已知单个操作具有相同的查询文本，则应使用该查询文本；否则，应使用 ; 分隔符或其他更适用的数据库系统特定分隔符连接所有单个查询文本。参数化查询文本不应被清理。尽管参数化查询文本可能包含敏感数据，但使用参数化查询的用户会发出一个强烈的信号，表明任何敏感数据都将作为参数值传递，并且默认捕获查询静态部分的可见性好处会超过风险。

[16] network.peer.address: 如果数据库操作涉及多个网络调用（例如重试），则应使用最后联系的节点的地址。

[17] server.address: 当从客户端观察时，并且通过中间人进行通信时，server.address 应表示任何中间人（例如代理）之后的服务器地址，如果可用。

[18] db.query.parameter.<key>: 如果查询参数没有名称，而是仅通过索引引用，则 <key> 应为 0 基索引。

db.query.parameter.<key> 应与 db.query.text 中存在的参数化占位符匹配。

建议捕获应用程序提供的原始值，而不尝试进行任何大小写规范化。

db.query.parameter.<key> 不应在批量操作上捕获。

示例

• 对于查询 SELECT * FROM users where username = %s 和参数 "jdoe"，属性 db.query.parameter.0 应设置为 "jdoe"。

• 对于查询 "SELECT * FROM users WHERE username = %(userName)s; 和参数 userName = "jdoe"，属性 db.query.parameter.userName 应设置为 "jdoe"。

以下属性对于做出采样决策可能很重要，并且应在跨度创建时提供（如果提供的话）

• db.collection.name
• db.namespace
• db.operation.name
• db.query.summary
• db.query.text
• server.address
• server.port

cassandra.consistency.level 具有以下已知值列表。如果其中一个适用，则必须使用相应的 值；否则，可以 使用自定义值。

值	描述	Stability
all	All
any	Any
each_quorum	Each Quorum
local_one	Local One
local_quorum	Local Quorum
local_serial	Local Serial
one	One
quorum	Quorum
serial	Serial
three	Three
two	Two

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。

指标

Cassandra 客户端仪器应根据通用的 数据库客户端指标语义约定 收集指标。

db.system.name 必须设置为 "cassandra"。