/DB

Diagnostics & OpenTelemetry

Every executed SQL statement automatically emits an OpenTelemetry activity (span) with database semantic-convention tags and records a duration histogram and command/error counters. Subscribe with a single AddSource/AddMeter.

updated 5 Jun 20262 min readv0.2.0View as Markdown

Overview

As of 0.2.0 the library instruments every SQL statement it executes — queries, inserts, updates, deletes, joins, set operations, stored procedures, migrations and DDL. For each command it emits:

  • an OpenTelemetry activity (span) with database semantic-convention tags,
  • a duration histogram plus command and error counters,
  • one structured log message (see Logging).

Tracing and metrics need no configuration beyond subscribing — the library exposes a single source/meter name.

Enable tracing & metrics

Both the ActivitySource and Meter are named Socigy.OpenSource.DB. Register them with OpenTelemetry:

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t
        .AddSource("Socigy.OpenSource.DB")
        .AddOtlpExporter())
    .WithMetrics(m => m
        .AddMeter("Socigy.OpenSource.DB")
        .AddOtlpExporter());

The constants are also available in code as SocigyDbInstrumentation.ActivitySourceName and SocigyDbInstrumentation.MeterName.

Span shape

Each command produces a client span named "<OPERATION> (postgresql)" (e.g. SELECT (postgresql)) with tags:

Tag Value
db.system postgresql
db.operation.name SELECT / INSERT / UPDATE / DELETE / PROC / MIGRATE / DDL / SEQUENCE
db.query.text the executed SQL (unless command-text capture is disabled)
db.query.parameters parameter names + types (values only when explicitly enabled — see Logging)
db.response.affected_rows rows affected (writes)
db.response.returned_rows rows read (streamed reads)

For reads the span stays open for the whole enumeration, so its duration reflects time-to-drain and db.response.returned_rows is accurate.

When you use ExecuteTransactionAsync, a parent TRANSACTION (postgresql) span wraps the commands, giving you a clean BEGIN…COMMIT trace.

Metrics

Instrument Type Unit Meaning
db.client.operation.duration histogram s Duration of each command.
socigy.db.commands counter {command} Commands executed.
socigy.db.command.errors counter {error} Commands that threw.

Each measurement is tagged with db.operation.name.

Errors

When a command throws, its span status is set to Error, an exception event is recorded, and socigy.db.command.errors is incremented before the exception propagates.

NOTE
These types come from System.Diagnostics.DiagnosticSource, which is part of the .NET shared framework on net6.0+. The package declares it (and Microsoft.Extensions.Logging.Abstractions) as dependencies so non-web consumers also resolve them.