Tickwork.Instrumentation.OpenTelemetry 1.0.0

Tickwork.Instrumentation.OpenTelemetry

OpenTelemetry instrumentation package for Tickwork job scheduler with distributed tracing support.

Features

• Distributed Tracing: Full OpenTelemetry activity/span creation for job execution lifecycle
• Structured Logging: Rich logging with job context through ILogger integration
• Parent-Child Relationships: Maintains trace relationships between parent and child jobs
• Retry Tracking: Tracks retry attempts with detailed context
• Performance Metrics: Comprehensive execution time and outcome tracking
• Error Tracking: Detailed exception and cancellation tracking
• Caller Information: Automatic detection of where jobs are enqueued from

Installation

dotnet add package Tickwork.Instrumentation.OpenTelemetry

Usage

Basic Setup

using Tickwork.Instrumentation.OpenTelemetry;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Configure OpenTelemetry with Tickwork ActivitySource
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("Tickwork") // Add Tickwork ActivitySource
               .AddConsoleExporter()
               .AddJaegerExporter();
    });

// Add Tickwork with OpenTelemetry instrumentation
builder.Services.AddTickwork<MyTimeTicker, MyCronTicker>(options => { })
    .AddOperationalStore(ef => { })
    .AddOpenTelemetryInstrumentation(); // 👈 Enable tracing

var app = builder.Build();
app.Run();

With Jaeger

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddTickworkInstrumentation()
               .AddJaegerExporter(options =>
               {
                   options.Endpoint = new Uri("http://localhost:14268/api/traces");
               });
    });

With Application Insights

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddTickworkInstrumentation()
               .AddAzureMonitorTraceExporter();
    });

Trace Structure

Job Execution Activities

tickwork.job.execute.timeticker (main job execution span)
├── tickwork.job.enqueued (when job starts execution)
├── tickwork.job.completed (on successful completion)
├── tickwork.job.failed (on failure)
├── tickwork.job.cancelled (on cancellation)
├── tickwork.job.skipped (when skipped)
├── tickwork.seeding.started (for data seeding)
└── tickwork.seeding.completed (seeding completion)

Tags Added to Activities

Logging Output

The instrumentation provides structured logging for all job events:

[INF] Tickwork Job enqueued: TimeTicker - ProcessEmails (123e4567-e89b-12d3-a456-426614174000) from ExecutionTaskHandler
[INF] Tickwork Job completed: ProcessEmails (123e4567-e89b-12d3-a456-426614174000) in 1250ms - Success: True
[ERR] Tickwork Job failed: ProcessEmails (123e4567-e89b-12d3-a456-426614174000) - Retry 1 - Connection timeout
[INF] Tickwork Job completed: ProcessEmails (123e4567-e89b-12d3-a456-426614174000) in 2500ms - Success: False
[WRN] Tickwork Job cancelled: ProcessEmails (123e4567-e89b-12d3-a456-426614174000) - Task was cancelled
[INF] Tickwork Job skipped: ProcessEmails (123e4567-e89b-12d3-a456-426614174000) - Another CronOccurrence is already running!
[INF] Tickwork start seeding data: TimeTicker (production-node-01)
[INF] Tickwork completed seeding data: TimeTicker (production-node-01)

Integration with Logging Frameworks

This package works seamlessly with any logging framework that integrates with ILogger:

Serilog

builder.Host.UseSerilog((context, config) =>
{
    config.WriteTo.Console()
          .WriteTo.File("logs/tickwork-.txt", rollingInterval: RollingInterval.Day)
          .Enrich.FromLogContext();
});

NLog

builder.Logging.ClearProviders();
builder.Logging.AddNLog();

Performance Impact

• Minimal Overhead: Activities are only created when OpenTelemetry listeners are active
• Efficient Logging: Uses structured logging with minimal string allocations
• Conditional Tracing: No performance impact when tracing is disabled

Requirements

• .NET 8.0 or later
• OpenTelemetry 1.7.0 or later
• Tickwork.Utilities (automatically included)