Skip to main content

arolariu.Backend.Common.Telemetry.Tracing

arolariu.Backend.Common​

arolariu.Backend.Common.Telemetry.Tracing Namespace​

Classes​

ActivityEnrichingProcessor Class​

A custom span processor that enriches all activities with consistent baseline attributes for improved filtering and correlation in Azure Application Insights.

public sealed class ActivityEnrichingProcessor : OpenTelemetry.BaseProcessor<System.Diagnostics.Activity>

Inheritance System.Object 🡒 OpenTelemetry.BaseProcessor<System.Diagnostics.Activity> 🡒 ActivityEnrichingProcessor

Example​

// Registration in TracingExtensions.cs
tracingOptions.AddProcessor(new ActivityEnrichingProcessor());

Remarks​

This processor is invoked for every span (activity) started in the application and adds:

  • Correlation IDs for cross-service tracing
  • Environment context for multi-environment filtering
  • Timestamp metadata for precise timing analysis
  • Request context extraction from Activity baggage

The processor runs before spans are exported to Azure Monitor, ensuring all telemetry contains the enrichment data needed for effective distributed trace analysis.

Constructors​

ActivityEnrichingProcessor() Constructor​

Initializes a new instance of the ActivityEnrichingProcessor class.

public ActivityEnrichingProcessor();

Fields​

ActivityEnrichingProcessor.CorrelationIdKey Field​

private const string CorrelationIdKey = "correlation.id";

Field Value​

System.String

ActivityEnrichingProcessor.EnvironmentNameKey Field​

private const string EnvironmentNameKey = "environment.name";

Field Value​

System.String

ActivityEnrichingProcessor.HostNameKey Field​

private const string HostNameKey = "host.name";

Field Value​

System.String

ActivityEnrichingProcessor.ParentSpanIdKey Field​

private const string ParentSpanIdKey = "parent.span_id";

Field Value​

System.String

ActivityEnrichingProcessor.ProcessIdKey Field​

private const string ProcessIdKey = "process.id";

Field Value​

System.String

ActivityEnrichingProcessor.RootTraceIdKey Field​

private const string RootTraceIdKey = "root.trace_id";

Field Value​

System.String

ActivityEnrichingProcessor.SpanDepthKey Field​

private const string SpanDepthKey = "span.depth";

Field Value​

System.String

ActivityEnrichingProcessor.StartTimestampUtcKey Field​

private const string StartTimestampUtcKey = "start.timestamp_utc";

Field Value​

System.String

ActivityEnrichingProcessor.ThreadIdKey Field​

private const string ThreadIdKey = "thread.id";

Field Value​

System.String

ActivityEnrichingProcessor._environmentName Field​

private readonly string _environmentName;

Field Value​

System.String

ActivityEnrichingProcessor._hostName Field​

private readonly string _hostName;

Field Value​

System.String

ActivityEnrichingProcessor._processId Field​

private readonly int _processId;

Field Value​

System.Int32

Methods​

ActivityEnrichingProcessor.CalculateSpanDepth(Activity) Method​

Calculates the depth of the current span in the trace hierarchy.

private static int CalculateSpanDepth(System.Diagnostics.Activity? activity);

Parameters​

activity System.Diagnostics.Activity

The activity to calculate depth for.

Returns​

System.Int32
The depth level (0 = root, 1 = first child, etc.).

ActivityEnrichingProcessor.OnEnd(Activity) Method​

Called when an activity is stopped. Can add final enrichment based on activity results.

public override void OnEnd(System.Diagnostics.Activity activity);

Parameters​

activity System.Diagnostics.Activity

The activity that was stopped.

Remarks​

OnEnd is called synchronously on the thread that stops the activity. This is the last chance to add attributes before the span is exported.

ActivityEnrichingProcessor.OnStart(Activity) Method​

Called when an activity is started. Enriches the activity with baseline context.

public override void OnStart(System.Diagnostics.Activity activity);

Parameters​

activity System.Diagnostics.Activity

The activity that was started.

Remarks​

OnStart is called synchronously on the thread that starts the activity. Keep processing minimal to avoid impacting application performance.

