-
Notifications
You must be signed in to change notification settings - Fork 169
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Moved and restructured database and object-store semconv to a databas…
…e folder structure Signed-off-by: Alexander Wert <alexander.wert@elastic.co>
- Loading branch information
1 parent
2aa586f
commit 33f7f76
Showing
22 changed files
with
732 additions
and
478 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.