OpenTelemetryExtension.Configuration 2.1.3

Drop-in OpenTelemetry setup for .NET — tracing, metrics and logging over OTLP, configured through code or configuration.

builder.Services.AddTelemetry(builder.Configuration);

{
  "Telemetry": {
    "Endpoint": "http://localhost:4318",
    "ServiceName": "my-api"
  }
}

That's the whole setup — traces, metrics and logs are exported via OTLP.

Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Code Configuration
• Using outside the Generic Host
• Samples
• Running Locally with a Backend
• Sample Backend Configurations
• Contributing
• Report a Bug

✨ Features

• One-call setup — tracing, metrics and logging via a single AddTelemetry(), from appsettings.json or code
• Works on any .NET — ASP.NET Core, WPF, console and more, exporting over OTLP to any compatible backend
• Auto-instrumentation — HttpClient, ASP.NET Core and .NET runtime traced and measured automatically, each toggleable
• Extensible — add your own sources, meters and databases when you need them

✅ Requirements

Every app type works — ASP.NET Core, WPF, WinForms, console, worker services, MAUI/WinUI, UWP. The package ships three targets and NuGet picks the best match for your target framework; the app type plays no role:

The last column is only about the optional ASP.NET Core instrumentation dependency, which traces incoming HTTP requests and is therefore meaningless outside a web app. It is left out of the netstandard2.0 build so .NET Framework clients don't drag in an ASP.NET Core dependency they can't use. Everything else — OTLP export, tracing, metrics, logging, HttpClient and runtime instrumentation — is identical in all three builds.

A WPF app on net10.0-windows therefore gets the full net10.0 build. Only WPF on .NET Framework falls back to netstandard2.0.

You also need an OTLP-compatible backend to receive the telemetry (collector, Jaeger, OpenObserve, SigNoz, the .NET Aspire Dashboard, …). See Running Locally with a Backend.

📦 Installation

dotnet add package OpenTelemetryExtension.Configuration

Other ways to consume it

The NuGet package is the recommended path, but it isn't the only one:

• As source / project reference or a plain copy — the library is just two files. Either clone OpenTelemetryExtension.Configuration into your repository and add a <ProjectReference> to it, or drop the two files straight into your project (no package, no reference) and own them outright: TelemetryServiceCollectionExtensions.cs and TelemetryOptions.cs. Handy when you want to tweak the defaults or step through the setup code.
• As a git submodule — pin the source at a specific commit and reference the project from your solution:

  git submodule add https://github.com/thorstenalpers/OpenTelemetryExtension.Configuration.git external/OpenTelemetryExtension.Configuration
  

  then add a <ProjectReference> to external/OpenTelemetryExtension.Configuration/src/OpenTelemetryExtension.Configuration/OpenTelemetryExtension.Configuration.csproj.
• As a fork — fork the repository and adapt it to your needs. Optionally, if your changes are generally useful, open a pull request back upstream. See Contributing.

In every case the API is identical — AddTelemetry(...) works the same whether the type comes from a NuGet package or your own copy of the source.

🚀 Quick Start

1. Register

builder.Services.AddTelemetry(builder.Configuration);

2. Configure (appsettings.json)

{
  "Telemetry": {
    "Endpoint": "http://localhost:4318",
    "ServiceName": "my-api"
  }
}

That's it — tracing, metrics and logging are exported via OTLP.

You need an OTLP-compatible backend listening at Endpoint. No backend yet? See Running Locally with a Backend for one-command setups.

⚙️ Configuration

All keys live under the Telemetry section. Only Endpoint is required; everything else has a default and telemetry is on out of the box. Bind from appsettings.json or set the same properties in the AddTelemetry(o => …) callback.

💡 See docs/appsettings.Example.json for a complete profile with every key set to a realistic, non-default value.

Endpoint & protocol — give Endpoint the base URL, not a signal path:

• HttpProtobuf (default, port 4318) — the per-signal path (/v1/traces, /v1/metrics, /v1/logs) is appended for you.
• Grpc (port 4317) — every signal goes to the base endpoint as-is.

Endpoint is validated at registration and AddTelemetry() throws when it is missing. The one exception is Enabled: false: validation is skipped, nothing is registered, and the call becomes a no-op — so you can switch telemetry off in an environment without also having to supply an endpoint.

Custom section name

The section defaults to Telemetry, but you can bind any section by passing its name:

builder.Services.AddTelemetry(builder.Configuration, "MyTelemetry");
// or together with a code callback:
builder.Services.AddTelemetry(builder.Configuration, o => { /* ... */ }, "MyTelemetry");

{
  "MyTelemetry": {
    "Endpoint": "http://localhost:4318",
    "ServiceName": "my-api"
  }
}

🧩 Code Configuration

Configure entirely in code instead of appsettings.json:

