Telemetry (Tracing and Metrics)

ldbc supports distributed tracing and metrics collection compliant with OpenTelemetry Semantic Conventions. Internally it uses otel4s, and works on all platforms: JVM, JS, and Native.

When no OpenTelemetry backend is connected, tracing and metrics automatically become no-ops with zero performance impact.

Dependencies

ldbc-connector depends only on otel4s-core (the abstract API). To actually collect and export telemetry data, you need to add a backend implementation.

libraryDependencies ++= Seq(
  // ldbc connector (includes otel4s-core)
  "io.github.takapi327" %% "ldbc-connector" % "0.6.0",

  // OpenTelemetry Java SDK backend
  "org.typelevel"    %% "otel4s-oteljava"                           % "0.15.1",
  "io.opentelemetry"  % "opentelemetry-exporter-otlp"               % "1.59.0" % Runtime,
  "io.opentelemetry"  % "opentelemetry-sdk-extension-autoconfigure" % "1.59.0" % Runtime,
)

Setup

Set Tracer[F] and Meter[F] on MySQLDataSource.

import cats.effect.*
import io.opentelemetry.api.GlobalOpenTelemetry
import org.typelevel.otel4s.oteljava.OtelJava
import ldbc.connector.*

object Main extends IOApp.Simple:

  override def run: IO[Unit] =
    val resource = for
      otel   <- Resource
                   .eval(IO.delay(GlobalOpenTelemetry.get))
                   .evalMap(OtelJava.forAsync[IO])
      tracer <- Resource.eval(otel.tracerProvider.get("my-app"))
      meter  <- Resource.eval(otel.meterProvider.get("my-app"))
      datasource = MySQLDataSource
                     .build[IO]("127.0.0.1", 3306, "user")
                     .setPassword("password")
                     .setDatabase("mydb")
                     .setTracer(tracer)
                     .setMeter(meter)
      connection <- datasource.getConnection
    yield connection

    resource.use { conn =>
      conn.createStatement().flatMap(_.executeQuery("SELECT 1")).void
    }

When using connection pooling, pass meter to the pooling method.

val pool = MySQLDataSource.pooling[IO](
  config = MySQLConfig.default
    .setHost("127.0.0.1")
    .setPort(3306)
    .setUser("user")
    .setPassword("password")
    .setDatabase("mydb"),
  meter  = Some(meter),
  tracer = Some(tracer)
)

Tracing

Overview

ldbc generates an OpenTelemetry span for each database operation. Spans are created through the exchange mechanism, which works in conjunction with a Mutex to guarantee serialization of MySQL protocol operations.

Span Names

Span names are generated following the OpenTelemetry Semantic Conventions priority:

1. db.query.summary if available (e.g., SELECT users)
2. {db.operation.name} {target} (e.g., SELECT users)
3. {target} only
4. Fallback: mysql

When extractMetadataFromQueryText in TelemetryConfig is true (default), operation names and table names are automatically extracted from SQL to generate dynamic span names. When false, fixed span names like Execute Statement are used.

The following is a list of the main spans generated by ldbc:

Span Attributes

Each span is annotated with the following attributes:

Error Recording

When a database operation fails, the following is recorded on the span:

• The span status is set to Error
• The error.type attribute records the error class name
• recordException records the stack trace as a span event
• For MySQL ERRPacket responses, the error code and SQLState are also recorded as attributes

TelemetryConfig

Use TelemetryConfig to customize telemetry behavior.

import ldbc.connector.telemetry.TelemetryConfig

// Default settings (all enabled)
val default = TelemetryConfig.default

// Disable metadata extraction from SQL (use fixed span names)
val fixed = TelemetryConfig.withoutQueryTextExtraction

// Individual settings
val custom = TelemetryConfig.default
  .withoutQueryTextExtraction      // Use fixed span names
  .withoutSanitization             // Disable query text sanitization
  .withoutInClauseCollapsing       // Disable IN clause collapsing

Query Sanitization

When sanitizeNonParameterizedQueries is enabled, string literals, numbers, NULL values, etc. in the SQL recorded in the db.query.text attribute are replaced with ?. This prevents sensitive data from being included in traces.

-- Original SQL
SELECT * FROM users WHERE name = 'Alice' AND age > 25

-- After sanitization (value recorded in db.query.text)
SELECT * FROM users WHERE name = ? AND age > ?

IN Clause Collapsing

When collapseInClauses is enabled, span cardinality is kept low even when the number of parameters in IN clauses varies.

-- Original SQL
SELECT * FROM users WHERE id IN (?, ?, ?, ?)

-- After collapsing
SELECT * FROM users WHERE id IN (?)

Metrics

Overview

ldbc collects metrics compliant with the OpenTelemetry Database Metrics Semantic Conventions. Metrics are divided into two categories: operation metrics and connection pool metrics.

Operation Metrics

Automatically recorded for all Statement, PreparedStatement, and CallableStatement executions.

db.client.operation.duration

Recorded for all of executeQuery, executeUpdate, and executeBatch. Cancelled operations are not recorded.

db.client.response.returned_rows

Recorded only for executeQuery-type methods. Not recorded for executeUpdate or executeBatch.

Metrics Attributes

Operation metrics are annotated with the following low-cardinality attributes. Unlike trace attributes, high-cardinality attributes such as db.query.text and db.mysql.thread_id are excluded to keep metrics aggregation costs manageable.

Connection Pool Metrics

Recorded only when using connection pooling (PooledDataSource). All metrics carry the db.client.connection.pool.name attribute.

Histogram Metrics

Counter Metrics

Gauge Metrics (Observable)

The following metrics are reported at export time via OTel's BatchCallback.

Differences Between Traces and Metrics

ldbc uses different attributes for traces and metrics. This follows OpenTelemetry best practices to properly manage metrics cardinality.

Selective Use of Tracer/Meter

Tracer and Meter can be used independently.

// Tracing only (no metrics)
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")
  .setTracer(tracer)

// Metrics only (no tracing)
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")
  .setMeter(meter)

// Both
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")
  .setTracer(tracer)
  .setMeter(meter)

// Neither (no-op, zero performance impact)
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")