Add Traces

Adding Traces to a Class

Chronicle uses the Fundamentals Traces pattern from Cratis.Traces. Never call System.Diagnostics.ActivitySource directly. Always use the source-generator [Span] attribute and IActivitySource<T>.

Overview

1. Create a *Traces.cs companion file with [Span] methods.
2. Register IActivitySource<T> via services.AddNamedActivitySource(WellKnown.MeterName) in ChronicleMetersExtensions (one call covers all types via open-generic keyed DI).
3. Inject [FromKeyedServices(WellKnown.MeterName)] IActivitySource<TTarget> into the class.
4. Call the generated extension methods and apply tags via TagExtensions.
5. Update specs to pass new ActivitySource<T>() (not a substitute).

DI registration architecture

Chronicle's ActivitySource follows the same keyed DI pattern as Meter:

Both calls are made from ChronicleMetersExtensions.AddChronicleMeters(). They use open-generic keyed DI (TryAddKeyedSingleton(typeof(IMeter<>), name, typeof(Meter<>))), so any new type added to a keyed-injected class is automatically covered — no per-type registration step is needed.

Step 1 — Create a *Traces.cs companion file

Each class that needs tracing gets its own *Traces.cs file in the same folder.

// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using System.Diagnostics;
using Cratis.Traces;

namespace Cratis.Chronicle.<Namespace>;

#pragma warning disable SA1600 // Elements should be documented
#pragma warning disable MA0048 // File name must match type name
#pragma warning disable SA1402 // File may only contain a single type

internal static partial class <ClassName>Traces
{
    [Span("cratis.chronicle.<domain>.<operation>", ActivityKind.Internal)]
    internal static partial IActivityScope<<ClassName>> <OperationName>(this IActivitySource<<ClassName>> source);
}

Rules:

• File name: <ClassName>Traces.cs, next to <ClassName>.cs.
• Class name: <ClassName>Traces (partial, static, internal).
• One [Span] method per traced operation.
• Span names follow cratis.chronicle.<domain>.<operation> (lower_snake_case).
• Use ActivityKind.Internal for grain-to-grain/internal calls.
• Use ActivityKind.Server for gRPC service entry points.
• No parameters in [Span] methods — tags are set manually via TagExtensions.

Step 2 — Register IActivitySource<T> in DI

2a — Open-generic registration (no per-type step needed)

ChronicleMetersExtensions.AddChronicleMeters() calls:

services.AddNamedActivitySource(WellKnown.MeterName);

This uses TryAddKeyedSingleton(typeof(IActivitySource<>), name, typeof(ActivitySource<>)), so any class that injects [FromKeyedServices(WellKnown.MeterName)] IActivitySource<T> is automatically resolved — no extra registration line is required.

Note: AddNamedMeter and AddNamedActivitySource are currently provided by a local compatibility shim (NamedDiagnosticsServiceCollectionExtensions.cs) that mirrors the Fundamentals upstream API. When Cratis.Fundamentals is upgraded to a version that includes DiagnosticsServiceCollectionExtensions, delete that shim file and bump the version in Directory.Packages.props.

Step 3 — Inject IActivitySource<T> into the class

Primary constructor (grain / primary constructor class)

/// <param name="activitySource">The <see cref="IActivitySource{T}"/> for tracing.</param>
public class MyClass(
    ...
    [FromKeyedServices(WellKnown.MeterName)] IActivitySource<MyClass> activitySource,
    ...)

Traditional constructor (non-grain class, registered in DI)

readonly IActivitySource<MyClass> _activitySource;

public MyClass(
    ...
    IActivitySource<MyClass> activitySource,
    ...)
{
    _activitySource = activitySource;
}

Non-grain classes constructed manually (e.g., in service factories) must use:

sp.GetRequiredKeyedService<IActivitySource<MyClass>>(WellKnown.MeterName)

Step 4 — Use the generated span methods and apply tags

using var span = activitySource.MyOperation(); // or _activitySource.MyOperation()
span?.Activity?.Tag(someEventStore);
span?.Activity?.Tag(someNamespace);
span?.Activity?.Tag(someObserverKey);
try
{
    // ... work ...
}
catch (Exception ex)
{
    span?.Activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
    throw;
}

Always use null-conditional span?.Activity?.Tag(...) because the source generator's IActivityScope<T> can be null when no listener is attached (e.g., in tests).

Available TagExtensions (in Cratis.Chronicle.Diagnostics.OpenTelemetry.Tracing)

Add new overloads to TagExtensions.cs for any domain concept not already listed.

Step 5 — Update specs

In specs, never use Substitute.For<IActivitySource<T>>(). The source-generator accesses .ActualSource which NSubstitute returns as null, causing NullReferenceException. Instead, use:

new ActivitySource<MyClass>()

Add using Cratis.Traces; where needed.

For Orleans TestKit grains

_silo.AddKeyedService<IActivitySource<Observer>>(WellKnown.MeterName, new ActivitySource<Observer>());

For manually instantiated classes

new MyClass(
    ...,
    new ActivitySource<MyClass>(),
    ...);

Checklist

• <ClassName>Traces.cs created with [Span] methods
• No per-type DI registration needed — open-generic AddNamedActivitySource covers all types automatically
• Class constructor injects IActivitySource<T> (keyed with [FromKeyedServices(WellKnown.MeterName)] or non-keyed for non-grain DI)
• Span methods called with span?.Activity?.Tag(...) null-safe pattern
• using Cratis.Chronicle.Diagnostics.OpenTelemetry.Tracing; added for TagExtensions
• using Cratis.Traces; added for ActivitySource<T>, IActivitySource<T>
• Specs updated to use new ActivitySource<T>() instead of Substitute.For<...>()
• Build passes with no errors
• Specs pass