Microsoft SQL Server 客户端操作的语义约定
状态: 稳定，除非另有说明。
Microsoft SQL Server 的语义约定扩展并覆盖了 数据库语义约定。
Span
状态:
代表 Microsoft SQL Server 调用的 Span 应遵循通用的 数据库客户端 Span 的语义约定。
db.system.name 必须设置为 "microsoft.sql_server"，并且应在 **创建 Span 时** 提供。
**Span 类型**应为 CLIENT。
**Span 状态**应遵循 记录错误文档。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
db.namespace |  | 有条件要求 如果在不产生额外网络调用的情况下可用。 | 字符串 | 通过实例名限定的连接关联的数据库。[1] | instance1|products; customers |
db.response.status_code | | 有条件要求 如果响应以警告或错误结束。 | 字符串 | Microsoft SQL Server 错误编号，表示为字符串。[2] | 102; 40020 |
error.type | | 有条件必需 仅在操作失败时。 | 字符串 | 描述操作结束的错误类别。[3] | timeout；java.net.UnknownHostException；server_certificate_invalid；500 |
server.port | | 有条件地必需 [4] | int | 服务器端口号。[5] | 80; 8080; 443 |
db.collection.name | | 推荐 [6] | 字符串 | 数据库中的集合（表、容器）的名称。[7] | public.users; customers |
db.operation.batch.size | | 推荐 | int | 批量操作中包含的查询数量。 [8] | 2; 3; 4 |
db.operation.name | | 推荐 [9] | 字符串 | 正在执行的操作或命令的名称。[10] | EXECUTE; INSERT |
db.query.summary | | 推荐 [11] | 字符串 | 数据库查询的低基数摘要。[12] | SELECT wuser_table; INSERT shipping_details SELECT orders; get user by id |
db.query.text | | 推荐 [13] | 字符串 | 正在执行的数据库查询。[14] | SELECT * FROM wuser_table where username = ?; SET mykey ? |
db.stored_procedure.name | | 推荐 [15] | 字符串 | 数据库中的存储过程的名称。[16] | GetCustomer |
server.address | | 推荐 | 字符串 | 数据库主机的名称。[17] | example.com；10.1.2.80；/tmp/my.sock |
db.query.parameter.<key> |  | 选择加入 | 字符串 | 数据库查询参数，其中 <key> 是参数名称，属性值是参数值的字符串表示。[18] | someval; 55 |
db.response.returned_rows | | 选择加入 | int | 操作返回的行数。 | 10; 30; 1000 |
[1] db.namespace: 连接到默认实例时，db.namespace 应设置为数据库名称。连接到 命名实例 时，db.namespace 应设置为实例名和数据库名的组合，格式为 {instance_name}|{database_name}。
连接当前关联的数据库在其生命周期中可能会发生更改，例如通过执行 USE <database>。
如果仪器化无法在每次查询时捕获连接当前关联的数据库，而又不会触发执行额外的查询（例如 SELECT DB_NAME()），则建议回退并使用建立连接时提供的数据库。
检测工具应记录 db.namespace 是否反映了建立连接时提供的数据库。
建议捕获应用程序提供的原始值，而不尝试进行任何大小写规范化。
[2] db.response.status_code: Microsoft SQL Server 不报告 SQLSTATE。仪器化应使用与状态码一同返回的 错误严重性 来确定 Span 的状态。严重性为 11 或更高的响应码应被视为错误。
[3] error.type： error.type 应与数据库或客户端库返回的 db.response.status_code 或发生的异常的标准名称相匹配。当使用标准异常类型名称时，检测工具应尽最大努力报告最相关的类型。例如，如果原始异常被包装到一个通用异常中，则应优先使用原始异常。检测工具应记录 error.type 的填充方式。
[4] server.port： 如果使用的是非此 DBMS 默认端口的端口，并且 server.address 已设置。
[5] server.port: 从客户端观察并与中介通信时，server.port 应表示任何中介（例如代理）之后的服务器端口，如果可用。
[6] db.collection.name： 如果操作是通过不支持多个集合名称的高级 API 执行的。
[7] db.collection.name： 不应从 db.query.text 中提取集合名称。
[8] db.operation.batch.size：只有当操作包含两个或更多操作时，才将其视为批量操作，因此 db.operation.batch.size 绝不应为 1。
[9] db.operation.name： 如果操作是通过不支持多个操作名称的高级 API 执行的。
[10] db.operation.name： 不应从 db.query.text 中提取操作名称。
[11] db.query.summary： 如果可通过检测工具钩子获得，或者如果检测工具支持生成查询摘要。
[12] db.query.summary： 查询摘要描述了一类数据库查询，并可用作分组键，尤其是在分析涉及复杂查询的数据库调用遥测数据时。
摘要可能通过仪器化钩子或其他方式提供给仪器化。如果不可用，支持查询解析的仪器化应遵循 生成查询摘要 部分来生成摘要。
[13] db.query.text： 默认情况下不应收集非参数化查询文本，除非有排除敏感数据的清理措施，例如通过删除查询文本中存在的所有字面值。请参阅 db.query.text 的清理。默认情况下应收集参数化查询文本（查询参数值本身是选择加入的，请参阅 db.query.parameter.<key>）。
[14] db.query.text： 有关清理，请参阅 db.query.text 的清理。对于批量操作，如果已知单个操作具有相同的查询文本，则应使用该查询文本；否则，应将所有单个查询文本与分隔符 ; 或某个其他更适用的数据库系统特定分隔符连接起来。参数化查询文本不应被清理。即使参数化查询文本可能包含敏感数据，通过使用参数化查询，用户也已发出强烈信号表明任何敏感数据都将作为参数值传递，并且默认捕获查询文本静态部分的可观察性优势超过了风险。
[15] db.stored_procedure.name： 如果操作应用于特定的存储过程。
[16] db.stored_procedure.name： 建议捕获应用程序提供的值，而无需尝试进行任何大小写规范化。
对于批量操作，如果已知各个操作具有相同的存储过程名称，则应使用该存储过程名称。
[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"。
以下属性对于做出采样决策可能很重要，并且应在跨度创建时提供（如果提供的话）
error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 当检测不到自定义值时使用的回退错误值。 | |
上下文传播
状态: 开发中
SET CONTEXT_INFO
仪器化可以通过 SET CONTEXT_INFO 来传播上下文，通过在执行查询之前注入 Span 上下文的固定长度部分（trace-id、span-id、trace-flags、protocol version）。例如，使用 W3C Trace Context 时，只应注入 traceparent 的字符串表示。上下文注入默认不应启用，但仪器化可以允许用户选择开启。
由于 CONTEXT_INFO 的值长度限制为 128 字节，因此不应注入可变上下文部分（tracestate、baggage）。
传播上下文的仪器化必须在与 SQL 语句相同的物理连接上执行 SET CONTEXT_INFO（或重用其事务）。
请注意，根据其语法，SET CONTEXT_INFO 需要二进制输入：SET CONTEXT_INFO { binary_str | @binary_var }，最大尺寸为 128 字节。
示例
对于查询 SELECT * FROM songs，其中 traceparent 为 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
在与 SQL 语句相同的物理连接上运行以下命令
-- The binary conversion may be done by the application or the driver.
DECLARE @traceparent varbinary(55);
SET @traceparent = CAST('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01' AS varbinary(55));
SET CONTEXT_INFO @traceparent;
然后运行查询
SELECT * FROM songs;
指标
Microsoft SQL Server 客户端仪器化应按照通用的 数据库客户端指标的语义约定 来收集指标。
db.system.name 必须设置为 "microsoft.sql_server"。