PostgreSQL 客户端操作的语义约定

状态: 稳定，除非另有说明。

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

Span

状态: 稳定

代表调用 PostgreSQL 数据库的 Span 应遵循通用的 数据库客户端 Span 的语义约定。

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

**Span 类型**应为 CLIENT。

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

Attributes

键Stability需求级别Value Type描述Example Values
db.namespaceStable有条件要求 如果在不产生额外网络调用的情况下可用。字符串与连接关联的模式，由数据库名称限定。[1]mydatabase.products; mydatabase.customers
db.response.status_codeStable有条件要求 如果响应以警告或错误结束。字符串PostgreSQL 错误代码. [2]08000; 08P01
error.typeStable有条件必需 仅在操作失败时。字符串描述操作结束的错误类别。[3]timeout；java.net.UnknownHostException；server_certificate_invalid；500
server.portStable有条件地必需 [4]int服务器端口号。[5]80; 8080; 443
db.collection.nameStable推荐 [6]字符串数据库中的集合（表、容器）的名称。[7]public.users; customers
db.operation.batch.sizeStable推荐int批量操作中包含的查询数量。 [8]2; 3; 4
db.operation.nameStable推荐 [9]字符串正在执行的操作或命令的名称。[10]EXECUTE; INSERT
db.query.summaryStable推荐 [11]字符串数据库查询的低基数摘要。[12]SELECT wuser_table; INSERT shipping_details SELECT orders; get user by id
db.query.textStable推荐 [13]字符串正在执行的数据库查询。[14]SELECT * FROM wuser_table where username = ?; SET mykey ?
db.stored_procedure.nameStable推荐 [15]字符串数据库中的存储过程的名称。[16]GetCustomer
server.addressStable推荐字符串数据库主机的名称。[17]example.com；10.1.2.80；/tmp/my.sock
db.query.parameter.<key>Development选择加入字符串数据库查询参数，其中 <key> 是参数名称，属性值是参数值的字符串表示。[18]someval; 55
db.response.returned_rowsDevelopment选择加入int操作返回的行数。10; 30; 1000

[1] db.namespace: db.namespace 应设置为数据库和模式名称的组合，遵循 {database}|{schema} 模式。如果 {database} 或 {schema} 中有一个不可用，db.namespace 应设置为另一个（不带任何 | 分隔符）。

连接当前关联的数据库在其生命周期中可能会发生变化，例如通过执行 SET search_path TO <schema>。如果搜索路径包含多个模式，则应使用搜索路径中的第一个模式。

如果仪器化无法在每次查询时捕获连接当前关联的模式，而不会触发额外的查询（例如 SELECT current_schema()），则建议回退并使用建立连接时提供的模式。

仪器化应记录 db.namespace 是否反映了建立连接时提供的模式。

仪器化可以使用建立连接时使用的用户名作为模式名称的替代。

仪器化应记录 db.namespace 是否反映了提供连接时使用的用户。

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

[2] db.response.status_code: PostgreSQL 遵循 SQL 标准的 SQLSTATE 约定。“Class 02”或更高的响应代码应被视为错误。

[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当检测不到自定义值时使用的回退错误值。Stable

指标

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

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