Elven.Observability.Instrumentation.EntityFrameworkCore 0.1.3

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 OpenTelemetry .NET AutoInstrumentation. It does not replace OpenTelemetry. Elven mode always configures traces, metrics, and logs.

Architecture

Applications send OTLP to a Collector deployed in the customer environment. The customer-side Collector then forwards telemetry to the Elven Observability backends.

.NET app
  -> OTLP gRPC or HTTP/protobuf
  -> customer-side OpenTelemetry Collector
  -> Elven Observability backend
  -> Tempo, Mimir, Loki, Grafana

The package default endpoint is http://localhost:4317, which is the common local/sidecar Collector endpoint. In production, set OTEL_EXPORTER_OTLP_ENDPOINT or ELVEN_OTLP_ENDPOINT to the customer Collector address.

Keep Elven backend credentials in the Collector, not in the application. In the recommended Collector path, the app only needs to know where the customer-side Collector is. The Collector is responsible for adding Authorization: Bearer ... and x-scope-orgid when forwarding to Elven Observability.

Recommended Path

Start with the lowest-friction rollout path, then move down only when the service needs code-level customization.

Docker Zero-Code

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

COPY --from=elvenobservability/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_TRACES_EXPORTER=otlp \
    OTEL_METRICS_EXPORTER=otlp \
    OTEL_LOGS_EXPORTER=otlp \
    OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
    OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT=true \
    OTEL_DOTNET_AUTO_ENTITYFRAMEWORKCORE_SET_DBSTATEMENT_FOR_TEXT=true \
    OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT=true

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

Runtime configuration:

docker run --rm \
  -e OTEL_SERVICE_NAME=billing-api \
  -e OTEL_SERVICE_VERSION=1.0.0 \
  -e ELVEN_SERVICE_NAMESPACE=payments \
  -e ELVEN_ENVIRONMENT=production \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability.svc.cluster.local:4317 \
  -e OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
  -e OTEL_TRACES_EXPORTER=otlp \
  -e OTEL_METRICS_EXPORTER=otlp \
  -e OTEL_LOGS_EXPORTER=otlp \
  my-app:latest

Database statements are collected by default when the underlying .NET instrumentation supports them. Elven redacts db.statement, db.query.text, and database query parameter attributes to [REDACTED] before export, while keeping safe attributes such as db.query.summary, db.operation.name, db.system.name, duration, status, and errors.

Process Zero-Code

./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=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

dotnet Billing.Api.dll

Programmatic Setup

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("http://localhost:4317");
    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";
});

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();

Business Telemetry

Install:

dotnet add package Elven.Observability

Use business spans and metrics when the service needs journey-level observability:

using Elven.Observability.Business;
using Elven.Observability.Business.AirTravel;

using var op = ElvenAirTravel.StartAvailability(
    provider: "sabre",
    source: "sabre_bfm",
    correlationId: correlationId);

op.SetStatus("success");
ElvenBusinessMetrics.OperationTotal.Add(1, op.Tags(status: "success"));
ElvenBusinessMetrics.OperationDuration.Record(elapsed, op.Tags(status: "success"));

Business metric labels are intentionally low-cardinality: client, business_context, journey, business.operation, provider, source, supplier, product, status, result, and error.category. Reservation ids, PNRs, tickets, sessions, passengers, and documents must stay out of metric labels.

See Business telemetry and Business telemetry PT-BR.

Environment Variables

Elven supports standard OpenTelemetry variables plus Elven extensions.

Recommended app-to-Collector variables:

• ELVEN_ENVIRONMENT: mapped to deployment.environment.name
• ELVEN_REGION: mapped to elven.region
• ELVEN_DEBUG: enables verbose internal diagnostics
• ELVEN_REDACTION_MODE=default|none: default keeps PCI/LGPD redaction enabled
• ELVEN_LOG_BODY_MODE=redacted|raw: default redacts log bodies structurally
• ELVEN_MAX_LOG_BODY_CHARS: default 200000
• ELVEN_ALLOWED_RAW_ATTRIBUTES: exact attribute allowlist for controlled troubleshooting

Direct-to-Elven variables, only when the application exports straight to an Elven OTLP gateway instead of a customer-side Collector:

• ELVEN_TENANT_ID: mapped to x-scope-orgid
• ELVEN_API_KEY: mapped to Authorization: Bearer ...

When using the customer-side Collector, configure tenant and API key in the Collector exporter instead. If the application still needs tenant metadata as a resource attribute, prefer OTEL_RESOURCE_ATTRIBUTES=elven.tenant.id=... so the app does not emit backend authentication headers.

Core OpenTelemetry 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

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.

For http/protobuf, OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 is treated as a base endpoint. Elven expands it to /v1/traces, /v1/metrics, and /v1/logs per signal. If you provide a path explicitly, that path is preserved.

Log bodies are redacted by default with XML/JSON-aware structural redaction. Safe trace context fields such as trace_id, span_id, traceparent, and correlation_id are preserved.

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 tests/Elven.Observability.UnitTests/Elven.Observability.UnitTests.csproj -c Release
dotnet pack Elven.Observability.sln -c Release -o artifacts/packages

Native AOT:

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

Strict trimming:

dotnet publish samples/NativeAot.WebApi/NativeAot.WebApi.csproj -c Release -r linux-x64 -p:PublishAot=false -p:PublishTrimmed=true -p:SelfContained=true

The facade package is optimized for convenience and broad instrumentation coverage. For strict Native AOT or trim-clean services, compose the lean core/exporter packages as shown in the Native AOT sample and avoid optional instrumentation modules that are not trim-clean in the upstream OpenTelemetry ecosystem.

Build the auto-instrumentation layer:

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

Build the OpenTelemetry Operator init-container image:

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

Operator setup lives in k8s/otel-operator-instrumentation.yaml. The image follows the OTel Operator .NET contract by exposing /autoinstrumentation with linux-x64 and linux-musl-x64 payloads plus the Elven plugin in /autoinstrumentation/plugins.

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