From 568df1ae9416f304e66496ff60d4b7366e096448 Mon Sep 17 00:00:00 2001 From: Sudarshan Soma <48428602+sudarshan12s@users.noreply.github.com> Date: Mon, 17 Feb 2025 12:51:54 +0530 Subject: [PATCH 01/14] semantic definitions for OracleDB (#1) * - Add semantic conventions for oracle database --- .chloggen/add_oracledb_semconv.yaml | 23 ++++++ docs/database/README.md | 1 + docs/database/oracledb.md | 108 ++++++++++++++++++++++++++++ model/database/spans.yaml | 23 ++++++ schema-next.yaml | 16 +++++ 5 files changed, 171 insertions(+) create mode 100644 .chloggen/add_oracledb_semconv.yaml create mode 100644 docs/database/oracledb.md diff --git a/.chloggen/add_oracledb_semconv.yaml b/.chloggen/add_oracledb_semconv.yaml new file mode 100644 index 0000000000..7bb62dab6f --- /dev/null +++ b/.chloggen/add_oracledb_semconv.yaml @@ -0,0 +1,23 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adding semnatic conventions for `oracledb` instrumentations. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [2612] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: + Oracle Database semantic conventions. diff --git a/docs/database/README.md b/docs/database/README.md index c45cc751ab..604d756ad1 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -50,6 +50,7 @@ Technology specific semantic conventions are defined for the following databases * [HBase](hbase.md): Semantic Conventions for *HBase*. * [MongoDB](mongodb.md): Semantic Conventions for *MongoDB*. * [Microsoft SQL Server](mssql.md): Semantic Conventions for *Microsoft SQL Server*. +* [Oracle Database](oracledb.md): Semantic Conventions for *Oracle Database*. * [Redis](redis.md): Semantic Conventions for *Redis*. * [SQL](sql.md): Semantic Conventions for *SQL* databases. diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md new file mode 100644 index 0000000000..fcb2955d1b --- /dev/null +++ b/docs/database/oracledb.md @@ -0,0 +1,108 @@ + + +# Semantic conventions for Oracle Database + +**Status**: [Release Candidate][DocumentStatus] + + + +- [Spans](#spans) +- [Metrics](#metrics) + + + +The Semantic Conventions for *Oracle Database* extend and override the [Database Semantic Conventions](README.md). + +## Spans + +Spans representing calls to Oracle Database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + +`db.system.name` MUST be set to `"oracle.db"` and SHOULD be provided **at span creation time**. + +The following table outlines the span attributes applicable to Oracle Database. + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The service name associated with the connection. [1] | `db_high.adb.oraclecloud.com`; `db_low.adb.oraclecloud.com` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. | `ORA-02813`; `ORA-024459` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `1521`; `1522`; | `Conditionally Required` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [5] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [7] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [8] | `VARIABLE mykey VARCHAR2(50) = 'some_val';`; `SELECT * FROM wuser_table where username = :mykey`; | `Recommended` [9] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +**[1] `db.namespace`:** `db.namespace` SHOULD be set to the service name used to connect to the database. + +Instrumentation SHOULD document if `db.namespace` reflects the service name provided when the connection was established. + +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + +**[2] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. +When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. +Instrumentations SHOULD document how `error.type` is populated. + +**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[5] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. + +**[6] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. +A Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. + +**[7] `db.query.summary`:** if readily available or if instrumentation supports query summarization. + +**[8] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. + +**[9] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md). + +**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[11] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. + +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.namespace`](/docs/attributes-registry/db.md) +* [`db.query.summary`](/docs/attributes-registry/db.md) +* [`db.query.text`](/docs/attributes-registry/db.md) +* [`server.address`](/docs/attributes-registry/server.md) +* [`server.port`](/docs/attributes-registry/server.md) + +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + +## Metrics + +Oracle Database driver instrumentation SHOULD collect metrics according to the general +[Semantic Conventions for Database Client Metrics](database-metrics.md). + +`db.system.name` MUST be set to `"oracle.db"`. + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 7bbe1bd476..6b77f292f8 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -810,3 +810,26 @@ groups: - ref: azure.cosmosdb.operation.contacted_regions requirement_level: conditionally_required: If available. + - id: span.db.oracledb.client + type: span + stability: experimental + extends: span.db.sql.client + span_kind: client + brief: > + Attributes for Oracle Database + attributes: + - ref: db.namespace + sampling_relevant: true + brief: The service name associated with the connection. + note: | + Instrumentation SHOULD document if `db.namespace` reflects the service name provided when the connection was established. + + It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + examples: ["db_high.adb.oraclecloud.com", "db_low.adb.oraclecloud.com"] + - ref: db.response.status_code + brief: > + [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. + note: > + Oracle Database error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) + conventions. All Oracle Database error codes SHOULD be considered errors. + examples: ["ORA-02813", "ORA-02613"] \ No newline at end of file diff --git a/schema-next.yaml b/schema-next.yaml index 23675166b0..57e69298ae 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -7,6 +7,22 @@ versions: - rename_metrics: k8s.replication_controller.desired_pods: k8s.replicationcontroller.desired_pods k8s.replication_controller.available_pods: k8s.replicationcontroller.available_pods + all: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/TODO + # add semantic conventions for Oracle Database + - add_attributes: + db.system.name + db.namespace + db.response.status_code + error.type + server.port + db.operation.batch.size + db.query.summary + db.query.text + db.response.returned_rows + server.address + db.operation.parameter. 1.30.0: all: changes: From 1616f49a3ddb78032a193363c4de092177243b26 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Mon, 17 Feb 2025 15:52:20 +0530 Subject: [PATCH 02/14] - Remove semicolon in example --- docs/database/oracledb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md index fcb2955d1b..53d438ae40 100644 --- a/docs/database/oracledb.md +++ b/docs/database/oracledb.md @@ -38,7 +38,7 @@ The following table outlines the span attributes applicable to Oracle Database. | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `1521`; `1522`; | `Conditionally Required` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [5] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [7] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [8] | `VARIABLE mykey VARCHAR2(50) = 'some_val';`; `SELECT * FROM wuser_table where username = :mykey`; | `Recommended` [9] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [8] | `VARIABLE mykey VARCHAR2(50) = 'some_val'`; `SELECT * FROM wuser_table where username = :mykey`; | `Recommended` [9] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | From 70e327c52b69d8f53485b842dca1811ea797f65e Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 19 Feb 2025 07:41:04 +0530 Subject: [PATCH 03/14] - Add oracledb specific attributes --- docs/attributes-registry/README.md | 1 + docs/attributes-registry/oracledb.md | 20 ++++++++++++++++++++ docs/database/oracledb.md | 7 +++++++ 3 files changed, 28 insertions(+) create mode 100644 docs/attributes-registry/oracledb.md diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 629a46c242..7be3a0ead0 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -82,6 +82,7 @@ Currently, the following namespaces exist: - [NodeJS](nodejs.md) - [OCI](oci.md) - [OpenTracing](opentracing.md) +- [OracleDatabase](oracledb.md) - [OS](os.md) - [OTel](otel.md) - [Peer](peer.md) diff --git a/docs/attributes-registry/oracledb.md b/docs/attributes-registry/oracledb.md new file mode 100644 index 0000000000..0f66b38014 --- /dev/null +++ b/docs/attributes-registry/oracledb.md @@ -0,0 +1,20 @@ + + + +# Oracle Database + +## Oracle Database Attributes + +This section defines attributes for Oracle Database. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `oracledb.pool.min` | int | This read-only property is a number which specifies the minimum number of connections a connection pool maintains, even when there is no activity to the target database. | `0`; `3`; `4` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pool.max` | int | This read-only property is a number which specifies the maximum number of connections that can be open in the connection pool. | `2`; `30`; `70` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pool.incr` | int | This read-only property is a number which specifies the number of connections that are opened whenever a connection request exceeds the number of currently open connections. | `2`; `10`; `15` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.bind.values` | string[] | Array of bind values passed to parameterized queries. | `['43', 'scott', 'true'` | [Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.instance` | string | Oracle Database Instance. | `ORCL1`; `ORCL2`; | [Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pdbname` | string | Pluggable Database (PDB) name in a Multitenant Container Database (CDB) environment. | `PDB1`; `PDB2`; | [Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.implicit_release` | boolean | Indicates if the internal connection is released back to pool or not after executing a query. | `true` | [Development](https://img.shields.io/badge/-development-blue) | + +--- diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md index 53d438ae40..c7ff60cd2c 100644 --- a/docs/database/oracledb.md +++ b/docs/database/oracledb.md @@ -42,6 +42,13 @@ The following table outlines the span attributes applicable to Oracle Database. | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.pool.min`](/docs/attributes-registry/oracledb.md) | int | This read-only property is a number which specifies the minimum number of connections a connection pool maintains, even when there is no activity to the target database. | `0`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.pool.max`](/docs/attributes-registry/oracledb.md) | int | This read-only property is a number which specifies the maximum number of connections that can be open in the connection pool. | `2`; `30`; `70` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.pool.incr`](/docs/attributes-registry/oracledb.md) | int | This read-only property is a number which specifies the number of connections that are opened whenever a connection request exceeds the number of currently open connections. | `2`; `10`; `15` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.bind.values`](/docs/attributes-registry/oracledb.md) | string[] | Array of bind values passed to parameterized queries. | `['43', 'scott', 'true'` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.instance`](/docs/attributes-registry/oracledb.md) | string | Oracle Database Instance. | `ORCL1`; `ORCL2`; | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.pdbname`](/docs/attributes-registry/oracledb.md) | string | Pluggable Database (PDB) name in a Multitenant Container Database (CDB) environment. | `PDB1`; `PDB2`; | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`oracledb.implicit_release`](/docs/attributes-registry/oracledb.md) | boolean | Indicates if the internal connection is released back to pool or not after executing a query. | `true` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** `db.namespace` SHOULD be set to the service name used to connect to the database. From 4c93cdda0403cc2123108b8125789801fe75d304 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 5 Mar 2025 14:12:31 +0530 Subject: [PATCH 04/14] - Revert the non-existing add_attributes section --- schema-next.yaml | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/schema-next.yaml b/schema-next.yaml index 22efd242ef..28447ad5dc 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -9,20 +9,6 @@ versions: attribute_map: android.state: android.app.state io.state: ios.app.state - # https://github.com/open-telemetry/semantic-conventions/pull/TODO - # add semantic conventions for Oracle Database - - add_attributes: - db.system.name - db.namespace - db.response.status_code - error.type - server.port - db.operation.batch.size - db.query.summary - db.query.text - db.response.returned_rows - server.address - db.operation.parameter. metrics: changes: - rename_metrics: From bd5ad2d7db1f105f9b03f78bb09054e9ba408a38 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 5 Mar 2025 15:03:14 +0530 Subject: [PATCH 05/14] - Add oracledb specific attributes in model/oracledb/registry.yaml --- model/oracledb/registry.yaml | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 model/oracledb/registry.yaml diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml new file mode 100644 index 0000000000..c36ff11989 --- /dev/null +++ b/model/oracledb/registry.yaml @@ -0,0 +1,48 @@ +groups: + - id: registry.oracledb + type: attribute_group + display_name: Oracle Database Attributes + brief: > + This section defines attributes for Oracle Database. + attributes: + - id: oracledb.pool.min + type: int + stability: development + brief: > + The minimum number of connections that the pool maintains. + examples: 10 + - id: oracledb.pool.max + type: int + stability: development + brief: > + The maximum number of connections that can be open in the pool. + examples: 30 + - id: oracledb.pool.increment + type: int + stability: development + brief: > + The number of connections added when the pool needs to expand. + examples: 5 + - id: oracledb.instance + type: string + stability: development + brief: The name of the Oracle Database instance. + examples: "ORCL1" + - id: oracledb.bind.values + type: string[] + stability: development + brief: > + Array of bind values passed to parameterized queries. + examples: ["true", "42"] + - id: oracledb.pdb_name + type: string + stability: development + brief: > + The name of the pluggable database (PDB) the connection is using. + examples: "PDB1" + - id: oracledb.implicit_release + type: boolean + stability: development + brief: > + Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. + examples: [true] From 6af1c2019e1c5b158707e32e959450275f2cceec Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 5 Mar 2025 17:55:19 +0530 Subject: [PATCH 06/14] - Added changes made by make table-generation attribute-registry-generation --- docs/attributes-registry/README.md | 2 +- docs/attributes-registry/oracledb.md | 18 ++++++++---------- model/oracledb/registry.yaml | 3 ++- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 7be3a0ead0..44be91a2dd 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -82,7 +82,7 @@ Currently, the following namespaces exist: - [NodeJS](nodejs.md) - [OCI](oci.md) - [OpenTracing](opentracing.md) -- [OracleDatabase](oracledb.md) +- [Oracledb](oracledb.md) - [OS](os.md) - [OTel](otel.md) - [Peer](peer.md) diff --git a/docs/attributes-registry/oracledb.md b/docs/attributes-registry/oracledb.md index 0f66b38014..063f68baf9 100644 --- a/docs/attributes-registry/oracledb.md +++ b/docs/attributes-registry/oracledb.md @@ -1,7 +1,7 @@ -# Oracle Database +# Oracledb ## Oracle Database Attributes @@ -9,12 +9,10 @@ This section defines attributes for Oracle Database. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `oracledb.pool.min` | int | This read-only property is a number which specifies the minimum number of connections a connection pool maintains, even when there is no activity to the target database. | `0`; `3`; `4` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pool.max` | int | This read-only property is a number which specifies the maximum number of connections that can be open in the connection pool. | `2`; `30`; `70` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pool.incr` | int | This read-only property is a number which specifies the number of connections that are opened whenever a connection request exceeds the number of currently open connections. | `2`; `10`; `15` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.bind.values` | string[] | Array of bind values passed to parameterized queries. | `['43', 'scott', 'true'` | [Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.instance` | string | Oracle Database Instance. | `ORCL1`; `ORCL2`; | [Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pdbname` | string | Pluggable Database (PDB) name in a Multitenant Container Database (CDB) environment. | `PDB1`; `PDB2`; | [Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.implicit_release` | boolean | Indicates if the internal connection is released back to pool or not after executing a query. | `true` | [Development](https://img.shields.io/badge/-development-blue) | - ---- +| `oracledb.bind.values` | string[] | Array of bind values passed to parameterized queries. | `["true...", "42..."]` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.instance` | string | The name of the Oracle Database instance. | `ORCL1` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pdb_name` | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pool.increment` | int | The number of connections added when the pool needs to expand. | `5` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pool.max` | int | The maximum number of connections that can be open in the pool. | `30` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracledb.pool.min` | int | The minimum number of connections that the pool maintains. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml index c36ff11989..53cb165c45 100644 --- a/model/oracledb/registry.yaml +++ b/model/oracledb/registry.yaml @@ -33,7 +33,8 @@ groups: stability: development brief: > Array of bind values passed to parameterized queries. - examples: ["true", "42"] + examples: + - ['true...', '42...'] - id: oracledb.pdb_name type: string stability: development From 44008bb99e8d0103b83910369d0d35c4da6c8d85 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 5 Mar 2025 19:33:02 +0530 Subject: [PATCH 07/14] - remove bindvalues as its defined in standard (`db.operation.parameter.`) in generic way. --- docs/attributes-registry/oracledb.md | 1 - model/oracledb/registry.yaml | 7 ------- 2 files changed, 8 deletions(-) diff --git a/docs/attributes-registry/oracledb.md b/docs/attributes-registry/oracledb.md index 063f68baf9..7c8d9b35f7 100644 --- a/docs/attributes-registry/oracledb.md +++ b/docs/attributes-registry/oracledb.md @@ -9,7 +9,6 @@ This section defines attributes for Oracle Database. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `oracledb.bind.values` | string[] | Array of bind values passed to parameterized queries. | `["true...", "42..."]` | ![Development](https://img.shields.io/badge/-development-blue) | | `oracledb.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | | `oracledb.instance` | string | The name of the Oracle Database instance. | `ORCL1` | ![Development](https://img.shields.io/badge/-development-blue) | | `oracledb.pdb_name` | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml index 53cb165c45..b5fcf33fe3 100644 --- a/model/oracledb/registry.yaml +++ b/model/oracledb/registry.yaml @@ -28,13 +28,6 @@ groups: stability: development brief: The name of the Oracle Database instance. examples: "ORCL1" - - id: oracledb.bind.values - type: string[] - stability: development - brief: > - Array of bind values passed to parameterized queries. - examples: - - ['true...', '42...'] - id: oracledb.pdb_name type: string stability: development From 50db5670f735222a605d9e92677f39e4f9071dd2 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 5 Mar 2025 20:10:21 +0530 Subject: [PATCH 08/14] - keep in alphabatic order --- model/oracledb/registry.yaml | 40 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml index b5fcf33fe3..58d557f55a 100644 --- a/model/oracledb/registry.yaml +++ b/model/oracledb/registry.yaml @@ -5,24 +5,12 @@ groups: brief: > This section defines attributes for Oracle Database. attributes: - - id: oracledb.pool.min - type: int - stability: development - brief: > - The minimum number of connections that the pool maintains. - examples: 10 - - id: oracledb.pool.max - type: int - stability: development - brief: > - The maximum number of connections that can be open in the pool. - examples: 30 - - id: oracledb.pool.increment - type: int + - id: oracledb.implicit_release + type: boolean stability: development brief: > - The number of connections added when the pool needs to expand. - examples: 5 + Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. + examples: [true] - id: oracledb.instance type: string stability: development @@ -34,9 +22,21 @@ groups: brief: > The name of the pluggable database (PDB) the connection is using. examples: "PDB1" - - id: oracledb.implicit_release - type: boolean + - id: oracledb.pool.increment + type: int stability: development brief: > - Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. - examples: [true] + The number of connections added when the pool needs to expand. + examples: 5 + - id: oracledb.pool.max + type: int + stability: development + brief: > + The maximum number of connections that can be open in the pool. + examples: 30 + - id: oracledb.pool.min + type: int + stability: development + brief: > + The minimum number of connections that the pool maintains. + examples: 10 From fa073d8cd6fe9ebba46a664a6028b2b29f5de7ed Mon Sep 17 00:00:00 2001 From: Sudarshan Soma <48428602+sudarshan12s@users.noreply.github.com> Date: Thu, 6 Mar 2025 12:22:57 +0530 Subject: [PATCH 09/14] Update model/database/spans.yaml Co-authored-by: Liudmila Molkova --- model/database/spans.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/spans.yaml b/model/database/spans.yaml index a1fd9d6c65..6cef152fed 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -840,7 +840,7 @@ groups: conditionally_required: If available. - id: span.db.oracledb.client type: span - stability: experimental + stability: development extends: span.db.sql.client span_kind: client brief: > From c9a9cf221345eb71742eddfafa5d946d82db73f3 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Thu, 6 Mar 2025 13:15:50 +0530 Subject: [PATCH 10/14] -incorporate review comments --- docs/attributes-registry/README.md | 2 +- docs/attributes-registry/oracledb.md | 12 ++++++------ model/oracledb/registry.yaml | 12 ++++++------ templates/registry/markdown/weaver.yaml | 1 + 4 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 44be91a2dd..52e8417df4 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -82,7 +82,7 @@ Currently, the following namespaces exist: - [NodeJS](nodejs.md) - [OCI](oci.md) - [OpenTracing](opentracing.md) -- [Oracledb](oracledb.md) +- [OracleDB](oracledb.md) - [OS](os.md) - [OTel](otel.md) - [Peer](peer.md) diff --git a/docs/attributes-registry/oracledb.md b/docs/attributes-registry/oracledb.md index 7c8d9b35f7..5129bcc6dc 100644 --- a/docs/attributes-registry/oracledb.md +++ b/docs/attributes-registry/oracledb.md @@ -9,9 +9,9 @@ This section defines attributes for Oracle Database. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `oracledb.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.instance` | string | The name of the Oracle Database instance. | `ORCL1` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pdb_name` | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pool.increment` | int | The number of connections added when the pool needs to expand. | `5` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pool.max` | int | The maximum number of connections that can be open in the pool. | `30` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracledb.pool.min` | int | The minimum number of connections that the pool maintains. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.instance` | string | The name of the Oracle Database instance. | `ORCL1` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.pdb_name` | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.pool.increment` | int | The number of connections added when the pool needs to expand. | `5` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.pool.max` | int | The maximum number of connections that can be open in the pool. | `30` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.pool.min` | int | The minimum number of connections that the pool maintains. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml index 58d557f55a..81b08a1bee 100644 --- a/model/oracledb/registry.yaml +++ b/model/oracledb/registry.yaml @@ -5,36 +5,36 @@ groups: brief: > This section defines attributes for Oracle Database. attributes: - - id: oracledb.implicit_release + - id: oracle.db.implicit_release type: boolean stability: development brief: > Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. examples: [true] - - id: oracledb.instance + - id: oracle.db.instance type: string stability: development brief: The name of the Oracle Database instance. examples: "ORCL1" - - id: oracledb.pdb_name + - id: oracle.db.pdb_name type: string stability: development brief: > The name of the pluggable database (PDB) the connection is using. examples: "PDB1" - - id: oracledb.pool.increment + - id: oracle.db.pool.increment type: int stability: development brief: > The number of connections added when the pool needs to expand. examples: 5 - - id: oracledb.pool.max + - id: oracle.db.pool.max type: int stability: development brief: > The maximum number of connections that can be open in the pool. examples: 30 - - id: oracledb.pool.min + - id: oracle.db.pool.min type: int stability: development brief: > diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index cbe61f30e3..66524478c3 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -28,6 +28,7 @@ acronyms: - NodeJS - OCI - OpenTracing + - OracleDB - OS - OTel - RabbitMQ From 1c2b41692bbadb703d11cd6a392d147e198e63ab Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Thu, 6 Mar 2025 18:56:27 +0530 Subject: [PATCH 11/14] - Correct the Yaml files and generated md files are added. --- docs/attributes-registry/oracledb.md | 8 ++-- docs/database/oracledb.md | 68 ++++++++++++++-------------- model/database/spans.yaml | 40 +++++++++++++++- model/oracledb/registry.yaml | 26 +++-------- 4 files changed, 83 insertions(+), 59 deletions(-) diff --git a/docs/attributes-registry/oracledb.md b/docs/attributes-registry/oracledb.md index 5129bcc6dc..c48ff0b104 100644 --- a/docs/attributes-registry/oracledb.md +++ b/docs/attributes-registry/oracledb.md @@ -1,7 +1,7 @@ -# Oracledb +# OracleDB ## Oracle Database Attributes @@ -9,9 +9,7 @@ This section defines attributes for Oracle Database. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `oracle.db.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.client.connection.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | +| `oracle.db.client.connection.increment` | int | The number of connections added when the pool needs to expand. | `5` | ![Development](https://img.shields.io/badge/-development-blue) | | `oracle.db.instance` | string | The name of the Oracle Database instance. | `ORCL1` | ![Development](https://img.shields.io/badge/-development-blue) | | `oracle.db.pdb_name` | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracle.db.pool.increment` | int | The number of connections added when the pool needs to expand. | `5` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracle.db.pool.max` | int | The maximum number of connections that can be open in the pool. | `30` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracle.db.pool.min` | int | The minimum number of connections that the pool maintains. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md index c7ff60cd2c..a83390100a 100644 --- a/docs/database/oracledb.md +++ b/docs/database/oracledb.md @@ -33,54 +33,50 @@ The following table outlines the span attributes applicable to Oracle Database. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The service name associated with the connection. [1] | `db_high.adb.oraclecloud.com`; `db_low.adb.oraclecloud.com` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. | `ORA-02813`; `ORA-024459` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `1521`; `1522`; | `Conditionally Required` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [5] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [7] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [8] | `VARIABLE mykey VARCHAR2(50) = 'some_val'`; `SELECT * FROM wuser_table where username = :mykey`; | `Recommended` [9] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.pool.min`](/docs/attributes-registry/oracledb.md) | int | This read-only property is a number which specifies the minimum number of connections a connection pool maintains, even when there is no activity to the target database. | `0`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.pool.max`](/docs/attributes-registry/oracledb.md) | int | This read-only property is a number which specifies the maximum number of connections that can be open in the connection pool. | `2`; `30`; `70` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.pool.incr`](/docs/attributes-registry/oracledb.md) | int | This read-only property is a number which specifies the number of connections that are opened whenever a connection request exceeds the number of currently open connections. | `2`; `10`; `15` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.bind.values`](/docs/attributes-registry/oracledb.md) | string[] | Array of bind values passed to parameterized queries. | `['43', 'scott', 'true'` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.instance`](/docs/attributes-registry/oracledb.md) | string | Oracle Database Instance. | `ORCL1`; `ORCL2`; | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.pdbname`](/docs/attributes-registry/oracledb.md) | string | Pluggable Database (PDB) name in a Multitenant Container Database (CDB) environment. | `PDB1`; `PDB2`; | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`oracledb.implicit_release`](/docs/attributes-registry/oracledb.md) | boolean | Indicates if the internal connection is released back to pool or not after executing a query. | `true` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | - -**[1] `db.namespace`:** `db.namespace` SHOULD be set to the service name used to connect to the database. - -Instrumentation SHOULD document if `db.namespace` reflects the service name provided when the connection was established. +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. [2] | `ORA-02813`; `ORA-02613` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = :mykey` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`oracle.db.client.connection.implicit_release`](/docs/attributes-registry/oracledb.md) | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. [11] | `true` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`oracle.db.client.connection.increment`](/docs/attributes-registry/oracledb.md) | int | The number of connections added when the pool needs to expand. | `5` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`oracle.db.instance`](/docs/attributes-registry/oracledb.md) | string | The name of the Oracle Database instance. | `ORCL1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`oracle.db.pdb_name`](/docs/attributes-registry/oracledb.md) | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +**[1] `db.namespace`:** Instrumentation SHOULD document if `db.namespace` reflects the service name provided when the connection was established. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. +**[2] `db.response.status_code`:** Oracle Database error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All Oracle Database error codes SHOULD be considered errors. + +**[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. Instrumentations SHOULD document how `error.type` is populated. -**[3] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[4] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -**[5] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +**[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. -**[6] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -A Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +**[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[7] `db.query.summary`:** if readily available or if instrumentation supports query summarization. +**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[8] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. +**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). -**[9] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md). +**[11] `oracle.db.client.connection.implicit_release`:** This attribute appears in the span when an implicit release occurs, and its value is always true. -**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[12] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[11] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[13] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. The following attributes can be important for making sampling decisions @@ -89,6 +85,10 @@ and SHOULD be provided **at span creation time** (if provided at all): * [`db.namespace`](/docs/attributes-registry/db.md) * [`db.query.summary`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) +* [`oracle.db.client.connection.implicit_release`](/docs/attributes-registry/oracledb.md) +* [`oracle.db.client.connection.increment`](/docs/attributes-registry/oracledb.md) +* [`oracle.db.instance`](/docs/attributes-registry/oracledb.md) +* [`oracle.db.pdb_name`](/docs/attributes-registry/oracledb.md) * [`server.address`](/docs/attributes-registry/server.md) * [`server.port`](/docs/attributes-registry/server.md) diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 6cef152fed..b03e63f651 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -860,4 +860,42 @@ groups: note: > Oracle Database error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All Oracle Database error codes SHOULD be considered errors. - examples: ["ORA-02813", "ORA-02613"] \ No newline at end of file + examples: ["ORA-02813", "ORA-02613"] + - ref: db.query.text + sampling_relevant: true + brief: > + The database query being executed. + requirement_level: + recommended: > + Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured + and sanitized to exclude sensitive data, e.g. by redacting all literal values present + in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + Parameterized query text MUST also NOT be collected by default unless explicitly configured. + The query parameter values themselves are opt-in, + see [`db.operation.parameter.`](../attributes-registry/db.md)). + note: > + For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, + otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. + examples: ["SELECT * FROM wuser_table where username = :mykey"] + - ref: oracle.db.client.connection.implicit_release + sampling_relevant: true + brief: > + Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. + note: > + This attribute appears in the span when an implicit release occurs, and its value is always true. + examples: [true] + - ref: oracle.db.client.connection.increment + sampling_relevant: true + brief: > + The number of connections added when the pool needs to expand. + - ref: oracle.db.instance + sampling_relevant: true + brief: > + The name of the Oracle Database instance. + examples: ["ORCL1"] + - ref: oracle.db.pdb_name + sampling_relevant: true + brief: > + The name of the pluggable database (PDB) the connection is using. + examples: ["PDB1"] diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml index 81b08a1bee..ab3de7bc86 100644 --- a/model/oracledb/registry.yaml +++ b/model/oracledb/registry.yaml @@ -5,12 +5,18 @@ groups: brief: > This section defines attributes for Oracle Database. attributes: - - id: oracle.db.implicit_release + - id: oracle.db.client.connection.implicit_release type: boolean stability: development brief: > Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. examples: [true] + - id: oracle.db.client.connection.increment + type: int + stability: development + brief: > + The number of connections added when the pool needs to expand. + examples: 5 - id: oracle.db.instance type: string stability: development @@ -22,21 +28,3 @@ groups: brief: > The name of the pluggable database (PDB) the connection is using. examples: "PDB1" - - id: oracle.db.pool.increment - type: int - stability: development - brief: > - The number of connections added when the pool needs to expand. - examples: 5 - - id: oracle.db.pool.max - type: int - stability: development - brief: > - The maximum number of connections that can be open in the pool. - examples: 30 - - id: oracle.db.pool.min - type: int - stability: development - brief: > - The minimum number of connections that the pool maintains. - examples: 10 From 1dbaba9a50a203082b798b94fb01128f292d45a1 Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 19 Mar 2025 23:07:24 +0530 Subject: [PATCH 12/14] - incorporated comments --- docs/attributes-registry/oracledb.md | 3 --- model/database/spans.yaml | 27 ++++++++------------------- model/oracledb/registry.yaml | 17 ----------------- 3 files changed, 8 insertions(+), 39 deletions(-) diff --git a/docs/attributes-registry/oracledb.md b/docs/attributes-registry/oracledb.md index c48ff0b104..47b355411c 100644 --- a/docs/attributes-registry/oracledb.md +++ b/docs/attributes-registry/oracledb.md @@ -10,6 +10,3 @@ This section defines attributes for Oracle Database. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `oracle.db.client.connection.implicit_release` | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. | `true` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracle.db.client.connection.increment` | int | The number of connections added when the pool needs to expand. | `5` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracle.db.instance` | string | The name of the Oracle Database instance. | `ORCL1` | ![Development](https://img.shields.io/badge/-development-blue) | -| `oracle.db.pdb_name` | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/database/spans.yaml b/model/database/spans.yaml index b03e63f651..e6ffc686d2 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -848,12 +848,15 @@ groups: attributes: - ref: db.namespace sampling_relevant: true - brief: The service name associated with the connection. + brief: > + The database associated with the connection, qualified by the instance name, + database name and service name. note: | - Instrumentation SHOULD document if `db.namespace` reflects the service name provided when the connection was established. - - It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - examples: ["db_high.adb.oraclecloud.com", "db_low.adb.oraclecloud.com"] + `db.namespace` SHOULD be set to the combination of instance name, database name and + service name following the `{instance_name}|{database_name}|{service_name}` pattern. + For CDB architecture, database name would be pdb name. For Non-CDB, it would be + `DB_NAME` parameter. + examples: ["ORCL1|PDB1|db_high.adb.oraclecloud.com", "ORCL1|DB1|db_low.adb.oraclecloud.com"] - ref: db.response.status_code brief: > [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. @@ -885,17 +888,3 @@ groups: note: > This attribute appears in the span when an implicit release occurs, and its value is always true. examples: [true] - - ref: oracle.db.client.connection.increment - sampling_relevant: true - brief: > - The number of connections added when the pool needs to expand. - - ref: oracle.db.instance - sampling_relevant: true - brief: > - The name of the Oracle Database instance. - examples: ["ORCL1"] - - ref: oracle.db.pdb_name - sampling_relevant: true - brief: > - The name of the pluggable database (PDB) the connection is using. - examples: ["PDB1"] diff --git a/model/oracledb/registry.yaml b/model/oracledb/registry.yaml index ab3de7bc86..a0da3068af 100644 --- a/model/oracledb/registry.yaml +++ b/model/oracledb/registry.yaml @@ -11,20 +11,3 @@ groups: brief: > Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. examples: [true] - - id: oracle.db.client.connection.increment - type: int - stability: development - brief: > - The number of connections added when the pool needs to expand. - examples: 5 - - id: oracle.db.instance - type: string - stability: development - brief: The name of the Oracle Database instance. - examples: "ORCL1" - - id: oracle.db.pdb_name - type: string - stability: development - brief: > - The name of the pluggable database (PDB) the connection is using. - examples: "PDB1" From 0d7fb762f82e37171d5c2de0e5d78340b2179bed Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 19 Mar 2025 23:19:11 +0530 Subject: [PATCH 13/14] - Add the generated oracledb.md --- docs/database/oracledb.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md index a83390100a..e5ed95df6b 100644 --- a/docs/database/oracledb.md +++ b/docs/database/oracledb.md @@ -32,7 +32,7 @@ The following table outlines the span attributes applicable to Oracle Database. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The service name associated with the connection. [1] | `db_high.adb.oraclecloud.com`; `db_low.adb.oraclecloud.com` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name, database name and service name. [1] | `ORCL1|PDB1|db_high.adb.oraclecloud.com`; `ORCL1|DB1|db_low.adb.oraclecloud.com` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. [2] | `ORA-02813`; `ORA-02613` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -41,15 +41,13 @@ The following table outlines the span attributes applicable to Oracle Database. | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = :mykey` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`oracle.db.client.connection.implicit_release`](/docs/attributes-registry/oracledb.md) | boolean | Boolean flag Indicating if the internal connection is released back to pool or not after executing a query. [11] | `true` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`oracle.db.client.connection.increment`](/docs/attributes-registry/oracledb.md) | int | The number of connections added when the pool needs to expand. | `5` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`oracle.db.instance`](/docs/attributes-registry/oracledb.md) | string | The name of the Oracle Database instance. | `ORCL1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`oracle.db.pdb_name`](/docs/attributes-registry/oracledb.md) | string | The name of the pluggable database (PDB) the connection is using. | `PDB1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -**[1] `db.namespace`:** Instrumentation SHOULD document if `db.namespace` reflects the service name provided when the connection was established. - -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +**[1] `db.namespace`:** `db.namespace` SHOULD be set to the combination of instance name, database name and +service name following the `{instance_name}|{database_name}|{service_name}` pattern. +For CDB architecture, database name would be pdb name. For Non-CDB, it would be +`DB_NAME` parameter. **[2] `db.response.status_code`:** Oracle Database error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All Oracle Database error codes SHOULD be considered errors. @@ -86,9 +84,6 @@ and SHOULD be provided **at span creation time** (if provided at all): * [`db.query.summary`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) * [`oracle.db.client.connection.implicit_release`](/docs/attributes-registry/oracledb.md) -* [`oracle.db.client.connection.increment`](/docs/attributes-registry/oracledb.md) -* [`oracle.db.instance`](/docs/attributes-registry/oracledb.md) -* [`oracle.db.pdb_name`](/docs/attributes-registry/oracledb.md) * [`server.address`](/docs/attributes-registry/server.md) * [`server.port`](/docs/attributes-registry/server.md) From 686e309b71851a17e5007fcb893bf79723b231da Mon Sep 17 00:00:00 2001 From: sudarshan12s Date: Wed, 19 Mar 2025 23:22:57 +0530 Subject: [PATCH 14/14] - Add generated files --- .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 4edc8d9694..0e603fdfa9 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -70,6 +70,7 @@ body: - area:nodejs - area:oci - area:opentracing + - area:oracle - area:os - area:otel - area:peer diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index b9e963a44b..0e1c02c436 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -62,6 +62,7 @@ body: - area:nodejs - area:oci - area:opentracing + - area:oracle - area:os - area:otel - area:peer