SQL 数据库客户端操作的语义约定
状态: 稳定，除非另有说明。
Span
状态:
SQL 数据库语义约定描述了常见的 数据库语义约定 如何应用于 SQL 数据库。
以下数据库系统（在 db.system.name 集中定义）已知使用 SQL 作为其主要查询语言。
actian.ingrescockroachdbderbyfirebirdsqlh2databasehsqldbibm.db2mariadbmicrosoft.sql_servermysqloracle.dbother_sqlpostgresqlsap.maxdbsqlitetrino
许多其他数据库系统支持 SQL，并且可以通过通用的数据库驱动程序（如 JDBC 或 ODBC）进行访问。应用于通用 SQL 驱动程序的仪器化应遵循 SQL 语义约定。
span 名称应遵循通用的 数据库 span 名称约定。
**Span 类型**应为 CLIENT。
**Span 状态**应遵循 记录错误文档。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
db.namespace |  | 有条件要求 如果在不产生额外网络调用的情况下可用。 | 字符串 | 与连接关联的数据库，在服务器地址和端口中完全限定。[1] | customers; test.users |
db.response.status_code | | 有条件要求 如果响应以警告或错误结束。 | 字符串 | 数据库响应码，记录为字符串。[2] | ORA-17027; 1052; 2201B |
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 在该系统上下文中的含义。
连接当前关联的数据库在其生命周期中可能会发生变化，例如通过执行 USE <database>。
如果检测工具在不触发额外查询（例如 SELECT DATABASE()）的情况下，无法在每次查询时捕获连接当前关联的数据库，则建议回退并使用建立连接时提供的数据库。
检测工具应记录 db.namespace 是否反映了建立连接时提供的数据库。
建议捕获应用程序提供的原始值，而不尝试进行任何大小写规范化。
[2] db.response.status_code： SQL 定义了 SQLSTATE 作为数据库返回码，一些数据库系统（如 PostgreSQL）采用此码。有关详细信息，请参阅 PostgreSQL 错误码。
MySQL、Oracle 或 MS SQL Server 等其他系统定义了特定于供应商的错误码。数据库 SQL 驱动程序通常提供对这两种属性的访问。例如，在 Java 中，SQLException 类通过 getSQLState() 和 getErrorCode() 方法报告它们。
仪器化应使用可用的最具体代码来填充 db.response.status_code。
以下是报告特定于供应商的代码（其粒度高于 SQLSTATE 或根本不报告 SQLSTATE）的数据库的非详尽列表。
这些系统应将 db.response.status_code 设置为已知的特定于供应商的错误代码。如果只有 SQLSTATE 可用，则应使用它。
当有多个错误代码可用且特异性不明确时，仪器化应将 db.response.status_code 设置为所有代码的连接字符串，并使用 '/' 作为分隔符。
例如，通用数据库仪器检测到错误并具有 SQLSTATE "42000" 和特定于供应商的 1071，则应将 db.response.status_code 设置为 "42000/1071"。
[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 | 当检测不到自定义值时使用的回退错误值。 | |
示例
这是一个 MySQL 数据库 span 的属性示例
| 键 | 值 |
|---|---|
| Span 名称 | "SELECT orders" |
db.namespace | "ShopDb" |
db.system.name | "mysql" |
server.address | "shopdb.example.com" |
server.port | 3306 |
db.query.text | "SELECT * FROM orders WHERE order_id = 'o4711'" |