cratis-engineering-chronicle-kernel-tracing

Add tracing to a Chronicle class

Chronicle instruments itself with the Fundamentals traces pattern from Cratis.Traces. Never call System.Diagnostics.ActivitySource directly. Declare spans with the [Span] source generator and take an IActivitySource<T> on the class being traced.

This is contributor guidance for the Chronicle repository. An application built on Chronicle instruments itself with ordinary OpenTelemetry; nothing here applies to it.

Verified product sources

This skill is verified against these exact sources:

Package	Purpose
Cratis.Fundamentals	Cratis.Traces.SpanAttribute, IActivitySource<T>, IActivityScope<T>, AddNamedMeter, AddNamedActivitySource
Cratis.Chronicle (kernel and clients)	ChronicleMetersExtensions, WellKnown.MeterName, the tag extensions

Confirm the pinned Cratis.Fundamentals version in the repository's package management before relying on a member.

The shape

1. Declare the spans in a <ClassName>Traces.cs companion file.
2. Take IActivitySource<TClass> on the class.
3. Open a scope with the generated method and tag it.
4. Update the specifications to supply a real activity source.

No per-type dependency-injection registration is needed — the registration is open-generic.

Step 1 — Declare the spans

Each traced class gets its own <ClassName>Traces.cs, in the same folder as <ClassName>.cs.

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