Elven.Observability.Core 0.1.0

Elven Observability .NET

Production-grade OpenTelemetry bootstrap for modern .NET services on the Elven Observability LGTM stack: Loki, Grafana, Tempo, and Mimir.

This distribution wraps the official OpenTelemetry .NET SDK and auto-instrumentation. It does not replace OTel. Elven mode always configures traces, metrics, and logs.

Install

dotnet add package Elven.Observability

ASP.NET Core

var builder = WebApplication.CreateBuilder(args);

builder.AddElvenObservability(options =>
{
    options.ServiceName = "billing-api";
    options.ServiceNamespace = "payments";
    options.Endpoint = new Uri("https://otlp.elven.io");
    options.TenantId = "acme";
    options.ApiKey = builder.Configuration["ELVEN_API_KEY"];
    options.SamplingRatio = 1.0;
});

var app = builder.Build();
app.UseElvenObservability();
app.MapElvenObservabilityHealthCheck();
app.Run();

Generic Host / Worker

var builder = Host.CreateApplicationBuilder(args);
builder.AddElvenObservability();
await builder.Build().RunAsync();

Console / No Host

await using var observability = ElvenObservability.Initialize(options =>
{
    options.ServiceName = "batch-job";
    options.TenantId = "acme";
});

using var activity = ElvenTelemetry.ActivitySource.StartActivity("job.run");
ElvenTelemetry.Meter.CreateCounter<long>("jobs.started").Add(1);
observability.LoggerFactory.CreateLogger("Batch.Job").LogInformation("Job started.");
await observability.ForceFlushAsync();

Auto-Instrumentation

./scripts/install.sh
. "$HOME/.otel-dotnet-auto/instrument.sh"

export OTEL_DOTNET_AUTO_PLUGINS="Elven.Observability.AutoInstrumentation.ElvenPlugin, Elven.Observability.AutoInstrumentation"
export OTEL_SERVICE_NAME=billing-api
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.elven.io
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export ELVEN_TENANT_ID=acme
export ELVEN_API_KEY=...

dotnet Billing.Api.dll

OTEL_TRACES_EXPORTER=none, OTEL_METRICS_EXPORTER=none, OTEL_LOGS_EXPORTER=none, and OTEL_TRACES_SAMPLER=always_off are rejected in Elven mode. Logs, metrics, and traces are always on.

Docker Layer

FROM mcr.microsoft.com/dotnet/aspnet:10.0

COPY --from=elvenobs/dotnet-instrumentation:latest /otel /otel

ENV CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318} \
    CORECLR_PROFILER_PATH=/otel/current/OpenTelemetry.AutoInstrumentation.Native.so \
    DOTNET_ADDITIONAL_DEPS=/otel/AdditionalDeps \
    DOTNET_SHARED_STORE=/otel/store \
    DOTNET_STARTUP_HOOKS=/otel/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll \
    OTEL_DOTNET_AUTO_HOME=/otel \
    OTEL_DOTNET_AUTO_PLUGINS="Elven.Observability.AutoInstrumentation.ElvenPlugin, Elven.Observability.AutoInstrumentation" \
    OTEL_SERVICE_NAME=minha-app \
    OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.elven.io \
    OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
    OTEL_TRACES_EXPORTER=otlp \
    OTEL_METRICS_EXPORTER=otlp \
    OTEL_LOGS_EXPORTER=otlp \
    ELVEN_TENANT_ID=acme

COPY . /app
ENTRYPOINT ["dotnet", "/app/MyApp.dll"]

Environment Variables

Elven supports standard OTel variables plus these extensions:

• ELVEN_TENANT_ID: mapped to x-scope-orgid
• ELVEN_API_KEY: mapped to Authorization: Bearer ...
• ELVEN_ENVIRONMENT: mapped to deployment.environment.name
• ELVEN_REGION: mapped to elven.region
• ELVEN_DEBUG: enables verbose internal diagnostics

Core OTel variables:

• OTEL_SERVICE_NAME
• OTEL_SERVICE_VERSION
• OTEL_RESOURCE_ATTRIBUTES
• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_EXPORTER_OTLP_PROTOCOL=grpc|http/protobuf
• OTEL_EXPORTER_OTLP_HEADERS
• OTEL_TRACES_SAMPLER
• OTEL_TRACES_SAMPLER_ARG
• OTEL_TRACES_EXPORTER=otlp
• OTEL_METRICS_EXPORTER=otlp
• OTEL_LOGS_EXPORTER=otlp

Coverage

• Traces: ASP.NET Core, HttpClient, gRPC client, SQL Client, EF Core, MongoDB source registration, RabbitMQ/Kafka/MassTransit source registration, AWS/Azure source registration, manual ActivitySource.
• Metrics: runtime, process, ASP.NET Core/Kestrel, HttpClient, DNS/TLS/connection meters, Elven internal metrics, trace-based exemplars.
• Logs: ILogger OTLP exporter, formatted message, scopes, state values, automatic trace/span correlation.
• Resources: service namespace/version/instance, deployment.environment.name, host, container, Kubernetes, process/runtime, tenant, region.
• Error mapping: cancellation, timeout, validation, auth, user input, HTTP 4xx/5xx, gRPC status codes, DNS, connection refused, network, DB/provider, startup misconfiguration, unhandled exceptions.

Development

dotnet restore
dotnet build Elven.Observability.sln -c Release
dotnet test Elven.Observability.sln -c Release
dotnet run -c Release --project tests/Elven.Observability.Benchmarks

Native AOT:

dotnet publish samples/NativeAot.WebApi/NativeAot.WebApi.csproj -c Release -r linux-x64

Build the auto-instrumentation layer:

docker buildx build \
  -f docker/auto-instrumentation/Dockerfile \
  --platform linux/amd64,linux/arm64 \
  -t elvenobs/dotnet-instrumentation:latest .

Run the local LGTM stack and send the samples to it:

docker compose -f docker-compose.lgtm.yml up -d
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_SERVICE_NAME=elven-local-sample
dotnet run --project samples/AspNetCore.WebApi/AspNetCore.WebApi.csproj

Open Grafana at http://localhost:3000; the bundled LGTM image receives traces, metrics, and logs over OTLP on 4317 and 4318.

References

• OpenTelemetry .NET SDK 1.15.3
• OpenTelemetry .NET AutoInstrumentation 1.15.0
• OpenTelemetry semantic conventions 1.41.0
• .NET 8, .NET 9, and .NET 10