WorkflowForge.Extensions.Observability.OpenTelemetry 2.1.1

WorkflowForge.Extensions.Observability.OpenTelemetry

Distributed tracing extension for WorkflowForge with OpenTelemetry integration for comprehensive observability.

Dependency Isolation

This extension internalizes OpenTelemetry with ILRepack. This means:

• Reduced dependency conflicts for OpenTelemetry
• Public APIs stay WorkflowForge/BCL only
• Microsoft/System assemblies remain external

Installation

dotnet add package WorkflowForge.Extensions.Observability.OpenTelemetry

Requires: .NET Standard 2.0 or later

Quick Start

using WorkflowForge;
using WorkflowForge.Extensions.Observability.OpenTelemetry;

// Create foundry and enable OpenTelemetry
using var foundry = WorkflowForge.CreateFoundry("TracedWorkflow");
foundry.EnableOpenTelemetry(new WorkflowForgeOpenTelemetryOptions
{
    ServiceName = "OrderService",
    EnableTracing = true,
    EnableMetrics = true
});

var smith = WorkflowForge.CreateSmith();
var workflow = WorkflowForge.CreateWorkflow("TracedWorkflow")
    .AddOperation(new ActionWorkflowOperation("ProcessOrder", async (input, foundry, ct) => { /* ... */ }))
    .Build();

// Operations will create spans and record metrics
await smith.ForgeAsync(workflow, foundry);

// Access the OpenTelemetry service for custom instrumentation
var otelService = foundry.GetOpenTelemetryService();
using var activity = foundry.StartActivity("CustomOperation");

Key Features

• Distributed Tracing: Track workflows across services
• Automatic Spans: Operation-level span creation
• Context Propagation: W3C Trace Context support
• Multiple Exporters: Jaeger, Zipkin, Console, OTLP
• Rich Metadata: Operation names, durations, results
• Full OpenTelemetry API: Access entire ecosystem

Configuration

Programmatic

using var foundry = WorkflowForge.CreateFoundry("TracedWorkflow");

// Enable with custom options
foundry.EnableOpenTelemetry(new WorkflowForgeOpenTelemetryOptions
{
    ServiceName = "MyService",
    EnableTracing = true,
    EnableMetrics = true
});

// The extension uses System.Diagnostics.ActivitySource internally.
// Any host-level OpenTelemetry SDK configuration will automatically
// collect activities emitted by WorkflowForge.

See Configuration Guide for complete options.

Host-Level Exporter Configuration

WorkflowForge emits ActivitySource events that any OpenTelemetry exporter can collect. Configure exporters at the host application level:

// In your application startup (requires OpenTelemetry SDK packages)
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("WorkflowForge")
        .AddConsoleExporter()
        .AddOtlpExporter());

Supported exporters (via separate OpenTelemetry packages):

• Jaeger: OpenTelemetry.Exporter.Jaeger
• Zipkin: OpenTelemetry.Exporter.Zipkin
• OTLP: OpenTelemetry.Exporter.OpenTelemetryProtocol
• Console: OpenTelemetry.Exporter.Console

Span Structure

WorkflowForge creates the following span hierarchy:

Workflow: OrderProcessing
  ├─ Operation: ValidateOrder (12µs)
  ├─ Operation: ChargePayment (145µs)
  ├─ Operation: ReserveInventory (87µs)
  └─ Operation: CreateShipment (234µs)

Each span includes:

• Operation name
• Duration
• Success/failure status
• Custom tags (workflow properties)
• Error details (if failed)

Custom Spans

using var activity = foundry.StartActivity("CustomOperation");
activity?.SetTag("order.id", orderId);
activity?.SetTag("customer.id", customerId);

try
{
    // ... operation logic ...
    activity?.SetStatus(ActivityStatusCode.Ok);
}
catch (Exception ex)
{
    activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
    throw;
}

Context Propagation

WorkflowForge automatically propagates trace context across:

• Operations within a workflow
• Nested workflows
• HTTP calls (with propagation headers)
• Message queues (with context metadata)

Visualization

View traces in:

• Jaeger UI: http://localhost:16686
• Zipkin UI: http://localhost:9411
• Application Insights: Azure Portal
• Grafana Tempo: Grafana dashboard

Documentation

• Getting Started
• Configuration Guide
• Extensions Overview
• Sample 15: OpenTelemetry