ActivityExtensions Class​

Provides extension methods for enriching System.Diagnostics.Activity instances with semantic attributes following OpenTelemetry conventions for improved distributed tracing visibility in Azure Application Insights.

public static class ActivityExtensions

Inheritance System.Object 🡒 ActivityExtensions

Example​

using var activity = InvoicePackageTracing.StartActivity("ReadInvoice", ActivityKind.Internal);
activity?
    .SetInvoiceContext(invoiceId, userId)
    .SetLayerContext("Foundation", "InvoiceStorageFoundationService")
    .RecordSuccess();

Remarks​

These extensions enable structured, consistent span enrichment across all application layers:

  • Endpoints (Server spans with HTTP context)
  • Services (Internal spans with business context)
  • Brokers (Client spans with database semantic conventions)

Following OpenTelemetry semantic conventions ensures proper correlation and visualization in Azure Application Insights Transaction Search and End-to-End Transaction views.

Fields​

ActivityExtensions.DbCollectionKey Field​

private const string DbCollectionKey = "db.collection.name";

Field Value​

System.String

ActivityExtensions.DbCosmosDbContainerKey Field​

private const string DbCosmosDbContainerKey = "db.cosmosdb.container";

Field Value​

System.String

ActivityExtensions.DbCosmosDbDatabaseKey Field​

private const string DbCosmosDbDatabaseKey = "db.cosmosdb.database_id";

Field Value​

System.String

ActivityExtensions.DbCosmosDbPartitionKeyKey Field​

private const string DbCosmosDbPartitionKeyKey = "db.cosmosdb.partition_key";

Field Value​

System.String

ActivityExtensions.DbCosmosDbRequestChargeKey Field​

private const string DbCosmosDbRequestChargeKey = "db.cosmosdb.request_charge";

Field Value​

System.String

ActivityExtensions.DbNameKey Field​

private const string DbNameKey = "db.name";

Field Value​

System.String

ActivityExtensions.DbOperationKey Field​

private const string DbOperationKey = "db.operation";

Field Value​

System.String

ActivityExtensions.DbStatementKey Field​

private const string DbStatementKey = "db.statement";

Field Value​

System.String

ActivityExtensions.DbSystemKey Field​

private const string DbSystemKey = "db.system";

Field Value​

System.String

ActivityExtensions.ErrorKey Field​

private const string ErrorKey = "error";

Field Value​

System.String

ActivityExtensions.ExceptionMessageKey Field​

private const string ExceptionMessageKey = "exception.message";

Field Value​

System.String

ActivityExtensions.ExceptionStacktraceKey Field​

private const string ExceptionStacktraceKey = "exception.stacktrace";

Field Value​

System.String

ActivityExtensions.ExceptionTypeKey Field​

private const string ExceptionTypeKey = "exception.type";

Field Value​

System.String

ActivityExtensions.InvoiceCurrencyKey Field​

private const string InvoiceCurrencyKey = "invoice.currency";

Field Value​

System.String

ActivityExtensions.InvoiceIdKey Field​

private const string InvoiceIdKey = "invoice.id";

Field Value​

System.String

ActivityExtensions.InvoiceItemCountKey Field​

private const string InvoiceItemCountKey = "invoice.item_count";

Field Value​

System.String

ActivityExtensions.InvoiceMerchantIdKey Field​

private const string InvoiceMerchantIdKey = "invoice.merchant_id";

Field Value​

System.String

ActivityExtensions.InvoiceTotalAmountKey Field​

private const string InvoiceTotalAmountKey = "invoice.total_amount";

Field Value​

System.String

ActivityExtensions.InvoiceUserIdKey Field​

private const string InvoiceUserIdKey = "invoice.user_id";

Field Value​

System.String

ActivityExtensions.MerchantIdKey Field​

private const string MerchantIdKey = "merchant.id";

Field Value​

System.String

ActivityExtensions.MerchantNameKey Field​

private const string MerchantNameKey = "merchant.name";

Field Value​

System.String

ActivityExtensions.OperationTypeKey Field​

