Microsoft Azure Cosmos DB 客户端操作的语义约定

状态: 开发中

Microsoft Cosmos DB 的语义约定扩展并覆盖了 Microsoft Cosmos DB 的 数据库语义约定。

Span

状态:

Cosmos DB 仪器包含代表逻辑数据库调用的调用级跨度，并遵循通用的 数据库客户端跨度的语义约定。

根据连接模式（网关或直接），还可能创建代表网络调用的附加跨度。本文档中描述的语义约定仅适用于调用级跨度。

db.system.name 必须设置为 "azure.cosmosdb"，并且应在 **创建跨度时** 提供。

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

**Span 类型**应为 CLIENT。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
db.operation.name		必需	字符串	正在执行的操作或命令的名称。[1]	create_item；query_items；read_item
azure.cosmosdb.connection.mode		有条件地必需 [2]	字符串	Cosmos 客户端连接模式。	gateway; direct
azure.cosmosdb.consistency.level		有条件必需 如果可用。	字符串	帐户或请求 一致性级别。	Eventual; ConsistentPrefix; BoundedStaleness; Strong; Session
azure.cosmosdb.operation.contacted_regions		有条件必需 如果可用。	string[]	在操作期间联系的区域列表，按联系顺序排列。如果列出了多个区域，则表示该操作已在多个区域执行，即跨区域调用。[3]	["North Central US", "Australia East", "Australia Southeast"]
azure.cosmosdb.operation.request_charge		如果可用，则条件必需	double	操作消耗的请求单元数。	46.18; 1.0
azure.cosmosdb.response.sub_status_code		当收到响应并包含子代码时，**有条件必需**。	int	Cosmos DB 子状态码。	1000; 1002
db.collection.name		如果可用，**有条件必需**。	字符串	Cosmos DB 容器名称。[4]	public.users; customers
db.namespace		有条件必需 如果可用。	字符串	数据库的名称，在服务器地址和端口内完全限定。	customers; test.users
db.response.returned_rows		如果收到响应并返回任何行，则**有条件必需**。	int	Cosmos DB 结果集中的行计数。	10; 20
db.response.status_code		如果收到响应，则**有条件必需**。	字符串	Cosmos DB 状态码。[5]	200; 201
error.type		有条件必需 仅在操作失败时。	字符串	描述操作结束时的一类错误。[6]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
server.port		如果不是默认值 (443)，则**有条件必需**。	int	服务器端口号。[7]	80; 8080; 443
azure.client.id		推荐	字符串	客户端实例的唯一标识符。	3ba4827d-4422-483f-b59f-85b74211c11d；storage-client-1
azure.cosmosdb.request.body.size		推荐	int	请求的有效负载大小（以字节为单位）。
azure.resource_provider.namespace		推荐	字符串	客户端识别的Azure 资源提供程序命名空间。[8]	Microsoft.DocumentDB
db.operation.batch.size		推荐	int	批处理操作中包含的查询数。[9]	2; 3; 4
db.query.text		推荐	字符串	正在执行的数据库查询。[10]	SELECT * FROM wuser_table where username = ?; SET mykey ?
db.stored_procedure.name		推荐 [11]	字符串	数据库中的存储过程名称。[12]	GetCustomer
server.address		推荐	字符串	数据库主机名。[13]	example.com；10.1.2.80；/tmp/my.sock
user_agent.original		推荐	字符串	Cosmos DB SDK 生成的完整用户代理字符串。[14]	cosmos-netstandard-sdk/3.23.0|3.23.1|1|X64|Linux 5.4.0-1098-azure 104 18|.NET Core 3.1.32|S|
db.query.parameter.<key>		选择加入	字符串	数据库查询参数，其中 <key> 是参数名称，属性值是参数值的字符串表示形式。[15]	someval; 55

[1] db.operation.name：db.operation.name 具有以下常用值。如果其中一个适用，则必须使用相应的值。

批处理操作

• execute_batch

批量操作

• 在报告用于executeBulkOperations 等方法的跨度时，应使用 execute_bulk，它代表对多个操作的批量执行。
• 在描述批量中单个操作的跨度（如果已报告）时，应使用 bulk_{operation name}（例如 bulk_create_item、bulk_upsert_item 等）。当仪器为每个操作创建跨度，但操作被缓冲然后批量执行时，应使用此模式。例如，当 Microsoft.Azure.Cosmos 客户端的 Microsoft.Azure.Cosmos.CosmosClientOptions.AllowBulkExecution 属性配置为 true 时，会应用此规则。

更改提要操作

• query_change_feed

冲突操作

• delete_conflict
• query_conflicts
• read_all_conflicts
• read_conflict

容器操作

• create_container
• create_container_if_not_exists
• delete_container
• query_containers
• read_all_containers
• read_container
• read_container_throughput
• replace_container
• replace_container_throughput

