Skip to content

Commit cc780be

Browse files
Liudmila Molkovatraskjoaopgrassi
authored
Database: mention metrics in system-specific docs (#1779)
Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Joao Grassi <[email protected]>
1 parent 7bde041 commit cc780be

File tree

13 files changed

+259
-53
lines changed

13 files changed

+259
-53
lines changed

‎.chloggen/1779.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
change_type: enhancement
2+
component: db
3+
note: Add metrics section to each of the database system-specific conventions.
4+
issues: [1447, 1779]

‎docs/database/cassandra.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,22 @@ linkTitle: Cassandra
66

77
**Status**: [Experimental][DocumentStatus]
88

9-
The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md).
9+
<!-- toc -->
10+
11+
- [Spans](#spans)
12+
- [Metrics](#metrics)
13+
14+
<!-- tocstop -->
15+
16+
The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend and override the [Database Semantic Conventions](README.md).
17+
18+
## Spans
19+
20+
Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md).
1021

1122
`db.system` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**.
1223

13-
## Attributes
24+
The following table outlines the span attributes applicable to Cassandra.
1425

1526
<!-- semconv span.db.cassandra.client -->
1627
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -144,4 +155,11 @@ and SHOULD be provided **at span creation time** (if provided at all):
144155
<!-- END AUTOGENERATED TEXT -->
145156
<!-- endsemconv -->
146157

158+
## Metrics
159+
160+
Cassandra client instrumentations SHOULD collect metrics according to the general
161+
[Semantic Conventions for Database Client Metrics](database-metrics.md).
162+
163+
`db.system` MUST be set to `"cassandra"`.
164+
147165
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

‎docs/database/cosmosdb.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,33 +2,37 @@
22
linkTitle: Cosmos DB
33
--->
44

5+
# Semantic Conventions for Microsoft Azure Cosmos DB
6+
7+
**Status**: [Experimental][DocumentStatus]
8+
59
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
610

711
<!-- toc -->
812

9-
- [Semantic Conventions for Microsoft Azure Cosmos DB](#semantic-conventions-for-microsoft-azure-cosmos-db)
10-
- [Attributes](#attributes)
13+
- [Spans](#spans)
1114
- [Example](#example)
12-
- [Operation Level Metrics](#operation-level-metrics)
13-
- [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration)
14-
- [Metric: `db.client.response.returned_rows`](#metric-dbclientresponsereturned_rows)
15-
- [Metric: `db.client.cosmosdb.operation.request_charge`](#metric-dbclientcosmosdboperationrequest_charge)
16-
- [Metric: `db.client.cosmosdb.active_instance.count`](#metric-dbclientcosmosdbactive_instancecount)
15+
- [Metrics](#metrics)
16+
- [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration)
17+
- [Metric: `db.client.response.returned_rows`](#metric-dbclientresponsereturned_rows)
18+
- [Metric: `db.client.cosmosdb.operation.request_charge`](#metric-dbclientcosmosdboperationrequest_charge)
19+
- [Metric: `db.client.cosmosdb.active_instance.count`](#metric-dbclientcosmosdbactive_instancecount)
1720

1821
<!-- tocstop -->
1922

20-
# Semantic Conventions for Microsoft Azure Cosmos DB
23+
The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/)
24+
extend and override the [Database Semantic Conventions](README.md).
2125

22-
**Status**: [Experimental][DocumentStatus]
26+
## Spans
2327

24-
The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/)
25-
extend and override the [Database Semantic Conventions](database-spans.md).
28+
Cosmos DB instrumentations include call-level spans that represent logical database
29+
calls and adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md).
2630

27-
## Attributes
31+
Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). Semantic conventions described in this document apply to the call-level spans only.
2832

29-
`db.system` MUST be set to `"cosmosdb"` and SHOULD be provided **at span creation time**.
33+
The following table outlines the span attributes applicable to Cosmos DB.
3034

31-
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.
35+
`db.system` MUST be set to `"cosmosdb"` and SHOULD be provided **at span creation time**.
3236

3337
<!-- semconv span.db.cosmosdb.client -->
3438
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -271,7 +275,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
271275
<!-- END AUTOGENERATED TEXT -->
272276
<!-- endsemconv -->
273277

274-
## Example
278+
### Example
275279

276280
| Key | Value |
277281
|:-------------------------------------| :------------------- |
@@ -289,7 +293,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
289293
| `db.cosmosdb.sub_status_code` | `0` |
290294
| `db.cosmosdb.request_charge` | `7.43` |
291295

292-
## Operation Level Metrics
296+
## Metrics
293297

294298
The following metrics provide insights into Azure Cosmos DB client operation performance and behavior.
295299

‎docs/database/couchdb.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,22 @@ linkTitle: CouchDB
66

77
**Status**: [Experimental][DocumentStatus]
88

9-
The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](database-spans.md).
9+
<!-- toc -->
10+
11+
- [Spans](#spans)
12+
- [Metrics](#metrics)
13+
14+
<!-- tocstop -->
15+
16+
The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](README.md).
17+
18+
## Spans
19+
20+
Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md).
1021

1122
`db.system` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**.
1223

13-
## Attributes
24+
The following table outlines the span attributes applicable to CouchDB.
1425

1526
<!-- semconv span.db.couchdb.client -->
1627
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -68,4 +79,11 @@ and SHOULD be provided **at span creation time** (if provided at all):
6879
<!-- END AUTOGENERATED TEXT -->
6980
<!-- endsemconv -->
7081

82+
## Metrics
83+
84+
CouchDB client instrumentations SHOULD collect metrics according to the general
85+
[Semantic Conventions for Database Client Metrics](database-metrics.md).
86+
87+
`db.system` MUST be set to `"couchdb"`.
88+
7189
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

‎docs/database/database-spans.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
linkTitle: Client Calls
33
--->
44

5-
# Semantic Conventions for Database Client Calls
5+
# Semantic Conventions for Database Client Spans
66

77
**Status**: [Release Candidate][DocumentStatus], unless otherwise specified
88

@@ -96,7 +96,7 @@ classify as errors.
9696

9797
## Common attributes
9898

99-
These attributes will usually be the same for all operations performed over the same database connection.
99+
These attributes are commonly used across different database systems.
100100

101101
<!-- semconv span.db.client -->
102102
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->

‎docs/database/dynamodb.md‎

Lines changed: 47 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,38 @@ linkTitle: AWS DynamoDB
66

77
**Status**: [Experimental][DocumentStatus]
88

9+
<!-- toc -->
10+
11+
- [Spans](#spans)
12+
- [DynamoDB.BatchGetItem](#dynamodbbatchgetitem)
13+
- [DynamoDB.BatchWriteItem](#dynamodbbatchwriteitem)
14+
- [DynamoDB.CreateTable](#dynamodbcreatetable)
15+
- [DynamoDB.DeleteItem](#dynamodbdeleteitem)
16+
- [DynamoDB.DeleteTable](#dynamodbdeletetable)
17+
- [DynamoDB.DescribeTable](#dynamodbdescribetable)
18+
- [DynamoDB.GetItem](#dynamodbgetitem)
19+
- [DynamoDB.ListTables](#dynamodblisttables)
20+
- [DynamoDB.PutItem](#dynamodbputitem)
21+
- [DynamoDB.Query](#dynamodbquery)
22+
- [DynamoDB.Scan](#dynamodbscan)
23+
- [DynamoDB.UpdateItem](#dynamodbupdateitem)
24+
- [DynamoDB.UpdateTable](#dynamodbupdatetable)
25+
- [Metrics](#metrics)
26+
27+
<!-- tocstop -->
28+
929
The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) extend and override the general
10-
[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) and [Database Semantic Conventions](database-spans.md).
30+
[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) and [Database Semantic Conventions](/docs/database/README.md).
31+
32+
## Spans
33+
34+
Spans representing calls to AWS DynamoDB adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md).
35+
36+
The following table outlines the span attributes applicable to DynamoDB.
1137

1238
`db.system` MUST be set to `"dynamodb"` and SHOULD be provided **at span creation time**.
1339

14-
## DynamoDB.BatchGetItem
40+
### DynamoDB.BatchGetItem
1541

1642
<!-- semconv span.dynamodb.batchgetitem.client -->
1743
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -51,7 +77,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
5177
<!-- END AUTOGENERATED TEXT -->
5278
<!-- endsemconv -->
5379

54-
## DynamoDB.BatchWriteItem
80+
### DynamoDB.BatchWriteItem
5581

5682
<!-- semconv span.dynamodb.batchwriteitem.client -->
5783
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -92,7 +118,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
92118
<!-- END AUTOGENERATED TEXT -->
93119
<!-- endsemconv -->
94120

95-
## DynamoDB.CreateTable
121+
### DynamoDB.CreateTable
96122

97123
<!-- semconv span.dynamodb.createtable.client -->
98124
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -137,7 +163,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
137163
<!-- END AUTOGENERATED TEXT -->
138164
<!-- endsemconv -->
139165

140-
## DynamoDB.DeleteItem
166+
### DynamoDB.DeleteItem
141167

142168
<!-- semconv span.dynamodb.deleteitem.client -->
143169
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -178,7 +204,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
178204
<!-- END AUTOGENERATED TEXT -->
179205
<!-- endsemconv -->
180206

181-
## DynamoDB.DeleteTable
207+
### DynamoDB.DeleteTable
182208

183209
<!-- semconv span.dynamodb.deletetable.client -->
184210
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -217,7 +243,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
217243
<!-- END AUTOGENERATED TEXT -->
218244
<!-- endsemconv -->
219245

220-
## DynamoDB.DescribeTable
246+
### DynamoDB.DescribeTable
221247

222248
<!-- semconv span.dynamodb.describetable.client -->
223249
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -256,7 +282,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
256282
<!-- END AUTOGENERATED TEXT -->
257283
<!-- endsemconv -->
258284

259-
## DynamoDB.GetItem
285+
### DynamoDB.GetItem
260286

261287
<!-- semconv span.dynamodb.getitem.client -->
262288
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -298,7 +324,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
298324
<!-- END AUTOGENERATED TEXT -->
299325
<!-- endsemconv -->
300326

301-
## DynamoDB.ListTables
327+
### DynamoDB.ListTables
302328

303329
<!-- semconv span.dynamodb.listtables.client -->
304330
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -339,7 +365,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
339365
<!-- END AUTOGENERATED TEXT -->
340366
<!-- endsemconv -->
341367

342-
## DynamoDB.PutItem
368+
### DynamoDB.PutItem
343369

344370
<!-- semconv span.dynamodb.putitem.client -->
345371
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -380,7 +406,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
380406
<!-- END AUTOGENERATED TEXT -->
381407
<!-- endsemconv -->
382408

383-
## DynamoDB.Query
409+
### DynamoDB.Query
384410

385411
<!-- semconv span.dynamodb.query.client -->
386412
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -427,7 +453,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
427453
<!-- END AUTOGENERATED TEXT -->
428454
<!-- endsemconv -->
429455

430-
## DynamoDB.Scan
456+
### DynamoDB.Scan
431457

432458
<!-- semconv span.dynamodb.scan.client -->
433459
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -477,7 +503,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
477503
<!-- END AUTOGENERATED TEXT -->
478504
<!-- endsemconv -->
479505

480-
## DynamoDB.UpdateItem
506+
### DynamoDB.UpdateItem
481507

482508
<!-- semconv span.dynamodb.updateitem.client -->
483509
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -518,7 +544,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
518544
<!-- END AUTOGENERATED TEXT -->
519545
<!-- endsemconv -->
520546

521-
## DynamoDB.UpdateTable
547+
### DynamoDB.UpdateTable
522548

523549
<!-- semconv span.dynamodb.updatetable.client -->
524550
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -562,4 +588,11 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex
562588
<!-- END AUTOGENERATED TEXT -->
563589
<!-- endsemconv -->
564590

591+
## Metrics
592+
593+
AWS DynamoDB client instrumentations SHOULD collect metrics according to the general
594+
[Semantic Conventions for Database Client Metrics](database-metrics.md).
595+
596+
`db.system` MUST be set to `"dynamodb"`.
597+
565598
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

‎docs/database/elasticsearch.md‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,25 @@ linkTitle: Elasticsearch
66

77
**Status**: [Experimental][DocumentStatus]
88

9-
The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](database-spans.md).
9+
<!-- toc -->
1010

11-
`db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**.
11+
- [Spans](#spans)
12+
- [Example](#example)
13+
- [Metrics](#metrics)
14+
15+
<!-- tocstop -->
16+
17+
The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and override the [Database Semantic Conventions](README.md).
1218

13-
## Span Name
19+
## Spans
20+
21+
Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md).
1422

1523
The **span name** follows the [general database span name guidelines](database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`.
1624

17-
## Attributes
25+
`db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**.
26+
27+
The following table outlines the span attributes applicable to Elasticsearch.
1828

1929
<!-- semconv span.db.elasticsearch.client -->
2030
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -150,7 +160,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
150160
<!-- END AUTOGENERATED TEXT -->
151161
<!-- endsemconv -->
152162

153-
## Example
163+
### Example
154164

155165
| Key | Value |
156166
|:------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------|
@@ -167,4 +177,11 @@ and SHOULD be provided **at span creation time** (if provided at all):
167177
| `db.namespace` | `"my-cluster"` |
168178
| `db.elasticsearch.node.name` | `"instance-0000000001"` |
169179

180+
## Metrics
181+
182+
Elasticsearch client instrumentations SHOULD collect metrics according to the general
183+
[Semantic Conventions for Database Client Metrics](database-metrics.md).
184+
185+
`db.system` MUST be set to `"elasticsearch"`.
186+
170187
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

0 commit comments

Comments
 (0)