CosmosClientTelemetryConfig Class

Package:

com.azure.cosmos.models

Maven Artifact:

com.azure:azure-cosmos:4.80.0

• java.lang.Object
• • com.azure.cosmos.models.CosmosClientTelemetryConfig

public final class CosmosClientTelemetryConfig

Class with config options for Cosmos Client telemetry

Constructor Summary

Constructor	Description
CosmosClientTelemetryConfig()	Instantiates a new Cosmos client telemetry configuration.

Method Summary

Modifier and Type	Method and Description
CosmosClientTelemetryConfig	clientCorrelationId(String clientCorrelationId) Sets the client correlationId used for tags in metrics.
CosmosClientTelemetryConfig	diagnosticsHandler(CosmosDiagnosticsHandler handler) Injects a custom diagnostics handler
CosmosClientTelemetryConfig	diagnosticsThresholds(CosmosDiagnosticsThresholds thresholds) Request diagnostics for operations will be logged if their latency, request charge or payload size exceeds one of the defined thresholds.
CosmosClientTelemetryConfig	enableTransportLevelTracing() Enables transport level tracing.
CosmosClientTelemetryConfig	metricsOptions(MetricsOptions clientMetricsOptions) Sets MetricsOptions to be used to emit client metrics
CosmosClientTelemetryConfig	metricTagNames(String[] tagNames) Deprecated Use CosmosMicrometerMetricsOptions#configureDefaultTagNames(CosmosMetricTagName...) or CosmosMicrometerMeterOptions#suppressTagNames(CosmosMetricTagName...) instead. Sets the tags that should be considered for metrics.
CosmosClientTelemetryConfig	sampleDiagnostics(double samplingRate) Can be used to enable sampling for capturing all diagnostics to reduce/disable any client resource overhead (CPU and/or memory).
CosmosClientTelemetryConfig	sendClientTelemetryToService(boolean enabled) Deprecated is is not possible to send the telemetry to the service. But client-side telemetry can be enabled via diagnosticsHandler(CosmosDiagnosticsHandler handler), metricsOptions(MetricsOptions clientMetricsOptions) and tracingOptions(TracingOptions tracingOptions). Enables or disables sending Cosmos DB client telemetry to the Azure Cosmos DB Service
CosmosClientTelemetryConfig	showQueryMode(ShowQueryMode showQueryMode) Enables printing query in db.statement attribute and diagnostic logs.
String	toString()
CosmosClientTelemetryConfig	tracingOptions(TracingOptions tracingOptions) Sets TracingOptions that are applied to each tracing reported by the client.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Details

CosmosClientTelemetryConfig

public CosmosClientTelemetryConfig()

Instantiates a new Cosmos client telemetry configuration.

Method Details

clientCorrelationId

public CosmosClientTelemetryConfig clientCorrelationId(String clientCorrelationId)

Sets the client correlationId used for tags in metrics. While we strongly encourage usage of singleton instances of CosmosClient there are cases when it is necessary to instantiate multiple CosmosClient instances - for example when an application connects to multiple Cosmos accounts. The client correlationId is used to distinguish client instances in metrics. By default an auto-incrementing number is used but with this method you can define your own correlationId (for example an identifier for the account)

Parameters:

clientCorrelationId - the client correlationId to be used to identify this client instance in metrics

Returns:

current CosmosClientTelemetryConfig

diagnosticsHandler

public CosmosClientTelemetryConfig diagnosticsHandler(CosmosDiagnosticsHandler handler)

Injects a custom diagnostics handler

Parameters:

handler - the custom diagnostics handler.

Returns:

current CosmosClientTelemetryConfig

diagnosticsThresholds

public CosmosClientTelemetryConfig diagnosticsThresholds(CosmosDiagnosticsThresholds thresholds)

Request diagnostics for operations will be logged if their latency, request charge or payload size exceeds one of the defined thresholds. This method can be used to customize the default thresholds, which are used across different types of diagnostics (logging, tracing, client telemetry).

Parameters:

thresholds - the default thresholds across all diagnostic types

Returns:

current CosmosClientTelemetryConfig

enableTransportLevelTracing

