Purview.Telemetry.SourceGenerator 4.0.0-prerelease.7

Purview Telemetry Source Generator

Generates ActivitySource, ILogger, and Metrics based telemetry from methods you define on an interface.

Features

• Zero boilerplate - define methods on an interface, get full telemetry implementation generated
• Multi-target generation - generate Activities, Logging, and Metrics from a single interface
• Testable - easy mocking/substitution for unit testing
• DI-ready - automatic dependency injection registration helpers

Supported Frameworks

• .NET Framework 4.8
• .NET 8 or higher

Installation

Add to your Directory.Build.props or .csproj file:

<PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.0.0-prerelease.7">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>analyzers</IncludeAssets>
</PackageReference>

Quick Start

Define an interface with telemetry methods and the generator creates the implementation:

using Purview.Telemetry;

// Multi-target interface: generates Activities, Logging, AND Metrics from combined methods
[ActivitySource]
[Logger]
[Meter]
interface IEntityStoreTelemetry
{
    // MULTI-TARGET: Creates Activity + Logs Info + Increments Counter - all from one method!
    [Activity]
    [Info]
    [AutoCounter]
    Activity? GettingEntityFromStore(int entityId, [Baggage]string serviceUrl);

    // MULTI-TARGET: Adds ActivityEvent + Logs the duration as Trace.
    [Event]
    [Trace]
    void GetDuration(Activity? activity, int durationInMS);

    // Single-target examples (when you only need one telemetry type):
    
    // Activity-only: Adds Baggage to the Activity
    [Context]
    void RetrievedEntity(Activity? activity, float totalValue, int lastUpdatedByUserId);

    // Log-only: Structured log message
    [Warning]
    void EntityNotFound(int entityId);

    // Metric-only: Histogram for tracking values
    [Histogram]
    void RecordEntitySize(int sizeInBytes);
}

Register with dependency injection:

// Generated extension method
services.AddEntityStoreTelemetry();

Then inject and use - a single method call emits an Activity, Log, and Metric simultaneously:

public class EntityService(IEntityStoreTelemetry telemetry)
{
    public async Task<Entity> GetEntityAsync(int id, string serviceUrl, CancellationToken cancellationToken)
    {
        // Single call creates Activity AND logs AND increments counter
        using var activity = telemetry.GettingEntityFromStore(id, serviceUrl);
        
        var entity = await _repository.GetAsync(id, cancellationToken);
                        
        // Adds event to activity AND logs duration
        telemetry.GetDuration(activity, stopwatch.ElapsedMilliseconds);

        if (entity == null)
        {
            // Logs warning if entity not found
            telemetry.EntityNotFound(id);
            return null;
        })

        // Activity context addition
        telemetry.RetrievedEntity(activity, entity.TotalValue, entity.LastUpdatedByUserId);
        
        // Histogram only records size
        telemetry.RecordEntitySize(entity.SizeInBytes);

        return entity;
    }
}

Telemetry Types

Documentation

• Full Wiki
• Generated Output Examples
• Multi-Targeting Guide
• Logging Configuration

Sample Project

The .NET Aspire Sample demonstrates Activities, Logs, and Metrics generation working together with the Aspire Dashboard.

Performance

Benchmarked on 13th Gen Intel Core i9-13900KF, .NET SDK 10.0.200. See the Performance wiki page for full cross-runtime results.

Activities (.NET 10.0)

Generated activities are within ±2% of hand-written code with identical allocations.

Logging (.NET 10.0)

Both v1 and v2 allocate 0 bytes per call on all runtimes. v2 (ThreadLocalState pattern) matches v1 in allocation and is within ~10% in CPU time.

Multi-Target (.NET 10.0, Activity + Logging + Metrics)

Adding full Activity+Logging+Metrics multi-target generation costs ~7% over Activity-only — matching hand-written multi-target code within 2%.

Metrics (.NET 10.0)

All instruments are 0 allocations. Manual baselines are JIT-eliminated on .NET 10.0 (no active listener), so absolute times are shown. On .NET 8/9 and .NET Framework, generated and manual are within ±25%.

v4 Breaking Changes

Namespace Consolidation

v4 consolidates all attributes into a single namespace. Update your using statements:

Before (v3):

using Purview.Telemetry.Activities;
using Purview.Telemetry.Logging;
using Purview.Telemetry.Metrics;

After (v4):

using Purview.Telemetry;

All attributes ([ActivitySource], [Logger], [Meter], [Activity], [Event], [Log], [Counter], etc.) are now in the unified Purview.Telemetry namespace.

OpenTelemetry-Aligned Naming (NEW in v4.0.0-alpha.5+)

v4 defaults to OpenTelemetry semantic conventions for generated telemetry names, improving observability and cross-platform compatibility. This is a breaking change if you rely on specific telemetry names.

What Changed

Examples

Before (v3/Legacy):

// Generated code:
new ActivitySource("myapp")           // lowercase
activity.SetTag("entityid", ...)      // smashed compound
var meter = meterFactory.Create("MyApp.Products");
meter.CreateCounter<int>("recordcount")  // smashed compound, no meter prefix

After (v4 OpenTelemetry mode - DEFAULT):

// Generated code:
new ActivitySource("MyApp")           // preserves casing
activity.SetTag("entity_id", ...)     // snake_case
var meter = meterFactory.Create("MyApp.Products");
meter.CreateCounter<int>("myapp.products.record.count")  // hierarchical: meter + instrument

Note: In OpenTelemetry mode, instrument names automatically include the meter name prefix (converted to lowercase dot.separated), following OpenTelemetry best practices for hierarchical metric naming.

Reverting to v3 Naming (Legacy Mode)

If you need to maintain v3-style naming for backward compatibility, set NamingConvention = Legacy on the [TelemetryGeneration] attribute:

using Purview.Telemetry;

// Revert ALL telemetry to v3 naming (assembly-level)
[assembly: TelemetryGeneration(NamingConvention = NamingConvention.Legacy)]

Or set per-interface:

// Legacy naming for this interface only
[TelemetryGeneration(NamingConvention = NamingConvention.Legacy)]
interface IMyTelemetry { }

Available Naming Conventions

public enum NamingConvention
{
    Legacy = 0,          // v3 behaviour: lowercase, smashed compounds
    OpenTelemetry = 1    // v4 default: OTel conventions (dot.separated, snake_case)
}

Recommendation: Use NamingConvention.OpenTelemetry (default) for new projects. Only use Legacy if you need exact v3 compatibility.