Momentum.OpenTelemetry 0.9.0

Momentum.OpenTelemetry

Optional OpenTelemetry SDK integration for Momentum. It registers Momentum's activity source and meter, common ASP.NET Core instrumentation, the ILogger provider, and OTLP exporters without adding an exporter dependency to the core runtime packages.

builder.Services.AddMomentumOpenTelemetry(options =>
{
    options.ServiceName = builder.Environment.ApplicationName;
    options.DeploymentEnvironment = builder.Environment.EnvironmentName;
});

Configure the collector with standard variables; no Alloy-specific application configuration is required:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
dotnet run

Set ExportOtlp = false and use ConfigureTracing, ConfigureMetrics, and ConfigureLogging to install different exporters. The callbacks can also add instrumentation, processors, views, and sampling configuration.

Structured logs and safety

The integration exports the original message template and its values as separate attributes, includes ILogger scopes, and lets the SDK attach the active trace and span IDs. Momentum execution scopes add only operational fields: step name, workflow ID, event type, delivery kind, retry attempt, and tenant ID.

OTLP filtering is independent of console logging:

builder.Services.AddMomentumOpenTelemetry(options =>
{
    options.MinimumExportedLogLevel = LogLevel.Warning;
    options.LogFilter = (category, level) =>
        category?.StartsWith("Momentum", StringComparison.Ordinal) == true
        || level >= LogLevel.Error;
});

Sensitive structured attributes are redacted by default. Built-in name rules cover credentials, passwords, tokens, authorization/cookies, connection strings, event payload/data, decrypted plaintext, email/phone/name/address, and government IDs. Extend them without putting secret values in configuration:

options.RedactedLogAttributeNames.Add("customer.tax_number");
options.IsSensitiveLogAttribute = name => name.EndsWith(".private", StringComparison.Ordinal);

Do not log whole events or DTOs. Redaction is defense in depth for named structured fields; it cannot reliably identify secrets embedded in free-form strings or exception messages. Exception objects and their stack traces remain available for diagnostics.

The OTLP exporter uses the SDK's bounded background batch processor by default. When its queue is full or the collector is unavailable, records may be dropped; step execution is never made to wait for network export. ConfigureLogging can replace or add processors, so production exporters should retain this asynchronous behavior. The same rule applies to ConfigureTracing; metrics use a periodic background reader. Do not install simple/synchronous network exporters on an application hot path.

PostgreSQL workflow-step records and the back-office Logs view remain execution records. Loki contains diagnostic ILogger records; it is a separate stream and is not the source of truth for workflow state, retry, or dead-letter status.

For a local collector, expose an OTLP endpoint and start the application with OpenTelemetry__Enabled=true and OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317.

Momentum respects the configured sampler. Trace and span IDs in PostgreSQL are observability metadata and may be absent when no activity was created; workflow IDs, tenant IDs, execution status, and retry/dead-letter state are persisted independently of trace sampling. W3C propagation also remains functional for unsampled parent contexts, so sampling never changes delivery or workflow behavior.

Runtime metrics

AddMomentumOpenTelemetry subscribes to the Momentum.Runtime meter and exports the native instruments below through the configured metrics pipeline:

Prometheus/Mimir may append conventional _total, _seconds, or unit suffixes during translation. Query the exported names shown by your backend.

Cardinality policy

Runtime-owned attributes (outcome, transport, delivery, reason, source, queue, backlog, and state) are closed sets. momentum.step.type is one of api, internal-event, external-event, or cron. event.type is the CLR type name of an application event and is controlled by the deployed event catalog.

Metric attributes never contain tenant IDs, workflow IDs, trace/span IDs, event IDs, step names, exception types/messages, payloads, or other customer data. A contract test enforces this. Keep the deployed event catalog below 200 types per service; the remaining dimensions produce fewer than 100 runtime-owned series before backend histogram buckets.

Step count, duration, and event flow can also be calculated from sampled spans. Native metrics remain necessary because counters are unsampled and queue depth, backlog, active work, drain state, and cluster role are point-in-time process state that no completed span can represent.

Compatibility and release policy

This package is optional and versioned with Momentum. Its minimum OpenTelemetry dependency versions are the floors recorded in the NuGet package; later compatible 1.x versions may be resolved by the application. Validate a dependency upgrade with the resilience and instrumentation-contract tests before deployment.

Momentum propagates standard W3C traceparent/tracestate. Current runtime versions also read legacy stored trace/span IDs when a full trace parent is absent, allowing a rolling mixed-version deployment. A mixed rollout may temporarily produce incomplete traces but must not affect execution, retry, dead-letter, replay, relay, or workflow state. PostgreSQL records are always authoritative; telemetry is never replayed back into Momentum.

Before production deployment, verify that collector loss, slow export, and queue saturation do not block application work; select an explicit sampling policy; review custom log attributes for sensitive data; and alert on exporter failures and dropped records. Keep bounded asynchronous processors on network exporters and treat telemetry as diagnostic data rather than the source of truth for workflow state.

License

Momentum is free for qualifying non-commercial open-source projects. Commercial use requires a separate written license agreement. The complete terms are included in the package.