public CosmosClientTelemetryConfig enableTransportLevelTracing()

Enables transport level tracing. By default, transport-level tracing is not enabled - but when operations fail or exceed thresholds the diagnostics are traced. Enabling transport level tracing can be useful when latency is still beneath the defined thresholds.

Returns:

current CosmosClientTelemetryConfig

metricsOptions

public CosmosClientTelemetryConfig metricsOptions(MetricsOptions clientMetricsOptions)

Sets MetricsOptions to be used to emit client metrics

Parameters:

clientMetricsOptions -

• the client MetricsOptions - NOTE: for now only CosmosMicrometerMetricsOptions are supported

Returns:

current CosmosClientTelemetryConfig

metricTagNames

@Deprecated
public CosmosClientTelemetryConfig metricTagNames(String[] tagNames)

Deprecated

Use CosmosMicrometerMetricsOptions#configureDefaultTagNames(CosmosMetricTagName...) or CosmosMicrometerMeterOptions#suppressTagNames(CosmosMetricTagName...) instead.

Sets the tags that should be considered for metrics. By default all supported tags are used - and for most use-cases that should be sufficient. But each tag/dimension adds some overhead when collecting the metrics - especially for percentile calculations - so, when it is clear that a certain dimension is not needed, it can be prevented from even considering it when collecting metrics.

Parameters:

tagNames -

• a comma-separated list of tag names that should be considered

Returns:

current CosmosClientTelemetryConfig

sampleDiagnostics

public CosmosClientTelemetryConfig sampleDiagnostics(double samplingRate)

Can be used to enable sampling for capturing all diagnostics to reduce/disable any client resource overhead (CPU and/or memory). The sampling rate can for example be reduced when an application has high CPU usage to reduce overhead for capturing diagnostics temporarily. The sampling is applied to operations in the SDK - so, a single operation is either sampled out completely or all diagnostics (logs, tracing, metrics depending on what diagnostics are enabled) are captured. The main motivation for applying sampling for an entire operation is that a significant part of the CPU overhead happens when injecting the Context into the reactor pipeline - and the CPU usage reduction would be lower when sampling out metrics on one operation (but still capture traces) and traces on another operation (but still capturing metrics). In this case both operations would still have significant overhead - so, it is more efficient to cover both metrics and traces for one operation and disable diagnostics completely for the second operation. It also makes it easier to correlate metrics and traces for example when sampling is applied on the operation-level as described above.

Parameters:

samplingRate - the sampling rate - 0 means no diagnostics will be capture at all, 1 means no sampling applies and all diagnostics are captured.

Returns:

current CosmosClientTelemetryConfig

sendClientTelemetryToService

@Deprecated
public CosmosClientTelemetryConfig sendClientTelemetryToService(boolean enabled)

Deprecated

is is not possible to send the telemetry to the service. But client-side telemetry can be enabled via diagnosticsHandler(CosmosDiagnosticsHandler handler), metricsOptions(MetricsOptions clientMetricsOptions) and tracingOptions(TracingOptions tracingOptions).

Enables or disables sending Cosmos DB client telemetry to the Azure Cosmos DB Service

Parameters:

enabled - a flag indicating whether sending client telemetry to the backend should be enabled or not

Returns:

current CosmosClientTelemetryConfig

showQueryMode

public CosmosClientTelemetryConfig showQueryMode(ShowQueryMode showQueryMode)

Enables printing query in db.statement attribute and diagnostic logs. By default, query is not printed. Users have the option to enable printing parameterized or all queries, but has to beware that customer data may be shown when the later option is chosen It's the user's responsibility to sanitize the queries if necessary.

Parameters:

showQueryMode - the mode for printing none, parameterized or all of the query statements

Returns:

current CosmosClientTelemetryConfig

toString

public String toString()

Overrides:

CosmosClientTelemetryConfig.toString()

tracingOptions

public CosmosClientTelemetryConfig tracingOptions(TracingOptions tracingOptions)

Sets TracingOptions that are applied to each tracing reported by the client. Use tracing options to enable and disable tracing or pass implementation-specific configuration.

Parameters:

tracingOptions - instance of TracingOptions to set.

Returns:

The updated ClientOptions object.