2.5.4 OpenTelemetry Tracing Support

For applications that use the legacy JDBC API (that is, not X DevAPI or X DevAPI for C) on Linux systems and use OpenTelemetry (OTel) instrumentation, the connector adds query and connection spans to the trace generated by application code and forwards the current OpenTelemetry context to the server. OpenTelemetry tracing was introduced in the Connector/C++ 8.1.0 release.

Note

OTel context forwarding works only with MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see https://www.mysql.com/products/.

Enabling and Disabling Tracing

By default, the connector generates spans only when an instrumented application links with the required OpenTelemetry SDK libraries and configures the trace exporter to send trace data to some destination. If the application code does not use instrumentation, then the legacy connector does not use it either.

Connector/C++ supports a connection property option, OPT_OPENTELEMETRY, which has these values:

• OTEL_DISABLED: The connector does not create OpenTelemetry spans or forward the OpenTelemetry context to the server.

• OTEL_PREFERRED: Default. Use instrumentation in the connection if the required OpenTelemetry instrumentation is available. Otherwise, permit the connection to operate without any OpenTelemetry instrumentation.

The OPT_OPENTELEMETRY option also accepts a Boolean value in which false corresponds to OTEL_DISABLED. false is the only accepted Boolean value for this option; setting it to true has no meaning and emits an error.

For example, an application can specify OPT_OPENTELEMETRY in either form using the connect() syntax that takes an option map argument:

connection_properties["OPT_OPENTELEMETRY"] = false;
connection_properties["OPT_OPENTELEMETRY"] = OTEL_DISABLED;

When you build code that links to Connector/C++ and uses OTel instrumentation, the additional spans generated by the connector appear in the traces generated by your code. Spans generated by the connector are sent to the same destination (trace exporter) where other spans generated by the user code are sent as configured by user code. It is not possible to send spans generated by the connector to any other destination.

This implementation is distinct from the implementation provided through the MySQL client library (or the related telemetry_client client-side plugin).