Ofbirds.Observability 1.2.0

dotnet add package Ofbirds.Observability --version 1.2.0
                    
NuGet\Install-Package Ofbirds.Observability -Version 1.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Ofbirds.Observability" Version="1.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Ofbirds.Observability" Version="1.2.0" />
                    
Directory.Packages.props
<PackageReference Include="Ofbirds.Observability" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Ofbirds.Observability --version 1.2.0
                    
#r "nuget: Ofbirds.Observability, 1.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Ofbirds.Observability@1.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Ofbirds.Observability&version=1.2.0
                    
Install as a Cake Addin
#tool nuget:?package=Ofbirds.Observability&version=1.2.0
                    
Install as a Cake Tool

Ofbirds.Observability

One-call logging + OpenTelemetry for ASP.NET Core services, so every service emits the same shape of telemetry. Defaults are the standard; the opt-outs exist for the rare case where a piece is impossible or genuinely unwanted.

var builder = WebApplication.CreateBuilder(args);
builder.AddOfbirdsObservability("my-app");   // FIRST — it sets the static Log.Logger
builder.RedactConfigurationSecret("SEQ_API_KEY", "environment#SEQ_API_KEY");

var app = builder.Build();
app.UseOfbirdsObservability();               // request logging + health endpoints

What you get

Logging (Serilog) — console, rolling compact-JSON file (logs/log-.json, 31 days), and Seq when SEQ_URL is set. Enrichers: log context, machine name, process id, thread id, Application, Version. Minimum level Information, with Microsoft.AspNetCore and System.Net.Http.HttpClient at Warning. Both the static Log.Logger and the DI logger are wired, so startup-time Log.Warning(...) calls before the host is built still reach the sinks.

Tracing (OpenTelemetry) — ASP.NET Core + HttpClient instrumentation plus your app's own ActivitySource, exported over OTLP/HTTP-protobuf.

Metrics — ASP.NET Core, HttpClient, runtime, and your app's Meter. Off unless OTEL_EXPORTER_OTLP_METRICS_ENDPOINT is set: not every backend accepts metrics, and one that doesn't answers with a 404 on every export interval. Point that variable at a metrics-capable collector — or at Seq 2026.1+, which ingests metrics natively — and they start flowing with no code change.

Health endpoints — /api/health (all checks) and /api/alive (checks tagged live), both mapped AllowAnonymous so an app with a global "require authenticated user" fallback policy does not answer its own probes with 401 and read as permanently down.

Quiet probe traffic — request logs for the health paths drop below the minimum level, so Kubernetes probes don't fill the log store with thousands of daily non-events. Failures still log: 5xx and unhandled exceptions stay at Error. Adjust with QuietRequestPaths.

Correlation — ObservabilityScope puts identifiers on every log event inside the scope and, when a span is active, as tags on it:

using var _ = ObservabilityScope.Begin(("ScanId", scanId), ("AccountId", accountId));

Custom spans and metrics — take OfbirdsTelemetry from DI (or OfbirdsTelemetry.Instance where DI is not available); its Source and Meter are the ones the pipeline listens to:

using var activity = telemetry.Source.StartActivity("scan.account");
var counter = telemetry.Meter.CreateCounter<long>("documents.routed");

Configuration

Everything is environment-driven — no endpoint is ever baked into the package.

Variable Effect
SEQ_URL Enables the Seq sink; also the fallback source for the OTLP trace endpoint (<host>:5341/ingest/otlp).
SEQ_API_KEY Optional Seq ingestion key.
OTEL_EXPORTER_OTLP_ENDPOINT OTLP base for traces; wins over the SEQ_URL fallback.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT Signal-specific traces endpoint; wins over everything.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT Metrics endpoint. Unset = no metrics exported.
APP_VERSION Release tag on every log and span. Falls back to the entry assembly's informational version, then dev.
LOG_LEVEL The floor every sink sees: Verbose/Trace, Debug, Information/Info, Warning/Warn, Error, Fatal/Critical (case-insensitive). Default Information. Wins over the app's own MinimumLevel, so an app can be turned up on a running pod without a code change. An unrecognised value falls back rather than silencing the app or drowning it.

Signal-specific variables accept either the full URL (…/v1/traces, per the OTel spec) or a base URL — the signal path is appended only when missing.

Unset everything and the service still runs, logging to console and file.

Credential redaction

Register every deployment credential that can occur in a log message, exception, or trace before the application begins handling work. The supplied source is emitted as the replacement label, so the telemetry remains useful without exposing the value:

