added more information

open-telemetry · Jan 13, 2023 · 32de87f · 32de87f
1 parent 7382872
commit 32de87f
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 35 deletions.
diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
@@ -397,54 +397,107 @@ groups:
         examples: ['public.users', 'customers']
 
   - id: db.cosmosdb
-    prefix: db.cosmosdb
     type: span
     extends: db
     brief: >
       Call-level attributes for CosmosDb
     attributes:
-      - id: "client_id"
+      - id: "kind"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "machine_id"
+        brief: one of the ACTIVITYKIND
+      - id: "az.namespace"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "user_agent"
+        brief: Microsoft.DocumentDB
+      - id: "db.system"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "connection_mode"
+        brief: cosmosdb
+      - id: "db.name"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "container"
+        brief: Database Name
+      - id: "db.operation"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "request_content_length_bytes"
+        brief: Database Operation Name e.g. ReadItemAsync, DeleteItemStreamAsync  etc.
+      - id: "net.peer.name"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+        brief: Account Name + Cloud e.g. for public cloud it will be <account name>.document.azure.com
+      - id: "db.cosmosdb.client_id"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+        brief: Unique Id generated by an instance of CosmosClient
+      - id: "db.cosmosdb.machine_id"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+        brief: Machine level Id generaed by SDK it will be VM Id for Azure machines and Hashed Machine Name for non-Azure VMs
+      - id: "db.cosmosdb.user_agent"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+      - id: "db.cosmosdb.connection_mode"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+        brief: Direct or Gateway
+      - id: "db.cosmosdb.container"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+      - id: "db.cosmosdb.request_content_length_bytes"
         type: int
         tag: call-level-tech-specific-cosmsodb
-      - id: "response_content_length_bytes"
+      - id: "db.cosmosdb.response_content_length_bytes"
         type: int
         tag: call-level-tech-specific-cosmsodb
-      - id: "status_code"
+      - id: "db.cosmosdb.status_code"
         type: int
         tag: call-level-tech-specific-cosmsodb
-      - id: "sub_status_code"
+      - id: "db.cosmosdb.sub_status_code"
         type: int
         tag: call-level-tech-specific-cosmsodb
-      - id: "request_charge"
+      - id: "db.cosmosdb.request_charge"
         type: int
         tag: call-level-tech-specific-cosmsodb
-      - id: "regions_contacted"
+      - id: "db.cosmosdb.regions_contacted"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "retry_count"
+        brief: Comma separated list of regions contacted by any operation
+      - id: "db.cosmosdb.retry_count"
         type: int
         tag: call-level-tech-specific-cosmsodb
-      - id: "operation_type"
+      - id: "db.cosmosdb.operation_type"
         type: string
         tag: call-level-tech-specific-cosmsodb
-      - id: "item_count"
+      - id: "db.cosmosdb.item_count"
         type: int
         tag: call-level-tech-specific-cosmsodb
+      - id: "db.cosmosdb.activity_id"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+        brief: Unique Id for the operation and can be helpful to debug particular operation in backend logs
+      - id: "db.cosmosdb.correlated_activity_id"
+        type: string
+        tag: call-level-tech-specific-cosmsodb
+        brief: It will be populated only in case of query operation to allow correlating query pages retrieved for the same multi-page or cross-partition query.
+      - id: "rntbd.url"
+        type: string
+        tag: connection-level
+        brief: rntb://<hostname><partitionid><replicaid>
+      - id: "rntbd.operation_type"
+        type: string
+        tag: connection-level
+        brief: operation type e.g. Read, Query etc
+      - id: "rntbd.resource_type"
+        type: string
+        tag: connection-level
+        brief: resource_type e.g. Document etc
+      - id: "rntbd.status_code"
+        type: string
+        tag: connection-level
+      - id: "rntbd.sub_status_code"
+        type: string
+        tag: connection-level
 
   - id: db.tech
     type: span

diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md
@@ -270,33 +270,20 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an
 
 ### CosmosDB
 
-##### Azure Specific Attributes
+CosmosDb SDK (Currently only .Net) emit Activity at operation level with following attributes/information.
+
 | Attribute  | Value | Comment |
 | --------  | ------------------- | --------------------- |
 | _kind_ | _client_       | _IGNORE, By Default, setting them as part of diagnostic scope_ | 
 | _az.namespace_| _Microsoft.DocumentDB_  | _IGNORE,  By Default, setting them as part of diagnostic scope_  | 
-
-##### Common Database Attributes
-| Attribute  | Value | Comment |
-| --------  | ------------------- | --------------------- |
 |db.system| cosmosdb | Open Telemetry Convention To identify type of Db  ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md#notes-and-well-known-identifiers-for-dbsystem|
 | db.name | < Database Name >  |   | 
 | db.operation| ReadItemAsync, DeleteItemStreamAsync etc  | Database Operation ~Type~ Name  | 
 | net.peer.name |  e.g. sourabhjaintemp  |  Account Name + Cloud | 
-
-##### Cosmos DB Specific
-Account Level Information:
-| Attribute  | Value | Comment |
-| --------  | ------------------- | --------------------- |
 | db.cosmosdb.client_id| Unique Client Id| Combination of client id and machine id can tell us, if customer is following best practices to create singleton client  |
 | db.cosmosdb.machine_id| Unique Machine Id|  |
 | db.cosmosdb.user_agent| < User Agent With SDK version>  | Useful to identify the SDK version  | 
 | db.cosmosdb.connection_mode | Direct/Gateway |   go through | 
-
-Request Level Information:
-
-| Attribute  | Value | Comment |
-| --------  | ------------------- | --------------------- |
 | db.cosmosdb.container| Container |    |
 | db.cosmosdb.request_content_length_bytes | Size of request payload |    |
 | db.cosmosdb.response_content_length_bytes | Size of response Payload |   | 
@@ -307,12 +294,18 @@ Request Level Information:
 | db.cosmosdb.retry_count| Number of retries|  |
 | db.cosmosdb.operation_type| Query/Read/Create |  |
 | db.cosmosdb.item_count | < int number> |  Number of items returned by the operation, only Feed Operation |
-| db.cosmosdb.request_diagnostics | < JSON String> |  **Open Question: What if this string is out of the limit size? will appinsight will break it and divide into different attributes?**  |
+| db.cosmosdb.activity_id | Guid |  Unique Id for the operation and can be helpful to debug particular operation in backend logs  |
+| db.cosmosdb.correlated_activity_id| Guid | It will be populated only in case of query operation to allow correlating query pages retrieved for the same multi-page or cross-partition query. |
+| exception.type| `java.net.ConnectException; ``OSError `| ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md | 
+| exception.message| `Division by zero; Can't convert 'int' object to str implicitly `| ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md | 
+| exception.stacktrace| `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md | 
 
-##### Open Telemetry Standard for any Exception
+CosmosDb SDK (Currently only .Net) emit Activity at Network level with following attributes/information.
 
 | Attribute  | Value | Comment |
 | --------  | ------------------- | --------------------- |
-| exception.type| `java.net.ConnectException; ``OSError `| ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md | 
-| exception.message| `Division by zero; Can't convert 'int' object to str implicitly `| ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md | 
-| exception.stacktrace| `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ref. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md | 
+| rntbd.url | |   rntbd url with partitionid and replicaid |
+| rntbd.operation_type |  |   Operation Type |
+| rntbd.resource_type |  |  Resource Type | 
+| rntbd.status_code  | 201/200/204   |  network status code  | 
+| rntbd.sub_status_code  | 1000/1002   |  Cosmos Db SubStatus Code |