builder.Services.AddTelemetry(o =>
{
    o.Endpoint        = new Uri("http://localhost:4318");
    o.ServiceName     = "my-api";
    o.ResourceAttributes = new() { ["deployment.environment"] = "production" };
    o.SampleRatio     = 0.1;

    // Code-only: register additional instrumentation
    o.ConfigureTracing = tracing => tracing.AddSource("MyApp");
    o.ConfigureMetrics = metrics => metrics.AddMeter("MyApp");
    o.ConfigureLogging = logging => logging.AddConsole();
});

Or bind appsettings.json first and layer code-only options on top — both sources are combined, and bound values can still be overridden in the callback:

builder.Services.AddTelemetry(builder.Configuration, o =>
{
    // Everything from appsettings.json is already bound here.
    o.ConfigureTracing = tracing => tracing.AddSource("MyApp");
    o.ConfigureMetrics = metrics => metrics.AddMeter("MyApp");
    o.ConfigureLogging = logging => logging.AddConsole();
});

The Configure* hooks — Sources & Meters

The three callbacks are the extension points for your own telemetry. The built-in instrumentation (ASP.NET Core, HttpClient, .NET runtime) is wired up automatically; these hooks let you add the signals your application emits itself, plus anything that needs an extra NuGet package — such as databases.

What is a Meter? A Meter (from System.Diagnostics.Metrics) is the factory you create instruments (counters, histograms, gauges) from. Each Meter has a name, and OpenTelemetry only collects metrics from meters you have explicitly registered with AddMeter("That.Name"). Without that call, your custom metrics are never exported.

// 1. Create a Meter and an instrument somewhere in your app
private static readonly Meter Meter = new("MyApp.Orders");
private static readonly Counter<long> OrdersPlaced = Meter.CreateCounter<long>("orders.placed");

// ... later
OrdersPlaced.Add(1);

// 2. Register the meter's name so it gets exported
o.ConfigureMetrics = metrics => metrics.AddMeter("MyApp.Orders");

What is a Source? An ActivitySource is the tracing equivalent: it creates Activity objects (= spans). Register its name with AddSource("MyApp") so your custom spans are sampled and exported.

private static readonly ActivitySource Activity = new("MyApp");

using var span = Activity.StartActivity("ProcessOrder");
// ... work being traced

o.ConfigureTracing = tracing => tracing.AddSource("MyApp");

The string passed to AddMeter/AddSource must exactly match the name you gave the Meter/ActivitySource — that name is how OpenTelemetry routes the data.

Databases

Database instrumentation is not built in — it depends entirely on your driver, so it is added through the ConfigureTracing hook. This keeps the package free of database-specific dependencies; you only pull in what you use.

There are two kinds of database instrumentation:

ConfigureTracing is a single delegate, so chain everything in one assignment:

// dotnet add package OpenTelemetry.Instrumentation.SqlClient
// dotnet add package OpenTelemetry.Instrumentation.EntityFrameworkCore
o.ConfigureTracing = t => t
    .AddSqlClientInstrumentation()
    .AddEntityFrameworkCoreInstrumentation()
    .AddSource("Npgsql")            // PostgreSQL
    .AddSource("MySqlConnector");   // MySQL

No code for source-based drivers: the second row of the table above needs no C# at all — AdditionalTracingSources does the same job from appsettings.json:

{
  "Telemetry": {
    "Endpoint": "http://localhost:4318",
    "AdditionalTracingSources": [ "Npgsql", "MyApp" ],
    "AdditionalMeters": [ "MyApp.Orders" ]
  }
}

Package-based instrumentation (SQL Server, EF Core) still needs the one-line ConfigureTracing call above, because it requires its NuGet package — a config string alone can't pull in a dependency.

Toggling SQL instrumentation from appsettings.json

Because EnableSqlClientInstrumentation is not part of TelemetryOptions (the package is optional), you can add it as a custom key and read it in the callback:

appsettings.json:

{
  "Telemetry": {
    "Endpoint": "http://localhost:4318",
    "ServiceName": "my-api",
    "RecordExceptions": true,

    "EnableSqlClientInstrumentation": true   // custom key
  }
}

Program.cs:

builder.Services.AddTelemetry(builder.Configuration, opt =>
    opt.ConfigureTracing = tracing =>
    {
        if (builder.Configuration.GetValue<bool>("Telemetry:EnableSqlClientInstrumentation"))
        {
            // NuGet: OpenTelemetry.Instrumentation.SqlClient
            tracing.AddSqlClientInstrumentation(sql => sql.RecordException = opt.RecordExceptions);
        }
    });

This keeps the on/off switch in config while the package dependency stays explicit in code.

🖥️ Using outside the Generic Host

AddTelemetry() works with any IServiceCollection — ASP.NET Core, WPF, WinForms, console, MAUI/WinUI, UWP, worker services, etc.