builder.RedactConfigurationSecret("SEQ_API_KEY", "environment#SEQ_API_KEY");
builder.RedactConfigurationSecret("DATABASE_URL", "environment#DATABASE_URL", connectionString: true);
builder.RedactConfigurationSecrets(
    key => key.StartsWith("AI_KEY_", StringComparison.Ordinal),
    key => $"environment#{key}");

The boundary wraps every configured Serilog sink and the OTLP trace HTTP payload. It replaces the exact configured value (including its URL-escaped form) in rendered messages, structured values, exception text, trace/span attributes, event names, links, status messages, and resource strings. It does not guess values or patterns: secrets created outside configuration must be registered with SecretRedactionRegistry before they are emitted. Metrics are deliberately not altered by this trace-and-log boundary.

Trace payload compression is intentionally unsupported at this boundary: an OTLP trace request with a non-identity Content-Encoding is rejected before it can be sent. Keep OTEL_EXPORTER_OTLP_COMPRESSION unset for services using this package.

The SEQ_URL trace fallback assumes the Seq host also exposes OTLP on 5341, since it rewrites the port (http://seq.example.com:8080 → http://seq.example.com:5341/ingest/otlp/v1/traces). If Seq sits behind a reverse proxy, or its 5341 is not published, set OTEL_EXPORTER_OTLP_ENDPOINT explicitly — a wrong OTLP endpoint fails silently, it does not throw.

Shutdown: the logger is disposed with the host, which is what flushes Seq. Keep the usual try { app.Run(); } catch (ex) { Log.Fatal(ex, "..."); } finally { Log.CloseAndFlush(); } wrapper, but be aware that a fatal logged after host disposal only reaches the console — the network sinks are already closed. Log.CloseAndFlush() after host disposal is safe.

Turning an app up

The floor is a LoggingLevelSwitch, not a fixed level, so it can move while the process runs:

options.LevelSwitch.MinimumLevel = LogEventLevel.Debug;   // e.g. from an admin endpoint

That matters because raising the level to diagnose something must not require the restart that destroys the state being diagnosed. Until this existed the floor was hardcoded at Information, which meant every LogDebug and LogTrace an app wrote was discarded before reaching a sink — so writing them was pointless, and the only way to see inside a running app was to add LogInformation calls and redeploy.

Framework noise stays capped by the standard overrides (Microsoft.AspNetCore at Warning), so LOG_LEVEL=Debug surfaces the app's own detail rather than ASP.NET's.

Three things worth knowing before you reach for it:

  • The per-source overrides are absolute in both directions. LOG_LEVEL=Fatal still lets Microsoft.Hosting.Lifetime log at Information, and LOG_LEVEL=Verbose still caps Microsoft.AspNetCore at Warning. Move those with LevelOverrides when they are the thing you are trying to see.
  • LOG_LEVEL=Verbose brings probe traffic back. QuietRequestPaths drops health-probe request logs to Verbose on the assumption that Verbose reaches no sink — true at every other level. With 5s probes that is a few thousand extra events a day.
  • ConfigureSerilog runs last and can disconnect the switch. A cfg.MinimumLevel.Debug() in that hook wins over ControlledBy, and LOG_LEVEL then does nothing for that app.

Opt-outs

builder.AddOfbirdsObservability("my-app", o =>
{
    o.DisableFileSink = true;          // containers without a writable scratch volume
    o.DisableHealthEndpoints = true;   // host already owns /api/health
    o.DisableRequestLogging = true;
    o.LevelOverrides["Npgsql"] = LogEventLevel.Warning;
    o.ConfigureTracing = t => t.AddSource("HotChocolate");   // app-specific instrumentation
});

Two routes on the same path throw AmbiguousMatchException at request time — an app that already maps /api/health should register its probe as an IHealthCheck rather than keeping a parallel endpoint.

Conventions this package assumes

  • Three levels in practice. Information for lifecycle and business events, Warning for handled problems including failed input validation, Error for failures that need someone. Critical only when the process cannot continue.
  • Named placeholders, always: logger.LogInformation("Scan {ScanId} finished in {Elapsed}ms", id, ms). Never string interpolation — it destroys the structure Seq queries.
  • Exception first: logger.LogError(ex, "template", args).
  • Never log whole entities. Log identifiers and the few fields that matter; entity dumps are a volume and privacy problem in a shared log store.
  • Log where the failure is absorbed. A swallowed exception logs; a rethrown one does not (whoever handles it will log it) — no double reporting.
  • Correlate at the boundary. Open an ObservabilityScope where a unit of work starts so every downstream line carries its identifiers.

MIT licensed.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.0 552 9/10/2026
1.1.0 1,065 8/9/2026
1.0.0 134 8/9/2026