Oracle Database 的语义约定

状态: 开发中

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

Span

状态: 开发中

表示调用 Oracle SQL Database 的 Span 应遵循通用的 数据库客户端 Span 的语义约定。

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

**Span 类型**应为 CLIENT。

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

Attributes

键Stability需求级别Value Type描述Example Values
db.namespaceStable有条件要求 如果在不产生额外网络调用的情况下可用。字符串与连接关联的数据库，由实例名、数据库名和服务名限定。[1]ORCL1|PDB1|db_high.adb.oraclecloud.com; ORCL1|DB1|db_low.adb.oraclecloud.com; ORCL1|DB1|order-processing-service
db.response.status_codeStable有条件要求 如果响应以警告或错误结束。字符串Oracle Database 错误编号，记录为字符串。[2]ORA-02813; ORA-02613
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 = :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 应设置为实例名、数据库名和服务名的组合，遵循 {service_name}|{database_name}|{instance_name} 模式。任何缺失的组件（及其关联的分隔符）应被省略。

对于 CDB 架构，数据库名将是 pdb 名称。对于非 CDB，它将是 DB_NAME 参数。

[2] db.response.status_code: Oracle Database 错误代码是特定于供应商的错误代码，不遵循 SQLSTATE 约定。所有 Oracle Database 错误代码都应被视为错误。

[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

上下文传播

状态: 开发中

V$SESSION.ACTION

Instrumentation 可以使用固定长度 64 字节的值通过 V$SESSION.ACTION 传播上下文，在执行查询之前注入 Span 上下文的一部分（trace-id、span-id、trace-flags、协议版本）。例如，当使用 W3C Trace Context 时，应仅注入 traceparent 的字符串表示形式。上下文注入不应默认启用，但 instrumentation 允许用户选择启用它。

由于 V$SESSION.ACTION 的值长度限制为 64 字节，因此不应注入可变上下文部分（tracestate、baggage）。

传播上下文的 Instrumentation 必须在与 SQL 语句相同的物理连接上更新 V$SESSION.ACTION。

示例

请注意，不同语言的 Oracle 数据库驱动程序在更新 V$SESSION.ACTION 方面可能有不同的实现。

对于查询 SELECT * FROM songs，其中 traceparent 是 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

在与 SQL 语句相同的物理连接上运行以下命令

BEGIN
    DBMS_APPLICATION_INFO.SET_ACTION('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
END;

然后运行查询

SELECT * FROM songs;

指标

Oracle Database 驱动程序 instrumentation 应根据通用的 数据库客户端指标的语义约定 收集指标。

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