テレメトリ（トレースとメトリクス）

ldbcはOpenTelemetry Semantic Conventionsに準拠した分散トレーシングとメトリクス収集をサポートしています。内部ではotel4sを使用しており、JVM・JS・Native のすべてのプラットフォームで動作します。

OpenTelemetryバックエンドを接続しない場合、トレースとメトリクスは自動的にno-op（何もしない）となり、パフォーマンスへの影響はありません。

依存関係

ldbc-connectorはotel4s-core（抽象API）のみに依存しています。実際にテレメトリデータを収集・送信するには、バックエンド実装を追加する必要があります。

libraryDependencies ++= Seq(
  // ldbcコネクタ（otel4s-coreを含む）
  "io.github.takapi327" %% "ldbc-connector" % "0.6.0",

  // OpenTelemetry Java SDKバックエンド
  "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,
)

セットアップ

Tracer[F]とMeter[F]を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
    }

コネクションプーリング使用時はmeterをpoolingメソッドに渡します。

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)
)

トレーシング

概要

ldbcは、データベース操作ごとにOpenTelemetryスパンを生成します。スパンはexchange機構を通じて作成され、MySQL プロトコルの直列性を保証するMutexと連携しています。

スパン名

スパン名はOpenTelemetry Semantic Conventionsの優先順位に従って生成されます：

1. db.query.summaryが利用可能な場合（例: SELECT users）
2. {db.operation.name} {target}（例: SELECT users）
3. {target}のみ
4. フォールバック: mysql

TelemetryConfigのextractMetadataFromQueryTextがtrue（デフォルト）の場合、SQLからオペレーション名とテーブル名を自動抽出し、動的なスパン名を生成します。falseの場合はExecute Statementのような固定のスパン名を使用します。

以下はldbcが生成する主なスパンの一覧です：

スパン属性

各スパンには以下の属性が付与されます：

エラー記録

データベース操作でエラーが発生した場合、スパンには以下が記録されます：

• スパンのステータスがErrorに設定される
• error.type属性にエラーの型名が記録される
• recordExceptionによりスタックトレースがスパンイベントとして記録される
• MySQLからのERRPacketの場合、エラーコードやSQLStateも属性として記録される

TelemetryConfig

TelemetryConfigを使用して、テレメトリの動作をカスタマイズできます。

import ldbc.connector.telemetry.TelemetryConfig

// デフォルト設定（すべて有効）
val default = TelemetryConfig.default

// SQLからのメタデータ抽出を無効にする（固定スパン名を使用）
val fixed = TelemetryConfig.withoutQueryTextExtraction

// 個別設定
val custom = TelemetryConfig.default
  .withoutQueryTextExtraction      // 固定スパン名を使用
  .withoutSanitization             // クエリテキストのサニタイズを無効化
  .withoutInClauseCollapsing       // IN句の折りたたみを無効化

クエリのサニタイズ

sanitizeNonParameterizedQueriesが有効な場合、db.query.text属性に記録されるSQLから文字列リテラル、数値、NULL等が?に置換されます。これにより、センシティブなデータがトレースに含まれることを防ぎます。

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

-- サニタイズ後（db.query.text に記録される値）
SELECT * FROM users WHERE name = ? AND age > ?

IN句の折りたたみ

collapseInClausesが有効な場合、IN句のパラメータ数が可変でもスパンのカーディナリティを抑えます。

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

-- 折りたたみ後
SELECT * FROM users WHERE id IN (?)

メトリクス

概要

ldbcはOpenTelemetry Database Metrics Semantic Conventionsに準拠したメトリクスを収集します。メトリクスはオペレーションメトリクスとコネクションプールメトリクスの2種類に分かれます。

オペレーションメトリクス

全てのStatement、PreparedStatement、CallableStatementの実行で自動的に記録されます。

db.client.operation.duration

executeQuery、executeUpdate、executeBatchのすべてで記録されます。キャンセルされた操作は記録されません。

db.client.response.returned_rows

executeQuery系のメソッドでのみ記録されます。executeUpdateやexecuteBatchでは記録されません。

メトリクス属性

オペレーションメトリクスには以下の低カーディナリティ属性が付与されます。トレース属性とは異なり、メトリクスの集約コストを抑えるため高カーディナリティな属性（db.query.text、db.mysql.thread_id等）は除外されています。

コネクションプールメトリクス

コネクションプーリング（PooledDataSource）使用時にのみ記録されます。すべてのメトリクスはdb.client.connection.pool.name属性を持ちます。

Histogram メトリクス

Counter メトリクス

ゲージメトリクス（Observable）

以下のメトリクスはOTelのBatchCallbackを通じてエクスポート時に報告されます。

トレースとメトリクスの違い

ldbcではトレースとメトリクスで異なる属性を使用しています。これはOpenTelemetryのベストプラクティスに従い、メトリクスのカーディナリティを適切に管理するためです。

Tracer/Meterの選択的使用

TracerとMeterは独立して使用できます。

// トレースのみ（メトリクスなし）
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")
  .setTracer(tracer)

// メトリクスのみ（トレースなし）
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")
  .setMeter(meter)

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

// どちらも設定しない（no-op、パフォーマンス影響なし）
val ds = MySQLDataSource.build[IO]("localhost", 3306, "user")