open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Moved database semantic conventions (#144)

This commit is contained in:
Alexander Wert 2023-07-01 16:27:27 +02:00 committed by GitHub
parent 2d1ea6bb64
commit 86dacb9a62
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 742 additions and 482 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
semantic_conventions/trace/database.yaml
View File

@ -279,6 +279,12 @@ groups:
brief: >
Call-level attributes for Cassandra
attributes:
- ref: db.name
tag: call-level-tech-specific-cassandra
brief: >
The keyspace name in Cassandra.
examples: ["mykeyspace"]
note: For Cassandra the `db.name` should be set to the Cassandra keyspace name.
- id: page_size
type: int
tag: call-level-tech-specific-cassandra
@ -350,6 +356,39 @@ groups:
The data center of the coordinating node for a query.
examples: 'us-west-2'
- id: db.hbase
prefix: db.hbase
type: span
extends: db
brief: >
Call-level attributes for HBase
attributes:
- ref: db.name
tag: call-level-tech-specific
brief: >
The HBase namespace.
examples: ['mynamespace']
note: For HBase the `db.name` should be set to the HBase namespace.
- id: db.couchdb
prefix: db.couchdb
type: span
extends: db
brief: >
Call-level attributes for CouchDB
attributes:
- ref: db.operation
tag: call-level-tech-specific
brief: >
The HTTP method + the target REST route.
examples: ['GET /{db}/{docid}']
note: >
In **CouchDB**, `db.operation` should be set to the HTTP method +
the target REST route according to the API reference documentation.
For example, when retrieving a document, `db.operation` would be set to
(literally, i.e., without replacing the placeholders with concrete values):
[`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid).
- id: db.redis
prefix: db.redis
type: span
@ -366,7 +405,14 @@ groups:
The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer.
To be used instead of the generic `db.name` attribute.
examples: [0, 1, 15]
- ref: db.statement
tag: call-level-tech-specific
brief: >
The full syntax of the Redis CLI command.
examples: ["HMSET myhash field1 'Hello' field2 'World'"]
note: >
For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI.
If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`.
- id: db.mongodb
prefix: db.mongodb
type: span

1
specification/README.md
View File

@ -8,6 +8,7 @@ Semantic Conventions are defined for the following areas:
* [General](general/README.md): General Semantic Conventions.
* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
* [Database](database/README.md): Semantic Conventions for database operations.
* *Other areas can be found in the signal specific Semantic Conventions below*
Semantic Conventions by signals:

11
specification/cloud-providers/README.md Normal file
View File

@ -0,0 +1,11 @@
# Semantic conventions for cloud providers
**Status**: [Experimental][DocumentStatus]
This document defines semantic conventions for cloud provider SDK spans, metrics and logs.
Semantic conventions exist for the following cloud provider SDKs:
* [AWS SDK](aws-sdk.md): Semantic Conventions for the *AWS SDK*.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

42
specification/cloud-providers/aws-sdk.md Normal file
View File

@ -0,0 +1,42 @@
# Semantic conventions for AWS SDK
**Status**: [Experimental][DocumentStatus]
This document defines semantic conventions to apply when instrumenting the AWS SDK. They map request or response
parameters in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based
on feedback from AWS users of tracing and will continue to increase as new interesting conventions
are found.
Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs.
## Context Propagation
See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation).
## Common Attributes
The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`,
`S3.ListBuckets`. This is equivalent to concatenating `rpc.service` and `rpc.method` with `.` and consistent
with the naming guidelines for RPC client spans.
<!-- semconv aws -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended |
| [`rpc.method`](../trace/semantic_conventions/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended |
| [`rpc.service`](../trace/semantic_conventions/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended |
| [`rpc.system`](../trace/semantic_conventions/rpc.md) | string | The value `aws-api`. | `aws-api` | Required |
**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
<!-- endsemconv -->
## AWS service specific attributes
The following Semantic Conventions extend the general AWS SDK attributes for specific AWS services:
* [AWS DynamoDB](/specification/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
* [AWS S3](/specification/object-stores/s3.md): Semantic Conventions for *AWS S3*.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

27
specification/database/README.md Normal file
View File

@ -0,0 +1,27 @@
# Semantic conventions for database calls and systems
**Status**: [Experimental][DocumentStatus]
This document defines semantic conventions for database client spans as well as
database metrics and logs.
Semantic conventions for database operations are defined for the following signals:
* [DB Spans](database-spans.md): Semantic Conventions for database client *spans*.
* [DB Metrics](database-metrics.md): Semantic Conventions for database operation *metrics*.
Technology specific semantic conventions are defined for the following databases:
* [AWS DynamoDB](dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
* [Cassandra](cassandra.md): Semantic Conventions for *Cassandra*.
* [Cosmos DB](cosmosdb.md): Semantic Conventions for *Microsoft Cosmos DB*.
* [CouchDB](couchdb.md): Semantic Conventions for *CouchDB*.
* [Elasticsearch](elasticsearch.md): Semantic Conventions for *Elasticsearch*.
* [GraphQL](graphql.md): Semantic Conventions for *GraphQL Server*.
* [HBase](hbase.md): Semantic Conventions for *HBase*.
* [MongoDB](mongodb.md): Semantic Conventions for *MongoDB*.
* [MSSQL](mssql.md): Semantic Conventions for *MSSQL*.
* [Redis](redis.md): Semantic Conventions for *Redis*.
* [SQL](sql.md): Semantic Conventions for *SQL* databases.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

46
specification/database/cassandra.md Normal file
View File

@ -0,0 +1,46 @@
# Semantic Conventions for Cassandra
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
`db.system` MUST be set to `"cassandra"`.
## Call-level attributes
<!-- semconv db.cassandra(tag=call-level-tech-specific-cassandra) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended |
| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | Recommended |
| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended |
| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended |
| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | Recommended |
| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended |
| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended |
| [`db.name`](database-spans.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. |
**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
**[2]:** For Cassandra the `db.name` should be set to the Cassandra keyspace name.
`db.cassandra.consistency_level` MUST be one of the following:
| Value | Description |
|---|---|
| `all` | all |
| `each_quorum` | each_quorum |
| `quorum` | quorum |
| `local_quorum` | local_quorum |
| `one` | one |
| `two` | two |
| `three` | three |
| `local_one` | local_one |
| `any` | any |
| `serial` | serial |
| `local_serial` | local_serial |
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

89
specification/database/cosmosdb.md Normal file
View File

@ -0,0 +1,89 @@
# Semantic Conventions for Microsoft Cosmos DB
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/)
extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
## Call-level attributes
`db.system` MUST be set to `"cosmosdb"`.
Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created.
<!-- semconv db.cosmosdb -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended |
| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] |
| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) |
| `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available |
| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | Recommended |
| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received |
| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] |
| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available |
| `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | Recommended |
**[1]:** when performing one of the operations in this list
**[2]:** when response was received and contained sub-code.
**[3]:** The user-agent value is generated by SDK which is a combination of<br> `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br> `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br> `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br> `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br> `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br> `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br> `failover_information` : Generated key to determine if region failover enabled.
Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
Default value is "NS".
`db.cosmosdb.operation_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 |
|---|---|
| `Invalid` | invalid |
| `Create` | create |
| `Patch` | patch |
| `Read` | read |
| `ReadFeed` | read_feed |
| `Delete` | delete |
| `Replace` | replace |
| `Execute` | execute |
| `Query` | query |
| `Head` | head |
| `HeadFeed` | head_feed |
| `Upsert` | upsert |
| `Batch` | batch |
| `QueryPlan` | query_plan |
| `ExecuteJavaScript` | execute_javascript |
`db.cosmosdb.connection_mode` MUST be one of the following:
| Value | Description |
|---|---|
| `gateway` | Gateway (HTTP) connections mode |
| `direct` | Direct connection. |
<!-- endsemconv -->
In addition to Cosmos DB attributes, all spans include
`az.namespace` attribute representing Azure Resource Provider namespace that MUST be equal to `Microsoft.DocumentDB`.
## Example
| Key | Value |
|:-------------------------------------| :------------------- |
| Span name | `"ReadItemsAsync"` |
| `kind` | `"internal"` |
| `az.namespace` | `"Microsoft.DocumentDB"` |
| `db.system` | `"cosmosdb"` |
| `db.name` | `"database name"` |
| `db.operation` | `"ReadItemsAsync"` |
| `server.address` | `"account.documents.azure.com"` |
| `db.cosmosdb.client_id` | `3ba4827d-4422-483f-b59f-85b74211c11d` |
| `db.cosmosdb.operation_type` | `Read` |
| `user_agent.original` | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` |
| `db.cosmosdb.connection_mode` | `"Direct"` |
| `db.cosmosdb.container` | `"container name"` |
| `db.cosmosdb.request_content_length` | `20` |
| `db.cosmosdb.status_code` | `201` |
| `db.cosmosdb.sub_status_code` | `0` |
| `db.cosmosdb.request_charge` | `7.43` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

21
specification/database/couchdb.md Normal file
View File

@ -0,0 +1,21 @@
# Semantic Conventions for CouchDB
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
`db.system` MUST be set to `"couchdb"`.
## Call-level attributes
<!-- semconv db.couchdb(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`db.operation`](database-spans.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | Conditionally Required: If `db.statement` is not applicable. |
**[1]:** In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid).
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

2
specification/metrics/semantic_conventions/database-metrics.md → specification/database/database-metrics.md
View File

@ -58,6 +58,6 @@ Below is a table of the attributes that MUST be included on all connection pool
| Name | Type | Description | Examples | Requirement Level |
|-------------|--------|------------------------------------------------------------------------------|----------------|-------------------|
| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used. | `myDataSource` | Required |
| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

189
specification/database/database-spans.md Normal file
View File

@ -0,0 +1,189 @@
# Semantic conventions for database client calls
**Status**: [Experimental][DocumentStatus]
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc -->
- [Connection-level attributes](#connection-level-attributes)
* [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
- [Call-level attributes](#call-level-attributes)
- [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies)
<!-- tocstop -->
> **Warning**
> Existing Database instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md)
> (or prior):
>
> * SHOULD NOT change the version of the networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in Database instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which is a comma-separated list of values.
> The only values defined so far are:
> * `http` - emit the new, stable networking attributes,
> and stop emitting the old experimental networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable networking attributes,
> allowing for a seamless transition.
> * The default behavior (in the absence of one of these values) is to continue
> emitting whatever version of the old experimental networking attributes
> the instrumentation was emitting previously.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
**Span kind:** MUST always be `CLIENT`.
The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database.
It MAY be a stored procedure name (without arguments), DB statement without variable arguments, operation name, etc.
Since SQL statements may have very high cardinality even without arguments, SQL spans SHOULD be named the
following way, unless the statement is known to be of low cardinality:
`<db.operation> <db.name>.<db.sql.table>`, provided that `db.operation` and `db.sql.table` are available.
If `db.sql.table` is not available due to its semantics, the span SHOULD be named `<db.operation> <db.name>`.
It is not recommended to attempt any client-side parsing of `db.statement` just to get these properties,
they should only be used if the library being instrumented already provides them.
When it's otherwise impossible to get any meaningful span name, `db.name` or the tech-specific database name MAY be used.
## Connection-level attributes
These attributes will usually be the same for all operations performed over the same database connection.
Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all.
<!-- semconv db(tag=connection-level) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] |
| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
**[1]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* [`server.address`](../general/general-attributes.md)
* [`server.socket.address`](../general/general-attributes.md)
`db.system` 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 |
|---|---|
| `other_sql` | Some other SQL database. Fallback only. See notes. |
| `mssql` | Microsoft SQL Server |
| `mssqlcompact` | Microsoft SQL Server Compact |
| `mysql` | MySQL |
| `oracle` | Oracle Database |
| `db2` | IBM Db2 |
| `postgresql` | PostgreSQL |
| `redshift` | Amazon Redshift |
| `hive` | Apache Hive |
| `cloudscape` | Cloudscape |
| `hsqldb` | HyperSQL DataBase |
| `progress` | Progress Database |
| `maxdb` | SAP MaxDB |
| `hanadb` | SAP HANA |
| `ingres` | Ingres |
| `firstsql` | FirstSQL |
| `edb` | EnterpriseDB |
| `cache` | InterSystems Caché |
| `adabas` | Adabas (Adaptable Database System) |
| `firebird` | Firebird |
| `derby` | Apache Derby |
| `filemaker` | FileMaker |
| `informix` | Informix |
| `instantdb` | InstantDB |
| `interbase` | InterBase |
| `mariadb` | MariaDB |
| `netezza` | Netezza |
| `pervasive` | Pervasive PSQL |
| `pointbase` | PointBase |
| `sqlite` | SQLite |
| `sybase` | Sybase |
| `teradata` | Teradata |
| `vertica` | Vertica |
| `h2` | H2 |
| `coldfusion` | ColdFusion IMQ |
| `cassandra` | Apache Cassandra |
| `hbase` | Apache HBase |
| `mongodb` | MongoDB |
| `redis` | Redis |
| `couchbase` | Couchbase |
| `couchdb` | CouchDB |
| `cosmosdb` | Microsoft Azure Cosmos DB |
| `dynamodb` | Amazon DynamoDB |
| `neo4j` | Neo4j |
| `geode` | Apache Geode |
| `elasticsearch` | Elasticsearch |
| `memcached` | Memcached |
| `cockroachdb` | CockroachDB |
| `opensearch` | OpenSearch |
| `clickhouse` | ClickHouse |
| `spanner` | Cloud Spanner |
| `trino` | Trino |
<!-- endsemconv -->
### Notes and well-known identifiers for `db.system`
The list above is a non-exhaustive list of well-known identifiers to be specified for `db.system`.
If a value defined in this list applies to the DBMS to which the request is sent, this value MUST be used.
If no value defined in this list is suitable, a custom value MUST be provided.
This custom value MUST be the name of the DBMS in lowercase and without a version number to stay consistent with existing identifiers.
It is encouraged to open a PR towards this specification to add missing values to the list, especially when instrumentations for those missing databases are written.
This allows multiple instrumentations for the same database to be aligned and eases analyzing for backends.
The value `other_sql` is intended as a fallback and MUST only be used if the DBMS is known to be SQL-compliant but the concrete product is not known to the instrumentation.
If the concrete DBMS is known to the instrumentation, its specific identifier MUST be used.
Back ends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the `db.statement`.
When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below.
## Call-level attributes
These attributes may be different for each operation performed, even if the same connection is used for multiple operations.
Usually only one `db.name` will be used per connection though.
<!-- semconv db(tag=call-level,remove_constraints) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. |
| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [2] |
| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [3] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. |
**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name).
**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information.
**[3]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
<!-- endsemconv -->
## Semantic Conventions for specific database technologies
More specific Semantic Conventions are defined for the following database technologies:
* [AWS DynamoDB](dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
* [Cassandra](cassandra.md): Semantic Conventions for *Cassandra*.
* [Cosmos DB](cosmosdb.md): Semantic Conventions for *Microsoft Cosmos DB*.
* [CouchDB](couchdb.md): Semantic Conventions for *CouchDB*.
* [Elasticsearch](elasticsearch.md): Semantic Conventions for *Elasticsearch*.
* [GraphQL](graphql.md): Semantic Conventions for *GraphQL Server*.
* [HBase](hbase.md): Semantic Conventions for *HBase*.
* [MongoDB](mongodb.md): Semantic Conventions for *MongoDB*.
* [MSSQL](mssql.md): Semantic Conventions for *MSSQL*.
* [Redis](redis.md): Semantic Conventions for *Redis*.
* [SQL](sql.md): Semantic Conventions for *SQL* databases.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

125
specification/trace/semantic_conventions/instrumentation/aws-sdk.md → specification/database/dynamodb.md
View File

@ -1,50 +1,24 @@
# Semantic conventions for AWS SDK
# Semantic Conventions for AWS DynamoDB
**Status**: [Experimental][DocumentStatus]
This document defines semantic conventions to apply when instrumenting the AWS SDK. They map request or response
parameters in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based
on feedback from AWS users of tracing and will continue to increase as new interesting conventions
are found.
Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs.
## Context Propagation
See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation).
The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) extend and override the general
[AWS SDK Semantic Conventions](/specification/cloud-providers/aws-sdk.md)
that describe common AWS SDK attributes and the [Database Semantic Conventions](database-spans.md).
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
## Common Attributes
The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`,
`S3.ListBuckets`. This is equivalent to concatenating `rpc.service` and `rpc.method` with `.` and consistent
with the naming guidelines for RPC client spans.
<!-- semconv aws -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended |
| [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended |
| [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended |
| [`rpc.system`](../rpc.md) | string | The value `aws-api`. | `aws-api` | Required |
**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
<!-- endsemconv -->
## DynamoDB
### Common Attributes
These attributes are filled in for all DynamoDB request types.
<!-- semconv dynamodb.all -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`db.system`](../database.md) | string | The value `dynamodb`. | `dynamodb` | Required |
| [`db.system`](database-spans.md) | string | The value `dynamodb`. | `dynamodb` | Required |
<!-- endsemconv -->
### DynamoDB.BatchGetItem
## DynamoDB.BatchGetItem
<!-- semconv dynamodb.batchgetitem -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -53,7 +27,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended |
<!-- endsemconv -->
### DynamoDB.BatchWriteItem
## DynamoDB.BatchWriteItem
<!-- semconv dynamodb.batchwriteitem -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -63,7 +37,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended |
<!-- endsemconv -->
### DynamoDB.CreateTable
## DynamoDB.CreateTable
<!-- semconv dynamodb.createtable -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -77,7 +51,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.DeleteItem
## DynamoDB.DeleteItem
<!-- semconv dynamodb.deleteitem -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -87,7 +61,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.DeleteTable
## DynamoDB.DeleteTable
<!-- semconv dynamodb.deletetable -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -95,7 +69,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.DescribeTable
## DynamoDB.DescribeTable
<!-- semconv dynamodb.describetable -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -103,7 +77,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.GetItem
## DynamoDB.GetItem
<!-- semconv dynamodb.getitem -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -114,7 +88,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.ListTables
## DynamoDB.ListTables
<!-- semconv dynamodb.listtables -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -124,7 +98,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended |
<!-- endsemconv -->
### DynamoDB.PutItem
## DynamoDB.PutItem
<!-- semconv dynamodb.putitem -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -134,7 +108,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended |
<!-- endsemconv -->
### DynamoDB.Query
## DynamoDB.Query
<!-- semconv dynamodb.query -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -150,7 +124,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.Scan
## DynamoDB.Scan
<!-- semconv dynamodb.scan -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -169,7 +143,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.UpdateItem
## DynamoDB.UpdateItem
<!-- semconv dynamodb.updateitem -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -179,7 +153,7 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.UpdateTable
## DynamoDB.UpdateTable
<!-- semconv dynamodb.updatetable -->
| Attribute | Type | Description | Examples | Requirement Level |
@ -192,63 +166,4 @@ These attributes are filled in for all DynamoDB request types.
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
## S3
<!-- semconv aws.s3 -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | Recommended |
| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [2] | `someFile.yml` | Recommended |
| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [3] | `someFile.yml` | Recommended |
| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [4] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended |
| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [5] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended |
| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | `3456` | Recommended |
**[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
This applies to almost all S3 operations except `list-buckets`.
**[2]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
- [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html)
- [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)
- [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html)
- [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html)
- [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html)
- [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html)
- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
- [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html)
- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
**[3]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html).
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
**[4]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations.
This applies in particular to the following operations:
- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
**[5]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
The `delete` attribute corresponds to the `--delete` parameter of the
[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html).
**[6]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations.
The `part_number` attribute corresponds to the `--part-number` parameter of the
[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html).
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

12
specification/trace/semantic_conventions/instrumentation/elasticsearch.md → specification/database/elasticsearch.md
View File

@ -28,14 +28,16 @@ in order to map the path part values to their names.
## Span attributes
`db.system` MUST be set to `"elasticsearch"`.
<!-- semconv db.elasticsearch -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`db.operation`](../database.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required |
| [`db.statement`](../database.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] |
| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required |
| [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| [`server.address`](../../../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below |
| [`server.port`](../../../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended |
| [`server.address`](../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below |
| [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended |
| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required |
**[1]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
@ -76,3 +78,5 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
| `db.operation` | `"search"` |
| `url.full` | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"` |
| `db.elasticsearch.path_parts.index` | `"my-index-000001"` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

0
specification/trace/semantic_conventions/instrumentation/graphql.md → specification/database/graphql.md
View File

21
specification/database/hbase.md Normal file
View File

@ -0,0 +1,21 @@
# Semantic Conventions for HBase
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
`db.system` MUST be set to `"hbase"`.
## Call-level attributes
<!-- semconv db.hbase(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`db.name`](database-spans.md) | string | The HBase namespace. [1] | `mynamespace` | Conditionally Required: If applicable. |
**[1]:** For HBase the `db.name` should be set to the HBase namespace.
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

36
specification/database/mongodb.md Normal file
View File

@ -0,0 +1,36 @@
# Semantic Conventions for MongoDB
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
`db.system` MUST be set to `"mongodb"`.
## Call-level attributes
<!-- semconv db.mongodb(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required |
<!-- endsemconv -->
## Example
| Key | Value |
| :---------------------- | :----------------------------------------------------------- |
| Span name | `"products.findAndModify"` |
| `db.system` | `"mongodb"` |
| `db.connection_string` | not set |
| `db.user` | `"the_user"` |
| `server.address` | `"mongodb0.example.com"` |
| `server.socket.address` | `"192.0.2.14"` |
| `server.port` | `27017` |
| `network.transport` | `"IP.TCP"` |
| `db.name` | `"shopDb"` |
| `db.statement` | not set |
| `db.operation` | `"findAndModify"` |
| `db.mongodb.collection` | `"products"` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

22
specification/database/mssql.md Normal file
View File

@ -0,0 +1,22 @@
# Semantic Conventions for MSSQL
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for the [Microsoft SQL Server](https://www.microsoft.com/sql-server) extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
`db.system` MUST be set to `"mssql"`.
## Connection-level attributes
<!-- semconv db.mssql(tag=connection-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`db.jdbc.driver_classname`](database-spans.md) | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | Recommended |
| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | Recommended |
**[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard).
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

42
specification/database/redis.md Normal file
View File

@ -0,0 +1,42 @@
# Semantic Conventions for Redis
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
`db.system` MUST be set to `"redis"`.
## Call-level attributes
<!-- semconv db.redis(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: If other than the default database (`0`). |
| [`db.statement`](database-spans.md) | string | The full syntax of the Redis CLI command. [1] | `HMSET myhash field1 'Hello' field2 'World'` | Recommended: [2] |
**[1]:** For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`.
**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information.
<!-- endsemconv -->
## Example
In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out.
Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead.
| Key | Value |
|:--------------------------| :-------------------------------------------- |
| Span name | `"HMSET myhash"` |
| `db.system` | `"redis"` |
| `db.connection_string` | not set |
| `db.user` | not set |
| `server.socket.address` | `"/tmp/redis.sock"` |
| `network.transport` | `"Unix"` |
| `db.name` | not set |
| `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` |
| `db.operation` | not set |
| `db.redis.database_index` | `15` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

38
specification/database/sql.md Normal file
View File

@ -0,0 +1,38 @@
# Semantic Conventions for SQL databases
**Status**: [Experimental][DocumentStatus]
The SQL databases Semantic Conventions extend and override the [Database Semantic Conventions](database-spans.md)
that describe common database operations attributes in addition to the Semantic Conventions
described on this page.
## Call-level attributes
<!-- semconv db.sql(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `public.users`; `customers` | Recommended |
**[1]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
<!-- endsemconv -->
## Example
This is an example of attributes for a MySQL database span:
| Key | Value |
|:------------------------| :----------------------------------------------------------- |
| Span name | `"SELECT ShopDb.orders"` |
| `db.system` | `"mysql"` |
| `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` |
| `db.user` | `"billing_user"` |
| `server.address` | `"shopdb.example.com"` |
| `server.socket.address` | `"192.0.2.12"` |
| `server.port` | `3306` |
| `network.transport` | `"IP.TCP"` |
| `db.name` | `"ShopDb"` |
| `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` |
| `db.operation` | `"SELECT"` |
| `db.sql.table` | `"orders"` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

2
specification/general/metrics-general.md
View File

@ -21,7 +21,7 @@ The following semantic conventions surrounding metrics are defined:
* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics.
* [RPC](/specification/metrics/semantic_conventions/rpc-metrics.md): For RPC client and server metrics.
* [Database](/specification/metrics/semantic_conventions/database-metrics.md): For SQL and NoSQL client metrics.
* [Database](/specification/database/database-metrics.md): For SQL and NoSQL client metrics.
* [System](/specification/metrics/semantic_conventions/system-metrics.md): For standard system metrics.
* [Process](/specification/metrics/semantic_conventions/process-metrics.md): For standard process metrics.
* [Runtime Environment](/specification/metrics/semantic_conventions/runtime-environment-metrics.md): For runtime environment metrics.

5
specification/general/trace-general.md
View File

@ -17,7 +17,7 @@ The following semantic conventions for spans are defined:
* [General](general-attributes.md): General semantic attributes that may be used in describing different kinds of operations.
* [HTTP](/specification/http/http-spans.md): For HTTP client and server spans.
* [Database](/specification/trace/semantic_conventions/database.md): For SQL and NoSQL client call spans.
* [Database](/specification/database/database-spans.md): For SQL and NoSQL client call spans.
* [RPC/RMI](/specification/trace/semantic_conventions/rpc.md): For remote procedure call (e.g., gRPC) spans.
* [Messaging](/specification/trace/semantic_conventions/messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans.
* [FaaS](/specification/trace/semantic_conventions/faas.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans.
@ -28,8 +28,7 @@ The following semantic conventions for spans are defined:
The following library-specific semantic conventions are defined:
* [AWS Lambda](/specification/trace/semantic_conventions/instrumentation/aws-lambda.md): For AWS Lambda spans.
* [AWS SDK](/specification/trace/semantic_conventions/instrumentation/aws-sdk.md): For AWS SDK spans.
* [GraphQL](/specification/trace/semantic_conventions/instrumentation/graphql.md): For GraphQL spans.
* [AWS SDK](/specification/cloud-providers/aws-sdk.md): For AWS SDK spans.
Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md),
OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own

11
specification/object-stores/README.md Normal file
View File

@ -0,0 +1,11 @@
# Semantic conventions for Object Stores
**Status**: [Experimental, Feature-freeze][DocumentStatus]
This document defines semantic conventions for object store operations.
The following technology specific semantic conventions are defined for object stores:
* [AWS S3](s3.md): Semantic Conventions for *AWS S3*.
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

67
specification/object-stores/s3.md Normal file
View File

@ -0,0 +1,67 @@
# Semantic Conventions for AWS S3
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for AWS S3 extend the general
[AWS SDK Semantic Conventions](/specification/cloud-providers/aws-sdk.md)
that describe common AWS SDK attributes in addition to the Semantic Conventions
described on this page.
<!-- semconv aws.s3 -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | Recommended |
| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [2] | `someFile.yml` | Recommended |
| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [3] | `someFile.yml` | Recommended |
| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [4] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended |
| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [5] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended |
| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | `3456` | Recommended |
**[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
This applies to almost all S3 operations except `list-buckets`.
**[2]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
- [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html)
- [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)
- [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html)
- [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html)
- [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html)
- [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html)
- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
- [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html)
- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
**[3]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html).
This applies in particular to the following operations:
- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
**[4]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations.
This applies in particular to the following operations:
- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
**[5]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
The `delete` attribute corresponds to the `--delete` parameter of the
[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html).
**[6]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations.
The `part_number` attribute corresponds to the `--part-number` parameter of the
[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html).
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

367
specification/trace/semantic_conventions/database.md
View File

@ -1,367 +0,0 @@
# Semantic conventions for database client calls
**Status**: [Experimental][DocumentStatus]
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc -->
- [Connection-level attributes](#connection-level-attributes)
* [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
* [Connection-level attributes for specific technologies](#connection-level-attributes-for-specific-technologies)
- [Call-level attributes](#call-level-attributes)
* [Call-level attributes for specific technologies](#call-level-attributes-for-specific-technologies)
+ [Cassandra](#cassandra)
+ [Microsoft Azure Cosmos DB Attributes](#microsoft-azure-cosmos-db-attributes)
- [Examples](#examples)
* [MySQL](#mysql)
* [Redis](#redis)
* [MongoDB](#mongodb)
* [Microsoft Azure Cosmos DB](#microsoft-azure-cosmos-db)
<!-- tocstop -->
> **Warning**
> Existing Database instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md)
> (or prior):
>
> * SHOULD NOT change the version of the networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in Database instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which is a comma-separated list of values.
> The only values defined so far are:
> * `http` - emit the new, stable networking attributes,
> and stop emitting the old experimental networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable networking attributes,
> allowing for a seamless transition.
> * The default behavior (in the absence of one of these values) is to continue
> emitting whatever version of the old experimental networking attributes
> the instrumentation was emitting previously.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
**Span kind:** MUST always be `CLIENT`.
The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database.
It MAY be a stored procedure name (without arguments), DB statement without variable arguments, operation name, etc.
Since SQL statements may have very high cardinality even without arguments, SQL spans SHOULD be named the
following way, unless the statement is known to be of low cardinality:
`<db.operation> <db.name>.<db.sql.table>`, provided that `db.operation` and `db.sql.table` are available.
If `db.sql.table` is not available due to its semantics, the span SHOULD be named `<db.operation> <db.name>`.
It is not recommended to attempt any client-side parsing of `db.statement` just to get these properties,
they should only be used if the library being instrumented already provides them.
When it's otherwise impossible to get any meaningful span name, `db.name` or the tech-specific database name MAY be used.
## Connection-level attributes
These attributes will usually be the same for all operations performed over the same database connection.
Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all.
<!-- semconv db(tag=connection-level) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
| [`network.transport`](../../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../general/general-attributes.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](../../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] |
| [`server.socket.address`](../../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below |
| [`server.socket.port`](../../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
**[1]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* [`server.address`](../../general/general-attributes.md)
* [`server.socket.address`](../../general/general-attributes.md)
`db.system` 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 |
|---|---|
| `other_sql` | Some other SQL database. Fallback only. See notes. |
| `mssql` | Microsoft SQL Server |
| `mssqlcompact` | Microsoft SQL Server Compact |
| `mysql` | MySQL |
| `oracle` | Oracle Database |
| `db2` | IBM Db2 |
| `postgresql` | PostgreSQL |
| `redshift` | Amazon Redshift |
| `hive` | Apache Hive |
| `cloudscape` | Cloudscape |
| `hsqldb` | HyperSQL DataBase |
| `progress` | Progress Database |
| `maxdb` | SAP MaxDB |
| `hanadb` | SAP HANA |
| `ingres` | Ingres |
| `firstsql` | FirstSQL |
| `edb` | EnterpriseDB |
| `cache` | InterSystems Caché |
| `adabas` | Adabas (Adaptable Database System) |
| `firebird` | Firebird |
| `derby` | Apache Derby |
| `filemaker` | FileMaker |
| `informix` | Informix |
| `instantdb` | InstantDB |
| `interbase` | InterBase |
| `mariadb` | MariaDB |
| `netezza` | Netezza |
| `pervasive` | Pervasive PSQL |
| `pointbase` | PointBase |
| `sqlite` | SQLite |
| `sybase` | Sybase |
| `teradata` | Teradata |
| `vertica` | Vertica |
| `h2` | H2 |
| `coldfusion` | ColdFusion IMQ |
| `cassandra` | Apache Cassandra |
| `hbase` | Apache HBase |
| `mongodb` | MongoDB |
| `redis` | Redis |
| `couchbase` | Couchbase |
| `couchdb` | CouchDB |
| `cosmosdb` | Microsoft Azure Cosmos DB |
| `dynamodb` | Amazon DynamoDB |
| `neo4j` | Neo4j |
| `geode` | Apache Geode |
| `elasticsearch` | Elasticsearch |
| `memcached` | Memcached |
| `cockroachdb` | CockroachDB |
| `opensearch` | OpenSearch |
| `clickhouse` | ClickHouse |
| `spanner` | Cloud Spanner |
| `trino` | Trino |
<!-- endsemconv -->
### Notes and well-known identifiers for `db.system`
The list above is a non-exhaustive list of well-known identifiers to be specified for `db.system`.
If a value defined in this list applies to the DBMS to which the request is sent, this value MUST be used.
If no value defined in this list is suitable, a custom value MUST be provided.
This custom value MUST be the name of the DBMS in lowercase and without a version number to stay consistent with existing identifiers.
It is encouraged to open a PR towards this specification to add missing values to the list, especially when instrumentations for those missing databases are written.
This allows multiple instrumentations for the same database to be aligned and eases analyzing for backends.
The value `other_sql` is intended as a fallback and MUST only be used if the DBMS is known to be SQL-compliant but the concrete product is not known to the instrumentation.
If the concrete DBMS is known to the instrumentation, its specific identifier MUST be used.
Back ends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the `db.statement`.
When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below.
### Connection-level attributes for specific technologies
<!-- semconv db.mssql(tag=connection-level-tech-specific,remove_constraints) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.jdbc.driver_classname` | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | Recommended |
| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | Recommended |
**[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard).
<!-- endsemconv -->
## Call-level attributes
These attributes may be different for each operation performed, even if the same connection is used for multiple operations.
Usually only one `db.name` will be used per connection though.
<!-- semconv db(tag=call-level,remove_constraints) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. |
| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [2] |
| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [3] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. |
**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name).
**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information.
**[3]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
<!-- endsemconv -->
For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI.
If, for example, the [`HMSET` command][] is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`.
[`HMSET` command]: https://redis.io/commands/hmset
In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation.
For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`][CouchDB get doc].
In **Cassandra**, `db.name` SHOULD be set to the keyspace name.
In **HBase**, `db.name` SHOULD be set to the HBase namespace.
[CouchDB get doc]: http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid
### Call-level attributes for specific technologies
<!-- semconv db.tech(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: If other than the default database (`0`). |
| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required |
| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `public.users`; `customers` | Recommended |
**[1]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
<!-- endsemconv -->
#### Cassandra
Separated for clarity.
<!-- semconv db.tech(tag=call-level-tech-specific-cassandra) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended |
| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | Recommended |
| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended |
| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended |
| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | Recommended |
| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended |
| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended |
**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
<!-- endsemconv -->
#### Microsoft Azure Cosmos DB Attributes
Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created.
<!-- semconv db.cosmosdb -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended |
| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] |
| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) |
| `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available |
| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | Recommended |
| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received |
| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] |
| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available |
| `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | Recommended |
**[1]:** when performing one of the operations in this list
**[2]:** when response was received and contained sub-code.
**[3]:** The user-agent value is generated by SDK which is a combination of<br> `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br> `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br> `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br> `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br> `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br> `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br> `failover_information` : Generated key to determine if region failover enabled.
Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
Default value is "NS".
`db.cosmosdb.operation_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 |
|---|---|
| `Invalid` | invalid |
| `Create` | create |
| `Patch` | patch |
| `Read` | read |
| `ReadFeed` | read_feed |
| `Delete` | delete |
| `Replace` | replace |
| `Execute` | execute |
| `Query` | query |
| `Head` | head |
| `HeadFeed` | head_feed |
| `Upsert` | upsert |
| `Batch` | batch |
| `QueryPlan` | query_plan |
| `ExecuteJavaScript` | execute_javascript |
`db.cosmosdb.connection_mode` MUST be one of the following:
| Value | Description |
|---|---|
| `gateway` | Gateway (HTTP) connections mode |
| `direct` | Direct connection. |
<!-- endsemconv -->
In addition to Cosmos DB attributes, all spans include
`az.namespace` attribute representing Azure Resource Provider namespace that MUST be equal to `Microsoft.DocumentDB`.
## Examples
### MySQL
| Key | Value |
|:------------------------| :----------------------------------------------------------- |
| Span name | `"SELECT ShopDb.orders"` |
| `db.system` | `"mysql"` |
| `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` |
| `db.user` | `"billing_user"` |
| `server.address` | `"shopdb.example.com"` |
| `server.socket.address` | `"192.0.2.12"` |
| `server.port` | `3306` |
| `network.transport` | `"IP.TCP"` |
| `db.name` | `"ShopDb"` |
| `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` |
| `db.operation` | `"SELECT"` |
| `db.sql.table` | `"orders"` |
### Redis
In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out.
Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead.
| Key | Value |
|:--------------------------| :-------------------------------------------- |
| Span name | `"HMSET myhash"` |
| `db.system` | `"redis"` |
| `db.connection_string` | not set |
| `db.user` | not set |
| `server.socket.address` | `"/tmp/redis.sock"` |
| `network.transport` | `"Unix"` |
| `db.name` | not set |
| `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` |
| `db.operation` | not set |
| `db.redis.database_index` | `15` |
### MongoDB
| Key | Value |
| :---------------------- | :----------------------------------------------------------- |
| Span name | `"products.findAndModify"` |
| `db.system` | `"mongodb"` |
| `db.connection_string` | not set |
| `db.user` | `"the_user"` |
| `server.address` | `"mongodb0.example.com"` |
| `server.socket.address` | `"192.0.2.14"` |
| `server.port` | `27017` |
| `network.transport` | `"IP.TCP"` |
| `db.name` | `"shopDb"` |
| `db.statement` | not set |
| `db.operation` | `"findAndModify"` |
| `db.mongodb.collection` | `"products"` |
### Microsoft Azure Cosmos DB
| Key | Value |
|:-------------------------------------| :------------------- |
| Span name | `"ReadItemsAsync"` |
| `kind` | `"internal"` |
| `az.namespace` | `"Microsoft.DocumentDB"` |
| `db.system` | `"cosmosdb"` |
| `db.name` | `"database name"` |
| `db.operation` | `"ReadItemsAsync"` |
| `server.address` | `"account.documents.azure.com"` |
| `db.cosmosdb.client_id` | `3ba4827d-4422-483f-b59f-85b74211c11d` |
| `db.cosmosdb.operation_type` | `Read` |
| `user_agent.original` | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` |
| `db.cosmosdb.connection_mode` | `"Direct"` |
| `db.cosmosdb.container` | `"container name"` |
| `db.cosmosdb.request_content_length` | `20` |
| `db.cosmosdb.status_code` | `201` |
| `db.cosmosdb.sub_status_code` | `0` |
| `db.cosmosdb.request_charge` | `7.43` |
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md