Tracing

MySqlConnector instruments database operations with .NET’s ActivitySource API. The source name is MySqlConnector; subscribe to it from OpenTelemetry with AddSource("MySqlConnector").

OpenTelemetry

Install the OpenTelemetry NuGet package and an exporter such as OpenTelemetry.Exporter.OpenTelemetryProtocol.

using OpenTelemetry;
using OpenTelemetry.Exporter;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
	.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyApplication"))
	.AddSource("MySqlConnector")
	.AddOtlpExporter(options =>
	{
		options.Endpoint = new Uri("http://otel-collector:4318/v1/traces");
		options.Protocol = OtlpExportProtocol.HttpProtobuf;
	})
	.Build();

When using MySqlDataSourceBuilder, configure MySqlConnector tracing options with ConfigureTracing:

await using var dataSource = new MySqlDataSourceBuilder(connectionString)
	.ConfigureTracing(options => options
		.WithSemanticConventionsKinds(MySqlConnectorSemanticConventionsKinds.Stable))
	.Build();

Semantic Conventions

MySqlConnector supports both legacy experimental database attributes and stable OpenTelemetry database attributes. These are controlled by the OTEL_SEMCONV_STABILITY_OPT_IN environment variable, which can be set to one of the following values:

Use database/dup while migrating dashboards, alerts, and collector processors, then switch to database when all consumers use stable names.

You can override the environment variable for a specific data source:

await using var dataSource = new MySqlDataSourceBuilder(connectionString)
	.ConfigureTracing(options => options.WithSemanticConventionsKinds(
		MySqlConnectorSemanticConventionsKinds.Experimental |
		MySqlConnectorSemanticConventionsKinds.Stable))
	.Build();

Spans

All spans use ActivityKind.Client.

Stable Attributes

These attributes are emitted when MySqlConnectorSemanticConventionsKinds.Stable is active.

Connection Attributes

db.connection_string and db.user are legacy attributes and are not emitted in stable-only mode.

Execute Attributes

MySqlConnector does not emit db.collection.name, db.query.summary, db.query.parameter.<key>, or db.response.returned_rows.

Error Attributes

When an exception occurs, the span status is set to Error.

Legacy Attribute Mapping

When MySqlConnectorSemanticConventionsKinds.Experimental is active, MySqlConnector emits legacy attribute names. In database/dup mode, both legacy and stable attributes are emitted when a stable replacement exists.

Events

When an exception occurs, the span status is set to Error.

Stable: exception

Added when MySqlConnectorSemanticConventionsKinds.Stable is active.

Legacy experimental: db.client.operation.exception

Added when MySqlConnectorSemanticConventionsKinds.Experimental is active.

Both event names contain:

read-result-set-header

This opt-in event is emitted on Execute spans when a result-set header is received from the server. Enable it with:

await using var dataSource = new MySqlDataSourceBuilder(connectionString)
	.ConfigureTracing(options => options.EnableResultSetHeaderEvent())
	.Build();

W3C Trace Context Propagation

When an Execute span is active and the .NET Activity uses W3C ID format, MySqlConnector sends the active trace context to MySQL Server as query attributes when the server supports query attributes.

If traceparent or tracestate is already present in MySqlCommand.Attributes, MySqlConnector does not add a duplicate value.

Privacy Notes

db.query.text records command text. Parameterized queries are recommended because parameter values are not recorded, but literal values embedded directly in SQL text can appear in telemetry.

Legacy db.connection_string and db.user can also contain sensitive deployment information. Use stable-only mode, or drop these attributes in the OpenTelemetry Collector, if they should not be exported.