private const string OperationTypeKey = "operation.type";

Field Value​

System.String

ActivityExtensions.ServiceComponentKey Field​

private const string ServiceComponentKey = "service.component";

Field Value​

System.String

ActivityExtensions.ServiceLayerKey Field​

private const string ServiceLayerKey = "service.layer";

Field Value​

System.String

ActivityExtensions.UserIdKey Field​

private const string UserIdKey = "user.id";

Field Value​

System.String

Methods​

ActivityExtensions.AddCustomEvent(this Activity, string, IEnumerable<KeyValuePair<string,object>>) Method​

Records a custom event on the activity timeline.

public static System.Diagnostics.Activity? AddCustomEvent(this System.Diagnostics.Activity? activity, string eventName, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string,object?>>? attributes=null);

Parameters​

activity System.Diagnostics.Activity

The activity to add the event to.

eventName System.String

The name of the event.

attributes System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<System.String,System.Object>>

Optional attributes to attach to the event.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

Remarks​

Events are useful for marking significant points in an operation's lifecycle, such as "validation.started", "external.service.called", or "cache.miss".

ActivityExtensions.RecordException(this Activity, Exception, bool) Method​

Records that the operation failed with an error status and exception details.

public static System.Diagnostics.Activity? RecordException(this System.Diagnostics.Activity? activity, System.Exception exception, bool escaped=true);

Parameters​

activity System.Diagnostics.Activity

The activity to mark as failed.

exception System.Exception

The exception that caused the failure.

escaped System.Boolean

Whether the exception escaped the span (default: true).

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

Remarks​

This method: 1. Sets the activity status to Error 2. Records the exception as an activity event (per OpenTelemetry spec) 3. Sets semantic exception attributes for filtering 4. Marks the span with the error flag for Application Insights

ActivityExtensions.RecordSuccess(this Activity, string) Method​

Records that the operation completed successfully with an OK status.

public static System.Diagnostics.Activity? RecordSuccess(this System.Diagnostics.Activity? activity, string? description=null);

Parameters​

activity System.Diagnostics.Activity

The activity to mark as successful.

description System.String

Optional description of the successful completion.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

ActivityExtensions.SetCosmosDbContext(this Activity, string, string, string, string) Method​

Sets Azure Cosmos DB specific context following OpenTelemetry database semantic conventions.

public static System.Diagnostics.Activity? SetCosmosDbContext(this System.Diagnostics.Activity? activity, string database, string container, string operation, string? partitionKey=null);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

database System.String

The Cosmos DB database name.

container System.String

The Cosmos DB container name.

operation System.String

The database operation type (e.g., "create", "read", "upsert", "delete", "query").

partitionKey System.String

Optional partition key value used for the operation.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

Remarks​

Following OpenTelemetry semantic conventions ensures proper dependency tracking and enables Application Insights to correctly categorize and display database operations. See: https://opentelemetry\.io/docs/specs/semconv/database/cosmosdb/

ActivityExtensions.SetCosmosDbRequestCharge(this Activity, double) Method​

Records the Cosmos DB request charge (RUs consumed) for cost analysis.

public static System.Diagnostics.Activity? SetCosmosDbRequestCharge(this System.Diagnostics.Activity? activity, double requestCharge);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

requestCharge System.Double

The request charge in Request Units (RU).

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

Remarks​

Tracking RU consumption per operation enables cost optimization analysis and identification of expensive database operations.

ActivityExtensions.SetDbStatement(this Activity, string) Method​

Sets a sanitized database query statement for debugging purposes.

public static System.Diagnostics.Activity? SetDbStatement(this System.Diagnostics.Activity? activity, string statement);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

statement System.String

The query statement (should be parameterized, no sensitive data).

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

Remarks​

Only include parameterized queries without sensitive data values. This aids in debugging slow or problematic queries.

ActivityExtensions.SetInvoiceContext(this Activity, Guid, Nullable<Guid>) Method​

Sets invoice-specific context for the activity, enabling invoice-based filtering and correlation.

