Table of Contents

Class ResultsTraceProviderBuilderExtensions

Namespace
Trellis
Assembly
Trellis.Core.dll

Extension methods for configuring OpenTelemetry tracing for Railway Oriented Programming operations.

public static class ResultsTraceProviderBuilderExtensions
Inheritance
ResultsTraceProviderBuilderExtensions
Inherited Members

Fields

ActivitySourceName

The name of the ActivitySource that traces Railway Oriented Programming operations. Value: "Trellis.Results".

public const string ActivitySourceName = "Trellis.Results"

Field Value

string

Remarks

AddTrellisResultsInstrumentation(TracerProviderBuilder) is the recommended way to subscribe. Use this constant when composing a source list by hand, filtering in a processor, or configuring a backend from code, so the name is never duplicated as a literal.

The source is named for what it traces — Result operations — rather than for the package that ships it. Trellis.Core also emits the Trellis.Primitives source and the Trellis.Validation meter.

Methods

AddTrellisResultsInstrumentation(TracerProviderBuilder)

Adds Trellis Railway Oriented Programming instrumentation to the OpenTelemetry tracer provider. This enables distributed tracing and observability for Result operations.

public static TracerProviderBuilder AddTrellisResultsInstrumentation(this TracerProviderBuilder builder)

Parameters

builder TracerProviderBuilder

The OpenTelemetry.Trace.TracerProviderBuilder to configure.

Returns

TracerProviderBuilder

The same OpenTelemetry.Trace.TracerProviderBuilder instance for method chaining.

Examples

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddTrellisResultsInstrumentation()
        .AddAspNetCoreInstrumentation()
        .AddConsoleExporter());

Remarks

This method registers the Trellis ROP activity source with OpenTelemetry, allowing you to trace Result operations through your application using tools like Application Insights, Jaeger, Zipkin, or other OpenTelemetry-compatible backends.

ROP operations will automatically create activities and spans when this instrumentation is enabled, providing visibility into success/failure paths and error information.

Performance characteristics. Trellis is designed so the per-operation tracing is essentially free when no listener is registered. AddTrellisResultsInstrumentation is the Trellis-provided helper for registering the "Trellis.Results" source with OpenTelemetry; consumers may also call AddSource("Trellis.Results") directly or attach an ActivityListener. Measured on .NET 10 / x64 with an ambient ASP.NET request activity present:

  • No listener registered (default): a 10-step Bind chain costs ~242 ns total (~19 ns per Bind) with 0 bytes allocated. The per-extension using var activity = ActivitySource.StartActivity(...) returns null almost immediately. Trellis does not update an ambient ASP.NET or Mediator activity from ROP operators unless that activity was started by the Trellis ROP ActivitySource.
  • With listener registered via AddTrellisResultsInstrumentation and AllDataAndRecorded sampling: each Bind/Map/Tap call costs ~200 ns and allocates ~400 B (the Activity object + name + tags). A 10-step chain costs ~2.3 μs and ~4 KB. At 10 000 RPS with a 10-step pipeline this adds up to ~22 ms/sec of CPU and ~40 MB/sec of GC pressure — material at high throughput.

Granularity guidance. Per-Result-extension spans add limited signal beyond the outer pipeline span (Trellis.Mediator.TracingBehavior) or the ASP.NET request span. They appear as a deeply nested tree under the outer span with no business context — most observability backends collapse or charge per span. For high-throughput services prefer instrumenting at the pipeline-behavior or HTTP-boundary altitude and reserve AddTrellisResultsInstrumentation for development/debugging or low-rate request paths where step-by-step ROP visibility is the diagnostic goal.

Benchmark source: Trellis.Benchmark/TracingOverheadBenchmarks.cs. Re-run before drawing conclusions for a different runtime (e.g., NativeAOT) or hardware tier.

Edit this page