数据库操作

• create_database
• create_database_if_not_exists
• delete_database
• query_databases
• read_all_databases
• read_database
• read_database_throughput
• replace_database_throughput

加密密钥操作

• create_client_encryption_key
• query_client_encryption_keys
• read_all_client_encryption_keys
• read_client_encryption_key
• replace_client_encryption_key

项操作

• create_item
• delete_all_items_by_partition_key
• delete_item
• patch_item
• query_items
• read_all_items
• read_all_items_of_logical_partition
• read_many_items
• read_item
• replace_item
• upsert_item

权限操作

• create_permission
• delete_permission
• query_permissions
• read_all_permissions
• read_permission
• replace_permission
• upsert_permission

存储过程操作

• create_stored_procedure
• delete_stored_procedure
• execute_stored_procedure
• query_stored_procedures
• read_all_stored_procedures
• read_stored_procedure
• replace_stored_procedure

触发器操作

• create_trigger
• delete_trigger
• query_triggers
• read_all_triggers
• read_trigger
• replace_trigger

用户操作

• create_user
• delete_user
• query_users
• read_all_users
• read_user
• replace_user
• upsert_user

用户定义函数操作

• create_user_defined_function
• delete_user_defined_function
• query_user_defined_functions
• read_all_user_defined_functions
• read_user_defined_function

如果以上都不适用，则建议使用 snake_case 格式的语言无关的客户端方法名称表示。引入新操作时，仪器应记录其他值。

[2] azure.cosmosdb.connection.mode： 如果不是 gateway（默认值假定为 gateway）。

[3] azure.cosmosdb.operation.contacted_regions： 区域名称的格式与 Azure 位置 API 中的 displayName 匹配。

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

[5] db.response.status_code： 4xx 和 5xx 范围内的响应代码应被视为错误。

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

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

[8] azure.resource_provider.namespace： 当填充 azure.resource_provider.namespace 属性时，对于 Cosmos DB 客户端执行的所有操作，它必须设置为 Microsoft.DocumentDB。

[9] db.operation.batch.size： 操作仅在包含两个或更多操作时才被视为批处理，因此 db.operation.batch.size 永远不应为 1。

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

[11] db.stored_procedure.name： 如果操作应用于特定的存储过程。

[12] db.stored_procedure.name： 建议捕获应用程序提供的原始值，而无需尝试进行任何大小写规范化。

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

[13] server.address： 当从客户端观察并与中间件通信时，server.address 应表示任何中间件（例如代理）之后的服务器地址，如果可用。

[14] user_agent.original： 用户代理值由 SDK 生成，它是组合而成：
sdk_version：SDK 的当前版本。例如，“cosmos-netstandard-sdk/3.23.0”
direct_pkg_version：Cosmos DB SDK 使用的 Direct 包版本。例如，“3.23.1”
number_of_client_instances：应用程序创建的 cosmos 客户端实例的数量。例如，“1”
type_of_machine_architecture：机器体系结构。例如，“X64”
operating_system：操作系统。例如，“Linux 5.4.0-1098-azure 104 18”
runtime_framework：运行时框架。例如，“.NET Core 3.1.32”
failover_information：用于确定是否启用了区域故障转移的生成密钥。格式 Reg-{D (禁用发现)}-S(应用程序区域)|L(首选区域列表)|N(无，用户未配置)。默认值为“NS”。

[15] 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
• server.address
• server.port

azure.cosmosdb.connection.mode 具有以下常用值。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
direct	直接连接。
gateway	网关 (HTTP) 连接。

azure.cosmosdb.consistency.level 具有以下常用值。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
BoundedStaleness	有界陈旧性
ConsistentPrefix	一致性前缀
Eventual	Eventual
Session	Session
Strong	Strong

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

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

示例

指标

以下指标提供了对 Azure Cosmos DB 客户端操作性能和行为的洞察。

指标：db.client.operation.duration

此指标是必需的。

它捕获 Azure Cosmos DB 操作所花费的总时间。此指标遵循常见的 db.client.operation.duration 定义。

有关维度，请参阅 azure.cosmosdb.client.operation.request_charge 指标。

指标：db.client.response.returned_rows

此指标是必需的。

它捕获 Azure Cosmos DB 的查询或提要操作返回的项目数。它有助于识别可能导致高延迟、内存/CPU 使用率增加或网络调用失败的响应大小。此指标遵循常见的 db.client.response.returned_rows 定义。

有关维度，请参阅 azure.cosmosdb.client.operation.request_charge 指标。

指标：azure.cosmosdb.client.operation.request_charge

此指标是必需的。

它捕获 Azure Cosmos DB 中每个操作消耗的请求单位。由于请求单位是 Azure Cosmos DB 数据库中的一种吞吐量控制形式，因此监控其使用情况对于避免节流至关重要。

