Cosmos DB: Operation Level Metrics

[sourabh1007]

Introducing operation-level metrics in the .NET Cosmos DB SDK.
This PR includes the registration of semantic conventions in the OpenTelemetry community, ensuring full alignment with OpenTelemetry's established guidelines.

Dimensions

Tag/dimension name	Sample value
db.system	cosmodb
db.collection.name	myCollectionName
db.namespace	myDatabaseName
server.address	myaccountname.documents.azure.com
server.port	443
db.operation.name	query_items
db.cosmosdb.operation_type	batch; create; delete
db.response.status_code	200 or 429 etc.
db.cosmos.sub_status_code	1002 etc.
db.cosmos.client_id	Guid
db.cosmosdb.consistency_level	Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session
db.cosmosdb.machine_id	Unique Id for a machine (Dependent of otel generated machine details)

Metrics

Name	Unit	Type	Description
db.cosmosdb.operation.request_charge	{request_units}	histogram	Total request units per operation (sum of RUs for all requested needed when processing an operation) This metric SHOULD be specified with [ExplicitBucketBoundaries] of [ 1, 5, 10, 25, 50, 100, 250, 500, 1000]
db.client.operation.duration	s	histogram	Total end-to-end duration of the operation This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000]
db.query.limit	{count}	histogram	For feed operations (query, readAll, readMany, change feed) and batch operations, this meter capture the requested maxItemCount per page/request. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [50, 100, 250, 500, 1000, 2000, 5000]
db.client.response.row_count	{count}	histogram	For feed operations (query, readAll, readMany, change feed) batch operations this meter capture the actual item count in responses from the service. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [10, 50, 100, 250, 500, 1000, 2000, 5000, 10000].
db.cosmosdb.operation.regions_contacted	{count}	histogram	Number of regions contacted when executing an operation. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 2, 3, 5, 10, 20, 50].
db.cosmosdb.client.active_instances	{count}	histogram	Number of active SDK client instances. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 2, 3, 5, 10, 50, 100].

Added db.cosmosdb.consistency_level in attribute list also, we are going to collect it is traces also
Removed db.cosmosdb.operation_type
Added db.cosmosdb.machine_id in attribute list also, we are going to collect it is traces also

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

[lmolkova]

Please add markdown for the metrics.

You need to add codegen placeholders like

and metrics will be generated between them.

Please take a look at the existing database metric definitions in https://github.com/open-telemetry/semantic-conventions/blob/v1.27.0/docs/database/database-metrics.md?plain=1 for the examples.

Note that a couple of properties are not yet defined in yaml, but need to be specified in markdown:

• metric requirement level - https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metric-requirement-level.md
• histogram boundaries - https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameter-explicitbucketboundaries

Please also document whether cosmos reports any of the standard DB metrics (I assume it does report db.client.operation.duration). If so, please document any difference from the generic metric. E.g. like it's done here - https://github.com/open-telemetry/semantic-conventions/blob/main/docs/dotnet/dotnet-http-metrics.md#metric-httpserverrequestduration

[jcocchi]

Left a few nits, but looks good overall

[lmolkova]

Left a few minor final comments, but it looks good otherwise!

[lmolkova]

this one should probably be updowncounter - you probably don't expect people to measure P95 for it. Also it does not change much in well-behaved application.

We have plenty of examples of current/active metrics in semconv - http.server.active_requests, db.client.connection.count, dotnet.thread_pool.thread.count, etc all of them are updowncounters.

Histogram will be more expensive but also harder to use and would require you to keep a current value around. With up-down-counter, you'd record +1 when client is created and -1 when it's disposed and won't need to maintain any state in the clients.

[lmolkova]

any reason to have boundaries different than the generic ones ([ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ])?

[lmolkova]

could you please move Cosmos DB metrics to cosmosdb.md ?

[lmolkova]

this metric should be added to the list of generic metrics above

[lmolkova]

please generate this metric in this file

[lmolkova]

any reason not to start from 1? I assume many queries always return 1 item.

[lmolkova]

We don't have a good way to show it properly using tooling yet. Currently when it's rendered it shows 50+ db.system values table and is confusing.

We're doing something like

      # TODO: add db.system once https://github.com/open-telemetry/build-tools/issues/192 is possible
      # - ref: db.system

in other places and adding some text in markdown that system is populated to improve readability. Suggesting to do the same here.

[lmolkova]

each metric should have a requirement level - take a look at the examples of existing metrics in this file. I assume all of them should be required or recommended (when available) for cosmos?

[lmolkova]

you're losing the clarifications made for cosmos DB span with this approach - check out briefs/notes on the attributes - they are no longer specific to cosmos.

suggestion:

1. take the clarifications (levels, briefs, notes) of applicable attributes from db.cosmosdb group defined here

   semantic-conventions/model/database/spans.yaml

   Line 516 in 76112dd

   - id: db.cosmosdb

2. put the resulting attributes.db.cosmosdb.minimal group to database/common.yaml
3. extend attributes.db.cosmosdb.minimal group in cosmos db spans. You might need to play a bit with extension to make spans look exactly the same, but it should be doable.