eeCLOUD.OpenTelemetry 1.0.0

eeCLOUD.OpenTelemetry

Version 1.0.0 provides optional OpenTelemetry integration for eeCLOUD 4.3.1 and .NET 8 or later. This integration package is versioned independently of the eeCLOUD core package. Create one eeTelemetry service for the host, then inject it into your Application instances alongside the optional eeCACHE singleton. The core eeCLOUD package has no OpenTelemetry dependency.

Installation

dotnet add package eeCLOUD.OpenTelemetry --version 1.0.0

The package brings in eeCLOUD and the OpenTelemetry OTLP exporter. All eeCLOUD types below are in the eeCLOUD namespace.

WebAPI / dependency injection

In Program.cs, with config containing your existing eeCLOUD database configuration:

using eeCLOUD;

builder.Services.AddSingleton<IeeCACHE, eeCACHE>();
builder.Services.AddSingleton<IeeTelemetry>(sp => new eeTelemetry(new()
{
    ServiceName = "MyProject.API",
    InstanceName = "primary-db",
    Endpoint = "http://localhost:4317",
    Protocol = TelemetryProtocol.OtlpGrpc,
    Metrics = true,
    Tracing = true,
    ExportIntervalMilliseconds = 15000
}));

builder.Services.AddSingleton<Application>(sp => new Application(
    config,
    sp.GetRequiredService<IeeCACHE>(),
    sp.GetRequiredService<IeeTelemetry>()));

var app = builder.Build();

// Start providers before the first request, including when adding HTTP instrumentation.
_ = app.Services.GetRequiredService<Application>();

// Map your endpoints / controllers here.
app.Run();

No OTEL environment variables are required. DI owns services created by these factories and disposes them at shutdown. Each Application disposes only its own observation registration; the shared service owns the providers and exporters. Do not also call EnableTelemetry() on an already observed Application.

Without cache:

using var telemetry = new eeTelemetry(new() { ServiceName = "MyWorker" });
using var db = new Application(config, telemetry: telemetry);

Override an instance label or disable a signal for a particular instance:

using var db = new Application(config, telemetry: telemetry, telemetryOptions: new()
{
    InstanceName = "background-jobs",
    Tracing = false
});

An instance cannot enable a signal disabled on the shared service. Names should be stable workload labels, never request IDs or customer IDs.

appsettings.json and IIS

Options have public setters and can be bound using the host's configuration binder:

{
  "EeCloudTelemetry": {
    "ServiceName": "MyProject.API",
    "InstanceName": "primary-db",
    "Endpoint": "http://localhost:4317",
    "Protocol": "OtlpGrpc",
    "Metrics": true,
    "Tracing": true,
    "ExportIntervalMilliseconds": 15000,
    "ExportTimeoutMilliseconds": 3000
  }
}

Replace the IeeTelemetry registration above with:

builder.Services.AddSingleton<IeeTelemetry>(sp => new eeTelemetry(
    builder.Configuration.GetSection("EeCloudTelemetry")
        .Get<TelemetryExporterOptions>() ?? new()));

This works for a WebAPI hosted by IIS; no changes to web.config are needed for these exporter settings. Options are snapshotted when the singleton is constructed; restart the application to apply changes. Credentials in Headers should come from host secrets, not committed configuration.

Aspire Dashboard

Run an Aspire standalone dashboard, for example with an installed Aspire CLI:

aspire dashboard run

Use Endpoint = "http://localhost:4317" and OtlpGrpc when the WebAPI and dashboard run on the same host. The browser UI is at http://localhost:18888; use the login link printed by the dashboard. When the receiver is on another machine, configure its reachable address instead of localhost.

Generate normal eeCLOUD calls, then inspect eeCLOUD.* spans under Traces and eecloud.* instruments under Metrics. Metrics export every 15 seconds by default; traces are batched independently. Aspire stores telemetry in memory, with bounded retention and loss on dashboard restart. Configure process supervision separately if the dashboard must keep running after an administrator logs out of Windows.

HTTP transport, Prometheus and other OTLP receivers

OtlpHttpProtobuf appends /v1/metrics and /v1/traces to the base Endpoint, preserving a prefix such as /otlp. Its default base endpoint is http://localhost:4318; the gRPC default is http://localhost:4317.

MetricsEndpoint and TracesEndpoint are full signal URLs and override the base endpoint without appending a path. For a Prometheus receiver enabled with --web.enable-otlp-receiver, use metrics only:

new TelemetryExporterOptions
{
    ServiceName = "MyProject.API",
    Protocol = TelemetryProtocol.OtlpHttpProtobuf,
    MetricsEndpoint = "http://localhost:9090/api/v1/otlp/v1/metrics",
    Metrics = true,
    Tracing = false
};

Grafana Cloud and compatible collectors can use their OTLP base URL and Headers = "Authorization=..." supplied by the host. Grafana's web UI itself is not an OTLP receiver. Metrics use cumulative temporality. Explicit exporter options take precedence over the standard OTEL endpoint/protocol/header variables.

HTTP request correlation

By default this package exports eeCLOUD operations only. To also export ASP.NET Core request spans and metrics from the same providers, install OpenTelemetry.Instrumentation.AspNetCore and use the optional builder callbacks:

using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

builder.Services.AddSingleton<IeeTelemetry>(sp => new eeTelemetry(
    new() { ServiceName = "MyProject.API", Endpoint = "http://localhost:4317" },
    configureMetrics: metrics => metrics.AddAspNetCoreInstrumentation(),
    configureTracing: tracing => tracing.AddAspNetCoreInstrumentation()));

Start the singleton before requests arrive, as in the first example. eeCLOUD spans inherit the current request's trace context. TraceSampleRatio controls sampling for root traces (default 1); parent sampling decisions are respected. Metrics do not depend on trace sampling. This package does not configure ILogger export.

Ownership and existing OpenTelemetry pipelines

Use one eeTelemetry singleton per process. The eeCLOUD Meter and ActivitySource are process-wide: the service collects all enabled eeCLOUD instances in the process, including instances enabled manually. It is not a per-instance routing mechanism. Multiple services or another provider listening to the same sources can duplicate export. If the host already owns its OpenTelemetry providers, keep using Application.EnableTelemetry() and register eeCLOUD with those providers instead.

An Application can only have one active registration. Disposing it releases the registration acquired through constructor injection; it does not stop the shared exporters, dispose the supplied cache, or affect another Application. Existing manual EnableTelemetry() handles retain their explicit, caller-owned lifetime. Operations already observed finish normally after registration disposal.

Stop and await application work before disposing the singleton. Provider disposal exports pending data and releases resources; ForceFlush() also supports an explicit flush, with the configured timeout per provider and a boolean result. Exporter outages do not change database results and can lose telemetry; this is not a durable delivery queue. Calls to Observe or ForceFlush after service disposal throw ObjectDisposedException. Disposing the service twice is safe.

Signal semantics

• eecloud.operations: completed public calls, grouped by operation, instance and outcome.
• eecloud.operation.duration: whole-call duration in seconds, including cache and graph work.
• eecloud.operations.active: calls in progress, without an outcome dimension.
• eecloud.response.records: response entries, not affected SQL rows or billing totals.

unsuccessful means Memory.result == false, including missing data. exception means an exception escaped the public operation. completed is used for scalar APIs whose return values do not prove backend success. Payloads, credentials, query values and Application/Memory names are not included in eeCLOUD signals.

References

References: Aspire standalone, Prometheus OTLP, OpenTelemetry OTLP exporter.

Made with love ❤️ by Giovanni Petruzzellis