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:

Layer	Meter	ActivitySource
Shared well-known instance (keyed by WellKnown.MeterName)	Meter("Cratis.Chronicle")	System.Diagnostics.ActivitySource("Cratis.Chronicle")
Per-type wrapper (keyed by WellKnown.MeterName)	IMeter<T> / Meter<T>	IActivitySource<T> / ActivitySource<T>
Registered by	services.AddNamedMeter(WellKnown.MeterName)	services.AddNamedActivitySource(WellKnown.MeterName)

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);
}