diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 1e6127c3b5..66b0b726c9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -129,8 +129,8 @@ /docs/non-normative/code-attrs-migration.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-code-attribute-approvers # Database semantic conventions -/docs/database/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers -/model/database/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers +/docs/db/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers +/model/db/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers /docs/non-normative/database-test-cases/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers /docs/non-normative/db-migration.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-db-approvers diff --git a/docs/README.md b/docs/README.md index 84757e51ea..e1ce39640a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,7 +23,7 @@ Semantic Conventions are defined for the following areas: * [CICD](cicd/README.md): Semantic Conventions for CICD systems. * [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries. * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. -* [Database](database/README.md): Semantic Conventions for database operations. +* [Database](db/README.md): Semantic Conventions for database operations. * [Exceptions](exceptions/README.md): Semantic Conventions for exceptions. * [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. * [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations. diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 4205a4f377..b6ebe6f047 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -72,7 +72,7 @@ interesting conventions are found. The following Semantic Conventions extend the general AWS SDK attributes for specific AWS services: -- [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for _AWS DynamoDB_. +- [AWS DynamoDB](/docs/db/dynamodb.md): Semantic Conventions for _AWS DynamoDB_. - [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for _AWS S3_. - [AWS Bedrock](/docs/gen-ai/aws-bedrock.md): Semantic Conventions for _AWS Bedrock_. - [AWS SNS](/docs/messaging/sns.md): Semantic Conventions for _AWS SNS_. diff --git a/docs/database/README.md b/docs/db/README.md similarity index 98% rename from docs/database/README.md rename to docs/db/README.md index 4dd6c14d0e..14ea3cd282 100644 --- a/docs/database/README.md +++ b/docs/db/README.md @@ -1,5 +1,6 @@ # Semantic conventions for database calls and systems diff --git a/docs/database/cassandra.md b/docs/db/cassandra.md similarity index 97% rename from docs/database/cassandra.md rename to docs/db/cassandra.md index 40490e862b..d46b647cf3 100644 --- a/docs/database/cassandra.md +++ b/docs/db/cassandra.md @@ -1,5 +1,6 @@ # Semantic conventions for Cassandra client operations @@ -24,11 +25,11 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). `db.system.name` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. @@ -111,13 +112,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[15] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[15] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/cosmosdb.md b/docs/db/cosmosdb.md similarity index 98% rename from docs/database/cosmosdb.md rename to docs/db/cosmosdb.md index b287e5e3c6..16d987fdb5 100644 --- a/docs/database/cosmosdb.md +++ b/docs/db/cosmosdb.md @@ -1,5 +1,6 @@ # Semantic conventions for Microsoft Azure Cosmos DB client operations @@ -30,14 +31,14 @@ extend and override the [Database Semantic Conventions](README.md). **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Cosmos DB instrumentations include call-level spans that represent logical database calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Cosmos DB instrumentations include call-level spans that represent logical database calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). Semantic conventions described in this document apply to the call-level spans only. `db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. @@ -211,7 +212,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9] `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`. -**[10] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[10] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. @@ -316,7 +317,7 @@ The following metrics provide insights into Azure Cosmos DB client operation per This metric is [required][MetricRequired]. -It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration](/docs/database/database-metrics.md#metric-dbclientoperationduration) definition. +It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration](/docs/db/database-metrics.md#metric-dbclientoperationduration) definition. Refer [azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclientoperationrequest_charge) metrics for dimensions. @@ -324,7 +325,7 @@ Refer [azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclie This metric is [required][MetricRequired]. -It captures the number of items returned by a query or feed operation in Azure Cosmos DB. It helps identify response sizes that may contribute to high latency, increased memory/CPU usage, or network call failures. This metric follows the common [`db.client.response.returned_rows`](/docs/database/database-metrics.md#metric-dbclientresponsereturned_rows) definition. +It captures the number of items returned by a query or feed operation in Azure Cosmos DB. It helps identify response sizes that may contribute to high latency, increased memory/CPU usage, or network call failures. This metric follows the common [`db.client.response.returned_rows`](/docs/db/database-metrics.md#metric-dbclientresponsereturned_rows) definition. Refer [azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclientoperationrequest_charge) metrics for dimensions. diff --git a/docs/database/couchdb.md b/docs/db/couchdb.md similarity index 97% rename from docs/database/couchdb.md rename to docs/db/couchdb.md index d33e8209bf..92ee1b1332 100644 --- a/docs/database/couchdb.md +++ b/docs/db/couchdb.md @@ -1,5 +1,6 @@ # Semantic conventions for CouchDB client operations @@ -30,11 +31,11 @@ The following table outlines the span attributes applicable to CouchDB. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). `db.system.name` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. diff --git a/docs/database/database-metrics.md b/docs/db/database-metrics.md similarity index 99% rename from docs/database/database-metrics.md rename to docs/db/database-metrics.md index 3d246691f3..b41a2d639a 100644 --- a/docs/database/database-metrics.md +++ b/docs/db/database-metrics.md @@ -1,5 +1,6 @@ # Semantic conventions for database client metrics @@ -152,7 +153,7 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. **[14] `db.stored_procedure.name`:** If operation applies to a specific stored procedure. @@ -168,7 +169,7 @@ If a database operation involved multiple network calls (for example retries), t **[17] `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. -**[18] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[18] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. @@ -338,7 +339,7 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. **[14] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. @@ -346,7 +347,7 @@ If a database operation involved multiple network calls (for example retries), t **[15] `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. -**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/database-spans.md b/docs/db/database-spans.md similarity index 98% rename from docs/database/database-spans.md rename to docs/db/database-spans.md index 4bdb22f8ca..876bde71c4 100644 --- a/docs/database/database-spans.md +++ b/docs/db/database-spans.md @@ -1,5 +1,6 @@ # Semantic conventions for database client spans @@ -96,7 +97,7 @@ it is RECOMMENDED to instrument the higher-level convenience APIs. These often allow setting `db.operation.*` attributes, which usually are not readily available at the generic query level. -**Span name** is covered in the [Name](/docs/database/database-spans.md#name) section. +**Span name** is covered in the [Name](/docs/db/database-spans.md#name) section. **Span kind** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing in-memory database calls. @@ -188,13 +189,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/dynamodb.md b/docs/db/dynamodb.md similarity index 99% rename from docs/database/dynamodb.md rename to docs/db/dynamodb.md index adf2383c67..ba39c89661 100644 --- a/docs/database/dynamodb.md +++ b/docs/db/dynamodb.md @@ -1,5 +1,6 @@ # Semantic conventions for AWS DynamoDB client operations @@ -27,7 +28,7 @@ linkTitle: DynamoDB The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) extend and override the general -[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) and [Database Semantic Conventions](/docs/database/README.md). +[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) and [Database Semantic Conventions](/docs/db/README.md). ## Spans diff --git a/docs/database/elasticsearch.md b/docs/db/elasticsearch.md similarity index 98% rename from docs/database/elasticsearch.md rename to docs/db/elasticsearch.md index 1ea48cd7fb..914fb858af 100644 --- a/docs/database/elasticsearch.md +++ b/docs/db/elasticsearch.md @@ -1,5 +1,6 @@ # Semantic conventions for Elasticsearch client operations @@ -25,11 +26,11 @@ The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). `db.system.name` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. **Span kind** SHOULD be `CLIENT`. @@ -117,7 +118,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[12] `db.query.text`:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. -**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/hbase.md b/docs/db/hbase.md similarity index 97% rename from docs/database/hbase.md rename to docs/db/hbase.md index 3bab6e87bf..95634f982a 100644 --- a/docs/database/hbase.md +++ b/docs/db/hbase.md @@ -1,5 +1,6 @@ # Semantic conventions for HBase client operations @@ -24,11 +25,11 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). `db.system.name` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. diff --git a/docs/database/mariadb.md b/docs/db/mariadb.md similarity index 97% rename from docs/database/mariadb.md rename to docs/db/mariadb.md index 6fcff6b09d..0675e3b7c4 100644 --- a/docs/database/mariadb.md +++ b/docs/db/mariadb.md @@ -1,5 +1,6 @@ # Semantic conventions for MariaDB client operations @@ -22,7 +23,7 @@ linkTitle: MariaDB **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/README.md). +Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/README.md). `db.system.name` MUST be set to `"mariadb"` and SHOULD be provided **at span creation time**. @@ -89,13 +90,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/mongodb.md b/docs/db/mongodb.md similarity index 97% rename from docs/database/mongodb.md rename to docs/db/mongodb.md index bb11cef544..ac5bb71874 100644 --- a/docs/database/mongodb.md +++ b/docs/db/mongodb.md @@ -1,5 +1,6 @@ # Semantic conventions for MongoDB client operations @@ -25,10 +26,10 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). `db.system.name` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. diff --git a/docs/database/mysql.md b/docs/db/mysql.md similarity index 97% rename from docs/database/mysql.md rename to docs/db/mysql.md index 93b755b78e..1eab581e7f 100644 --- a/docs/database/mysql.md +++ b/docs/db/mysql.md @@ -1,5 +1,6 @@ # Semantic conventions for MySQL client operations @@ -89,13 +90,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/oracledb.md b/docs/db/oracledb.md similarity index 93% rename from docs/database/oracledb.md rename to docs/db/oracledb.md index 22da088195..8f9b8d363c 100644 --- a/docs/database/oracledb.md +++ b/docs/db/oracledb.md @@ -1,5 +1,6 @@ # Semantic conventions for Oracle Database @@ -88,12 +89,12 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[13] `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.query.parameter.`](../registry/attributes/db.md)). +**[13] `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`](/docs/db/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.query.parameter.`](../registry/attributes/db.md)). -**[14] `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. +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. **[15] `db.stored_procedure.name`:** If operation applies to a specific stored procedure. diff --git a/docs/database/postgresql.md b/docs/db/postgresql.md similarity index 97% rename from docs/database/postgresql.md rename to docs/db/postgresql.md index be994e988b..420a4bea7c 100644 --- a/docs/database/postgresql.md +++ b/docs/db/postgresql.md @@ -1,5 +1,6 @@ # Semantic conventions for PostgreSQL client operations @@ -97,13 +98,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/redis.md b/docs/db/redis.md similarity index 97% rename from docs/database/redis.md rename to docs/db/redis.md index 4a48878142..3c63177e81 100644 --- a/docs/database/redis.md +++ b/docs/db/redis.md @@ -1,5 +1,6 @@ # Semantic conventions for Redis client operations @@ -17,11 +18,11 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the **Status:** ![Development](https://img.shields.io/badge/-development-blue) -Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). +Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). `db.system.name` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up looking confusing. @@ -71,7 +72,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8] `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`. **[9] `db.query.text`:** Query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. -See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). The value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 ? field2 ?"` would be a suitable value for `db.query.text`. **[10] `db.stored_procedure.name`:** See [FCALL](https://redis.io/docs/latest/commands/fcall/) and [EVALSHA](https://redis.io/docs/latest/commands/evalsha/). diff --git a/docs/database/sql-server.md b/docs/db/sql-server.md similarity index 98% rename from docs/database/sql-server.md rename to docs/db/sql-server.md index 91afc66472..9911161107 100644 --- a/docs/database/sql-server.md +++ b/docs/db/sql-server.md @@ -1,5 +1,6 @@ # Semantic conventions for Microsoft SQL Server client operations @@ -96,13 +97,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/database/sql.md b/docs/db/sql.md similarity index 96% rename from docs/database/sql.md rename to docs/db/sql.md index 6aa241e43e..ba9956117a 100644 --- a/docs/database/sql.md +++ b/docs/db/sql.md @@ -1,5 +1,6 @@ # Semantic conventions for SQL databases client operations @@ -15,10 +16,10 @@ linkTitle: SQL **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. +The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/db/database-spans.md) apply to SQL databases. The following database systems (defined in the -[`db.system.name`](/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) +[`db.system.name`](/docs/db/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: - `actian.ingres` @@ -41,7 +42,7 @@ are known to use SQL as their primary query language: Many other database systems support SQL and can be accessed via generic database driver such as JDBC or ODBC. Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic conventions. -**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +**Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. @@ -146,13 +147,13 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). -**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/docs/general/attribute-requirement-level.md b/docs/general/attribute-requirement-level.md index 4c971907bd..074027d1be 100644 --- a/docs/general/attribute-requirement-level.md +++ b/docs/general/attribute-requirement-level.md @@ -38,7 +38,7 @@ requirement level from the referred semantic convention applies. -For example, [Database semantic convention](../database/README.md) references +For example, [Database semantic convention](/docs/db/README.md) references `network.transport` attribute defined in [General attributes](./README.md) with `Conditionally Required` level on it. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 23900d88d3..5231dbbb8d 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -20,7 +20,7 @@ aliases: [metrics-general] The following semantic conventions surrounding metrics are defined: * **[General Guidelines](#general-guidelines): General metrics guidelines.** -* [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics. +* [Database](/docs/db/database-metrics.md): For SQL and NoSQL client metrics. * [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) metrics. * [GenAI](/docs/gen-ai/gen-ai-metrics.md): For Generative AI metrics. * [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics. diff --git a/docs/general/trace.md b/docs/general/trace.md index b60a9f6f69..e49ba799b0 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -24,7 +24,7 @@ The following semantic conventions for spans are defined: * [Compatibility](trace-compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer. * [CloudEvents](/docs/cloudevents/README.md): Semantic Conventions for the CloudEvents spans. * [Cloud Providers](/docs/cloud-providers/README.md): Semantic Conventions for cloud providers spans. -* [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. +* [Database](/docs/db/database-spans.md): For SQL and NoSQL client call spans. * [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. * [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. * [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. diff --git a/docs/how-to-write-conventions/README.md b/docs/how-to-write-conventions/README.md index e7bf79e006..39bce32492 100644 --- a/docs/how-to-write-conventions/README.md +++ b/docs/how-to-write-conventions/README.md @@ -170,7 +170,7 @@ For example, `db.system.name` contains database names like `mongodb` or `mysql`. System identifier enums help differentiate telemetry signals. MongoDB and MySQL both follow general database conventions, but populate attributes like `db.collection.name` differently and have system-specific attributes. Each system has its own span definitions and documentation. -See [MongoDB](/docs/database/mongodb.md) and [MySQL](/docs/database/mysql.md) as examples +See [MongoDB](/docs/db/mongodb.md) and [MySQL](/docs/db/mysql.md) as examples and check out [system-specific naming](../general/naming.md#system-specific-attributes) for naming guidance. diff --git a/docs/how-to-write-conventions/t-shaped-signals.md b/docs/how-to-write-conventions/t-shaped-signals.md index ff6eb287c8..a35d43649b 100644 --- a/docs/how-to-write-conventions/t-shaped-signals.md +++ b/docs/how-to-write-conventions/t-shaped-signals.md @@ -53,6 +53,6 @@ for a particular domain first. After providing a baseline set of signals for that domain, then explore deeper integrations that may be vendor or implementation specific. -For example, see [Database semantic conventions](/docs/database/README.md) where +For example, see [Database semantic conventions](/docs/db/README.md) where there is general guidance for spans about communicating with a database, and additionally there is database-specific guidance as an extension of the general. diff --git a/docs/registry/attributes/db.md b/docs/registry/attributes/db.md index a98f57e3c3..e328ad980f 100644 --- a/docs/registry/attributes/db.md +++ b/docs/registry/attributes/db.md @@ -93,10 +93,10 @@ 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) +[Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. -**[8] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +**[8] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/db/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. Parameterized query text SHOULD NOT be sanitized. 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. diff --git a/model/database/common.yaml b/model/db/common.yaml similarity index 100% rename from model/database/common.yaml rename to model/db/common.yaml diff --git a/model/database/deprecated/metrics-deprecated.yaml b/model/db/deprecated/metrics-deprecated.yaml similarity index 100% rename from model/database/deprecated/metrics-deprecated.yaml rename to model/db/deprecated/metrics-deprecated.yaml diff --git a/model/database/deprecated/registry-deprecated.yaml b/model/db/deprecated/registry-deprecated.yaml similarity index 100% rename from model/database/deprecated/registry-deprecated.yaml rename to model/db/deprecated/registry-deprecated.yaml diff --git a/model/database/metrics.yaml b/model/db/metrics.yaml similarity index 100% rename from model/database/metrics.yaml rename to model/db/metrics.yaml diff --git a/model/database/registry.yaml b/model/db/registry.yaml similarity index 98% rename from model/database/registry.yaml rename to model/db/registry.yaml index e3da7104c8..a115c7897b 100644 --- a/model/database/registry.yaml +++ b/model/db/registry.yaml @@ -63,7 +63,7 @@ groups: brief: > The database query being executed. note: > - For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). + For sanitization see [Sanitization of `db.query.text`](/docs/db/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 @@ -118,7 +118,7 @@ groups: 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](/docs/database/database-spans.md#generating-a-summary-of-the-query) + [Generating query summary](/docs/db/database-spans.md#generating-a-summary-of-the-query) section. examples: [ diff --git a/model/database/spans.yaml b/model/db/spans.yaml similarity index 96% rename from model/database/spans.yaml rename to model/db/spans.yaml index c99e616fbb..4593f3ddc4 100644 --- a/model/database/spans.yaml +++ b/model/db/spans.yaml @@ -36,7 +36,7 @@ groups: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. - See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). + See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, @@ -67,7 +67,7 @@ groups: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. - See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). + See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, @@ -122,7 +122,7 @@ groups: These often allow setting `db.operation.*` attributes, which usually are not readily available at the generic query level. - **Span name** is covered in the [Name](/docs/database/database-spans.md#name) section. + **Span name** is covered in the [Name](/docs/db/database-spans.md#name) section. **Span kind** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing in-memory database calls. @@ -259,7 +259,7 @@ groups: extends: span.db.sql.client span_kind: client brief: > - Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/README.md). + Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/README.md). note: > `db.system.name` MUST be set to `"mariadb"` and SHOULD be provided **at span creation time**. attributes: @@ -299,11 +299,11 @@ groups: stability: development extends: trace.db.common.query_and_collection brief: > - Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: | `db.system.name` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) attributes: - ref: db.namespace sampling_relevant: true @@ -346,11 +346,11 @@ groups: stability: development extends: trace.db.common.minimal brief: > - Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: | `db.system.name` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) attributes: - ref: db.namespace sampling_relevant: true @@ -388,11 +388,11 @@ groups: stability: development extends: trace.db.common.minimal brief: > - Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: | `db.system.name` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) attributes: - ref: db.operation.name sampling_relevant: true @@ -427,11 +427,11 @@ groups: span_kind: client extends: trace.db.common.minimal brief: > - Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: | `db.system.name` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up looking confusing. attributes: @@ -474,7 +474,7 @@ groups: Query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. - See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). + See [Sanitization of `db.query.text`](/docs/db/database-spans.md#sanitization-of-dbquerytext). The value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 ? field2 ?"` would be a suitable value for `db.query.text`. @@ -513,11 +513,11 @@ groups: span_kind: client extends: trace.db.common.minimal brief: > - Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: > `db.system.name` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) attributes: - ref: db.operation.name sampling_relevant: true @@ -557,11 +557,11 @@ groups: span_kind: client extends: trace.db.common.minimal brief: > - Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: | `db.system.name` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. attributes: - ref: http.request.method @@ -638,10 +638,10 @@ groups: stability: stable extends: trace.db.common.query brief: > - The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. + The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/db/database-spans.md) apply to SQL databases. note: | The following database systems (defined in the - [`db.system.name`](/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) + [`db.system.name`](/docs/db/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: - `actian.ingres` @@ -664,7 +664,7 @@ groups: Many other database systems support SQL and can be accessed via generic database driver such as JDBC or ODBC. Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic conventions. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) attributes: - ref: db.namespace brief: > @@ -761,14 +761,14 @@ groups: extends: trace.db.common.minimal brief: > Cosmos DB instrumentations include call-level spans that represent logical database - calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/db/database-spans.md). note: | Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). Semantic conventions described in this document apply to the call-level spans only. `db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + **Span name** SHOULD follow the general [database span name convention](/docs/db/database-spans.md#name) attributes: - ref: azure.client.id - ref: user_agent.original @@ -1008,12 +1008,12 @@ groups: 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). + in the query text. See [Sanitization of `db.query.text`](/docs/db/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.query.parameter.`](../registry/attributes/db.md)). note: > - For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + For sanitization see [Sanitization of `db.query.text`](/docs/db/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"]