Moved and restructured database and object-store semconv to a databas…

…e folder structure Signed-off-by: Alexander Wert <alexander.wert@elastic.co>
open-telemetry · Jun 29, 2023 · 33f7f76 · 33f7f76
1 parent 2aa586f
commit 33f7f76
Show file tree

Hide file tree

Showing 22 changed files with 732 additions and 478 deletions.
diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
@@ -349,6 +349,45 @@ groups:
         brief: >
           The data center of the coordinating node for a query.
         examples: 'us-west-2'
+      - 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: 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
@@ -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

diff --git a/specification/README.md b/specification/README.md
@@ -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:

diff --git a/specification/cloud-providers/README.md b/specification/cloud-providers/README.md
@@ -0,0 +1,11 @@
+# Semantic conventions for cloud provider SDKs
+
+**Status**: [Experimental, Feature-freeze][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
diff --git a/specification/cloud-providers/aws-sdk.md b/specification/cloud-providers/aws-sdk.md
@@ -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
diff --git a/specification/database/README.md b/specification/database/README.md
@@ -0,0 +1,26 @@
+# Semantic conventions for database calls and systems
+
+**Status**: [Experimental, Feature-freeze][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*.
+* [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
diff --git a/specification/database/cassandra.md b/specification/database/cassandra.md
@@ -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"`.
+
+## 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
diff --git a/specification/database/cosmosdb.md b/specification/database/cosmosdb.md
@@ -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.
+
+## Microsoft Azure Cosmos DB 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
diff --git a/specification/database/couchdb.md b/specification/database/couchdb.md
@@ -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"`.
+
+## 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
diff --git a/.../semantic_conventions/database-metrics.md → specification/database/database-metrics.md b/.../semantic_conventions/database-metrics.md → specification/database/database-metrics.md
@@ -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