With the Generic Host (recommended for desktop/console — Host.CreateApplicationBuilder()), the providers start and flush automatically:

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddTelemetry(builder.Configuration);
using var host = builder.Build();
await host.RunAsync();   // telemetry starts here and flushes on shutdown

Without a host (e.g. a bare ServiceCollection in UWP or a minimal app), build the provider and dispose it on exit so buffered telemetry is flushed:

var services = new ServiceCollection();
services.AddTelemetry(o =>
{
    o.Endpoint    = new Uri("http://localhost:4318");
    o.ServiceName = "my-desktop-app";
});

var provider = services.BuildServiceProvider();
// ... app runs ...
provider.Dispose();      // flushes traces, metrics and logs

ASP.NET Core instrumentation is in the net8.0 and net10.0 builds only — which a desktop or console app targeting net8.0/net10.0 (or their -windows variants) does get. Only on the netstandard2.0 build (.NET Framework) is it absent, and setting EnableAspNetCoreInstrumentation there is a harmless no-op. See Requirements.

🧪 Samples

Two runnable samples live under src/:

The Web API sample drives the backend walkthrough below; the WPF sample exports to http://localhost:4318 by default — point it at any of the backends here.

🔌 Running Locally with a Backend

The Web API sample ships ready-to-run configurations for several popular backends (the three below are documented in full; more start scripts live in infrastructure/). Each backend has:

1. an infrastructure start script (Docker Compose or Helm) in infrastructure/,
2. a launch profile that selects the matching appsettings.<env>.json,
3. a UI where the exported traces, metrics and logs show up.

Steps

1. Start the backend infrastructure — run the script for your backend (see table).
   • Docker scripts live in infrastructure/docker and need Docker.
   • Helm scripts live in infrastructure/helm and need a local Kubernetes cluster (e.g. k3s in WSL2).
2. Run the sample with the matching profile:

   cd src/OpenTelemetryExtension.Configuration.Sample.WebApi
   dotnet run --launch-profile "Start Aspire"
   

   Or pick the profile from the run dropdown in Visual Studio / Rider.
3. Generate traffic — the app opens Swagger at https://localhost:5073/swagger; call an endpoint.
4. Open the backend UI (see table) to inspect the telemetry.

Backend overview

(Paths are relative to infrastructure/. The first three are documented in full below; the rest work the same way — start the script, pick the profile.)

Tip — viewing logs in the Aspire Dashboard: after starting the app with the Start Aspire profile, open http://localhost:31888, then go to the Structured (logs), Traces or Metrics tab. Data appears as soon as you hit a Swagger endpoint.

📝 Sample Backend Configurations

These are the exact appsettings.<env>.json files used by the sample's launch profiles.

.NET Aspire Dashboard — appsettings.aspire.json

The dashboard requires an API key on the OTLP endpoint (x-otlp-api-key). The gRPC endpoint is exposed on NodePort 31889 (Helm) or host port 31889 (Docker).

{
  "Telemetry": {
    "Protocol": "Grpc",
    "Endpoint": "http://localhost:31889",
    "Headers": "x-otlp-api-key=aspire"
  }
}

Traces, metrics and logs from the sample app shown live in the Aspire Dashboard UI:

Jaeger — appsettings.jaeger.json

{
  "Telemetry": {
    "Protocol": "Grpc",
    "Endpoint": "http://localhost:4317"
  }
}

Traces from the sample app shown in the Jaeger UI:

OpenObserve — HTTP/protobuf — appsettings.openobserve-http.json

{
  "Telemetry": {
    "Protocol": "HttpProtobuf",
    "Endpoint": "http://localhost:30117/api/default",
    "Headers": "Authorization=Basic YWRtaW5Ad2ViLmRlOmFkbWlu,stream-name=default"
  }
}

The same telemetry explored in the OpenObserve UI:

🤝 Contributing

Contributions are welcome — bug fixes, new instrumentation options, documentation improvements and ideas alike. For anything beyond a small fix, please open an issue first so we can agree on the approach before you invest time in a pull request.

The basic workflow is: fork the repo, branch off main (feature/<name> or fix/<name>), make your change, add or update tests for any public API change, run the unit tests, and open a PR against main. Build and test locally with:

dotnet build OpenTelemetryExtension.slnx -c Release
dotnet test  src/OpenTelemetryExtension.Configuration.Tests -c Release

Full details — code style, the integration-test stack, and the release process — are in CONTRIBUTING.md. Note that versioning and release notes are handled separately at release time, so you don't need to touch them in a feature PR.

🐛 Report a Bug

Found something broken or behaving unexpectedly? Please open an issue. To help reproduce it quickly, include the package version, your target framework (e.g. net10.0 or netstandard2.0), the relevant Telemetry configuration, the OTLP backend you export to, and what you expected to happen versus what actually did. A minimal repro or stack trace speeds things up a lot.

For security-sensitive reports, please follow SECURITY.md instead of opening a public issue.