RepoDb.Telemetry.Default 0.0.1-beta1

RepoDb.Telemetry.Default

Drop-in telemetry for RepoDB. Wires up a default ITrace that captures every operation (Insert, Query, Update, Delete, etc.) and publishes it to an insights collector — no custom ITrace implementation required.

Built on top of RepoDb.Telemetry.Core.

Getting Started

Install the package:

dotnet add package RepoDb.Telemetry.Default

Enable it once at application startup:

GlobalConfiguration
    .Setup(new GlobalConfigurationOptions { UseRegisteredGlobalTraces = true })
    .UseDefaultTelemetry(
        host: "https://your-collector-host",
        apiKey: "YOUR_API_KEY",
        applicationName: "MyApp",
        groupName: "Default");

That's it — every operation across all connections in the app is now traced automatically.

UseRegisteredGlobalTraces = true is required. It tells RepoDB to run every globally registered tracer (this one included) for every operation, without having to pass a trace argument to each call.

How It Works

• Each operation's start/end is captured as a TelemetryItem (application, group, operation name, statement, elapsed time, client machine, source assembly, etc.).
• Items are buffered in memory and flushed on an interval (Frequency, default 5 seconds).
• On flush, the batch is JSON-serialized, gzip-compressed, and POSTed to {host}/v1/telemetry/publish, with an X-API-Key header when an API key is supplied.
• Publish failures never throw — they're routed to the optional errorCallback and logger.

The DefaultTelemetryItem Model

Every captured operation is represented as a DefaultTelemetryItem — a concrete, RepoDB-specific subclass of RepoDb.Telemetry.Core's TelemetryItem (it adds no fields of its own; it exists so the default pipeline has its own type to construct, serialize, and evolve independently of the core package). Each instance carries:

These items are what gets buffered, batched, and serialized to JSON before being published to your collector.

Not an OpenTelemetry Collector — By Design

This package intentionally does not ship an OpenTelemetry (OTel) exporter or rely on the OTel SDK. DefaultTelemetryTrace hooks directly into RepoDB's ITrace before/after execution events and serializes its own lightweight DefaultTelemetryItem payload straight to HTTP — there's no OTel Span/Activity machinery, no resource/attribute mapping layer, and no dependency on the OTel collector protocol in the hot path.

That's a deliberate tradeoff, not an oversight:

• Performance. Operations are captured with a handful of property assignments and buffered in memory; nothing allocates spans, contexts, or goes through an exporter pipeline per call. For a library whose whole value proposition is being a thin, fast layer over ADO.NET, that overhead matters.
• Tight coupling to the library. The capture shape (DefaultTelemetryItem) mirrors RepoDB's own operation model (session id, statement, elapsed time, cancellation) instead of being generalized to fit an industry-wide schema, keeping the implementation simple and directly meaningful for RepoDB users.

An OTel-based collector is planned as a separate, opt-in package for enterprise-grade telemetry scenarios (distributed tracing across services, vendor-neutral export to existing observability stacks, etc.). Until then, RepoDb.Telemetry.Default is the fast, zero-fuss path to seeing what your RepoDB operations are doing.

Configuration

For more control, pass a DefaultTelemetryOption instead of individual arguments:

GlobalConfiguration
    .Setup(new GlobalConfigurationOptions { UseRegisteredGlobalTraces = true })
    .UseDefaultTelemetry(
        new DefaultTelemetryOption("MyApp")
        {
            Host = "https://your-collector-host",
            ApiKey = "YOUR_API_KEY",
            Group = "Default",
            Frequency = TimeSpan.FromSeconds(10)
        },
        errorCallback: ex => logger.LogError(ex, "Telemetry publish failed"),
        logger: serilogLogger);

UseDefaultTelemetry is idempotent — calling it again reuses the same underlying tracer instance rather than starting a new one.

What's with Docker Compose

The docker-compose.yml at the root of this project spins up a complete, self-hosted telemetry stack: a Postgres database, the HTTP collector your app publishes to, a query API, two background workers (a file data sinker and a purger), and a Grafana-based visualization dashboard.

Most settings are supplied as environment variables using the ${VAR:-default} pattern, so they can be overridden without touching the compose file — either by exporting them in your shell or by placing a .env file next to docker-compose.yml. A few values (like the Postgres password on the pgsql service itself) are hardcoded and would need a direct edit to the compose file to change.

pgsql

The Postgres database backing the entire stack — the collector writes to it, and the query, filedatasinker, purger, and visualization services all read from it.

collector

The HTTP endpoint your application publishes telemetry to (this is the host you pass to UseDefaultTelemetry). It validates the API key and writes incoming batches to Postgres.

query

The read API that serves telemetry data to the visualization dashboard.

filedatasinker

A background worker that periodically exports telemetry data from Postgres into flat files for downstream consumption by the query service.

purger

A background worker that deletes telemetry records older than a configured retention window, keeping the Postgres database from growing unbounded.

visualization

The Grafana-based dashboard used to browse and chart the telemetry your app has published.

Volumes and networks

Two named volumes persist state across restarts: pgdata (the Postgres data directory) and telemetry_data (the shared directory filedatasinker writes to and query reads from). All services share a single bridge network, repodb, so they can reach each other by service name (e.g. pgsql, collector).