此指标应使用 [ 1, 5, 10, 25, 50, 100, 250, 500, 1000] 的 ExplicitBucketBoundaries 指定。

解释桶配置

1. 1、5、10：低使用级别。这些较小的存储桶允许精确跟踪消耗少量请求单位的操作。这对于轻量级操作（如基本读取请求或小型查询）至关重要，这些操作应优化资源利用率。监控这些低使用级别有助于确保应用程序不会无意中消耗比必要更多的资源。
2. 25、50：中等使用级别。这些范围捕获更中等的操作，这在许多应用程序中很常见。例如，返回合理数量数据或执行标准 CRUD 操作的查询可能在此限制范围内。识别这些存储桶中的使用模式有助于检测常规操作中的效率问题。
3. 100、250：高使用级别。这些边界表示可能需要大量资源的操作，例如复杂查询或大型事务。监控这些范围内的 RU 有助于识别性能瓶颈或可能导致节流的昂贵查询。
4. 500、1000：非常高使用级别。这些存储桶捕获消耗大量请求单位的操作，这可能表示潜在的昂贵查询或批量处理。了解此类高 RU 使用频率和模式对于优化性能和确保应用程序保持在预配的吞吐量限制内至关重要。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
azure.cosmosdb.client.operation.request_charge	Histogram	{request_unit}	操作消耗的请求单位。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
db.operation.name		必需	字符串	正在执行的操作或命令的名称。[1]	findAndModify; HMSET; SELECT
azure.cosmosdb.consistency.level		有条件必需 如果可用。	字符串	帐户或请求 一致性级别。	Eventual; ConsistentPrefix; BoundedStaleness; Strong; Session
azure.cosmosdb.response.sub_status_code		当收到响应并包含子代码时，**有条件必需**。	int	Cosmos DB 子状态码。	1000; 1002
db.collection.name		有条件必需 如果可用。	字符串	Cosmos DB 容器名称。[2]	public.users; customers
db.namespace		有条件必需 如果可用。	字符串	数据库的名称，在服务器地址和端口内完全限定。	customers; test.users
db.response.status_code		有条件地必需 [3]	字符串	数据库响应状态码。[4]	102; ORA-17002; 08P01; 404
error.type		有条件必需 仅在操作失败时。	字符串	描述操作结束时的一类错误。[5]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
server.port		有条件地必需 [6]	int	服务器端口号。[7]	80; 8080; 443
azure.cosmosdb.operation.contacted_regions		推荐 如果可用	string[]	在操作期间联系的区域列表，按联系顺序排列。如果列出了多个区域，则表示该操作已在多个区域执行，即跨区域调用。[8]	["North Central US", "Australia East", "Australia Southeast"]
server.address		推荐	字符串	数据库主机名。[9]	example.com；10.1.2.80；/tmp/my.sock

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

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

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

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

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

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

[4] db.response.status_code： 数据库返回的状态码。通常它表示错误代码，但也可能表示部分成功、警告或区分各种成功结果。特定数据库系统的语义约定应记录 db.response.status_code 在该系统上下文中的含义。

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

[6] server.port： 如果使用的端口不是此 DBMS 的默认端口，并且 server.address 已设置。

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

[8] azure.cosmosdb.operation.contacted_regions： 区域名称的格式与 Azure 位置 API 中的 displayName 匹配。

[9] server.address： 当从客户端观察并与中间件通信时，server.address 应表示任何中间件（例如代理）之后的服务器地址，如果可用。

azure.cosmosdb.consistency.level 具有以下常用值。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
BoundedStaleness	有界陈旧性
ConsistentPrefix	一致性前缀
Eventual	Eventual
Session	Session
Strong	Strong

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

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

指标：azure.cosmosdb.client.active_instance.count

此指标是必需的。

它捕获任何给定时间点的活动实例数。最佳实践规定，每个 Azure Cosmos DB 帐户理想情况下只有一个 SDK 客户端实例。在同一进程中为同一帐户拥有多个 SDK 客户端实例可能会导致 CPU 或内存相关问题。

名称	Instrument Type	Unit (UCUM)	描述	Stability	实体关联
azure.cosmosdb.client.active_instance.count	UpDownCounter	{instance}	活动客户端实例数。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
server.port		有条件地必需 [1]	int	服务器端口号。[2]	80; 8080; 443
server.address		推荐	字符串	数据库主机名。[3]	example.com；10.1.2.80；/tmp/my.sock

[1] server.port： 如果使用的端口不是此 DBMS 的默认端口，并且 server.address 已设置。

[2] server.port： 从客户端观察，并且在通过中介通信时，server.port 应表示任何中介（例如代理）后面的服务器端口，如果可用的话。

[3] server.address：从客户端观察时，并且在通过中间设备进行通信时，server.address 应表示中间设备（例如代理）后面的服务器地址，如果可用。