public static System.Diagnostics.Activity? SetInvoiceContext(this System.Diagnostics.Activity? activity, System.Guid invoiceId, System.Nullable<System.Guid> userId=null);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

invoiceId System.Guid

The unique identifier of the invoice being processed.

userId System.Nullable<System.Guid>

Optional user identifier associated with the invoice.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

Remarks​

Invoice context enables searching for all operations related to a specific invoice in Application Insights using custom dimension filters.

ActivityExtensions.SetInvoiceDetails(this Activity, Guid, Guid, Nullable<Guid>, Nullable<int>, Nullable<decimal>, string) Method​

Sets detailed invoice information for comprehensive trace enrichment.

public static System.Diagnostics.Activity? SetInvoiceDetails(this System.Diagnostics.Activity? activity, System.Guid invoiceId, System.Guid userId, System.Nullable<System.Guid> merchantId=null, System.Nullable<int> itemCount=null, System.Nullable<decimal> totalAmount=null, string? currency=null);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

invoiceId System.Guid

The invoice identifier.

userId System.Guid

The user identifier.

merchantId System.Nullable<System.Guid>

The merchant identifier.

itemCount System.Nullable<System.Int32>

The number of items in the invoice.

totalAmount System.Nullable<System.Decimal>

The total amount of the invoice.

currency System.String

The currency code (e.g., "USD", "EUR", "RON").

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

ActivityExtensions.SetLayerContext(this Activity, string, string) Method​

Sets the architectural layer context for the activity, enabling hierarchical trace visualization.

public static System.Diagnostics.Activity? SetLayerContext(this System.Diagnostics.Activity? activity, string layer, string component);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich. If null, no operation is performed.

layer System.String

The architectural layer name (e.g., "Endpoint", "Processing", "Orchestration", "Foundation", "Broker").

component System.String

The component or service name within the layer.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining, or null if input was null.

Remarks​

Layer information enables filtering and grouping spans by architectural tier in Application Insights. This is particularly useful for identifying bottlenecks at specific layers of the application.

ActivityExtensions.SetMerchantContext(this Activity, Guid, string) Method​

Sets merchant-specific context for the activity.

public static System.Diagnostics.Activity? SetMerchantContext(this System.Diagnostics.Activity? activity, System.Guid merchantId, string? merchantName=null);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

merchantId System.Guid

The merchant identifier.

merchantName System.String

Optional merchant name for display purposes.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

ActivityExtensions.SetOperationType(this Activity, string) Method​

Sets the operation type for the activity, categorizing the kind of work being performed.

public static System.Diagnostics.Activity? SetOperationType(this System.Diagnostics.Activity? activity, string operationType);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

operationType System.String

The operation type (e.g., "CRUD.Create", "CRUD.Read", "Analysis", "Validation").

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

ActivityExtensions.SetUserContext(this Activity, Guid) Method​

Sets user context for the activity, enabling user-based trace filtering.

public static System.Diagnostics.Activity? SetUserContext(this System.Diagnostics.Activity? activity, System.Guid userId);

Parameters​

activity System.Diagnostics.Activity

The activity to enrich.

userId System.Guid

The user identifier.

Returns​

System.Diagnostics.Activity
The enriched activity for method chaining.

ActivityExtensions.StartActivityWithLink(this ActivitySource, string, ActivityContext, ActivityKind) Method​

Creates a new activity with a link to a parent trace context, useful for async/batch operations.

public static System.Diagnostics.Activity? StartActivityWithLink(this System.Diagnostics.ActivitySource source, string name, System.Diagnostics.ActivityContext linkedContext, System.Diagnostics.ActivityKind kind=System.Diagnostics.ActivityKind.Internal);

Parameters​

source System.Diagnostics.ActivitySource

The activity source to create the activity from.

name System.String

The name of the new activity.

linkedContext System.Diagnostics.ActivityContext

The activity context to link to.

kind System.Diagnostics.ActivityKind

The kind of activity (default: Internal).

Returns​

System.Diagnostics.Activity
A new activity with the specified link.

Remarks​

Links are useful when an operation is triggered by multiple parent operations or when processing batched items that originated from different traces.

ActivityGenerators Class​

Provides centralized activity sources for distributed tracing across application components. This class defines ActivitySource instances that enable OpenTelemetry tracing throughout the system.

public static class ActivityGenerators

Inheritance System.Object 🡒 ActivityGenerators

Example​

// Creating a custom activity
using var activity = ActivityGenerators.CommonPackageTracing.StartActivity("ConfigurationLoad");
activity?.SetTag("config.source", "KeyVault");
// Perform configuration loading
activity?.SetStatus(ActivityStatusCode.Ok);

Remarks​

Activity sources are used to create spans and traces for: - Cross-service request correlation - Performance monitoring and bottleneck identification - Distributed system debugging and troubleshooting - Service dependency mapping and analysis

Constructors​

ActivityGenerators() Constructor​

static ActivityGenerators();

Fields​

ActivityGenerators.AuthPackageTracing Field​

Activity source for the Authentication package operations. Used to trace authentication, authorization, and security-related operations.

public static readonly ActivitySource AuthPackageTracing;

Field Value​

System.Diagnostics.ActivitySource

Remarks​

This activity source covers: - User authentication and token validation - Authorization policy evaluation - JWT token generation and verification - Security-related middleware operations

ActivityGenerators.CommonPackageTracing Field​

Activity source for the Common package operations. Used to trace shared infrastructure components including configuration, validation, and Key Vault operations.

public static readonly ActivitySource CommonPackageTracing;

Field Value​

System.Diagnostics.ActivitySource

Remarks​

This activity source covers: - Configuration loading and management - Key Vault secret retrieval operations - Validation and utility operations - Shared service interactions

ActivityGenerators.CorePackageTracing Field​

Activity source for the Core package operations. Used to trace application startup, middleware pipeline, and general API operations.

public static readonly ActivitySource CorePackageTracing;

Field Value​

System.Diagnostics.ActivitySource

Remarks​

This activity source covers: - Application startup and configuration - HTTP request processing and middleware operations - Swagger documentation generation - General API infrastructure operations

ActivityGenerators.InvoicePackageTracing Field​

Activity source for the Invoices domain package operations. Used to trace business operations related to invoice processing and management.

public static readonly ActivitySource InvoicePackageTracing;

Field Value​

System.Diagnostics.ActivitySource

Remarks​

This activity source covers: - Invoice creation, processing, and management - Business rule validation and enforcement - Data persistence and retrieval operations - Domain-specific service interactions

TracingExtensions Class​

Provides extension methods for configuring OpenTelemetry distributed tracing with Azure Monitor integration. This class sets up comprehensive request tracing across application layers and external dependencies.

public static class TracingExtensions

Inheritance System.Object 🡒 TracingExtensions

Example​

// Usage in Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.AddOTelTracing();

Remarks​

This extension configures: - ASP.NET Core instrumentation for HTTP request tracing - HTTP client instrumentation for outbound dependency tracking - Entity Framework Core instrumentation for database operation tracing - Azure Monitor exporter for distributed trace visualization

Methods​

TracingExtensions.AddOTelTracing(this WebApplicationBuilder) Method​

Configures OpenTelemetry distributed tracing with comprehensive instrumentation and Azure Monitor export. This method enables end-to-end request tracing across all application layers and external dependencies.

public static void AddOTelTracing(this Microsoft.AspNetCore.Builder.WebApplicationBuilder builder);

Parameters​

builder Microsoft.AspNetCore.Builder.WebApplicationBuilder

The Microsoft.AspNetCore.Builder.WebApplicationBuilder to configure with OpenTelemetry tracing.

Exceptions​

System.ArgumentNullException
Thrown when builder is null.

Remarks​

This method configures tracing instrumentation for: - ASP.NET Core: HTTP request spans with timing, status codes, and routing information - HTTP Client: Outbound request tracing for dependency monitoring and performance analysis - Entity Framework Core: Database query tracing with SQL execution times and connection details - Console export during debugging for immediate trace visibility - Azure Monitor export for production distributed tracing and correlation - Managed Identity authentication for secure Azure integration

// was this page useful?