Tracing instrumentation

The Apitally SDK captures OpenTelemetry spans during request handling. This allows you to see exactly what happened during each request, including database queries, HTTP calls to external services, and custom operations. If your application does not have an existing OpenTelemetry setup, the SDK configures one automatically. Spans created within a captured request using the standard Activity API or instrumentation libraries will be captured.

Instrument libraries

HttpClient calls and libraries that create spans using their own ActivitySource, such as Npgsql, are captured automatically without any additional setup. Other libraries require OpenTelemetry instrumentation packages. For example, to trace database queries made with Microsoft.Data.SqlClient, install OpenTelemetry.Extensions.Hosting and OpenTelemetry.Instrumentation.SqlClient:

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.SqlClient

Then register the instrumentation in your Program.cs file:

Program.cs

using OpenTelemetry.Trace;

builder.Services.AddApitally(options =>
{
    options.WriteToken = "your-write-token";
});

builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing
    .AddSqlClientInstrumentation()
    .AddHttpClientInstrumentation()
    .AddSource("*") // all other activity sources
);

Apitally adds its span processor to the tracer provider automatically, so you do not need to add an exporter.

Create custom spans

For custom operations that are not covered by library instrumentation, you can create spans using the StartActivity() method of the IApitally service. It is a thin wrapper around the standard .NET ActivitySource API, which you can also use directly.

`StartActivity()` method

Use StartActivity() to trace code blocks within a request handler. The span ends when the returned activity is disposed:

app.MapPost("/carts/{cartId}/checkout", (string cartId, IApitally apitally) =>
{
    using (var activity = apitally.StartActivity("validate_cart"))
    {
        activity?.SetTag("cart.id", cartId);
        // Validate the cart ...
    }

    using (apitally.StartActivity("process_payment"))
    {
        // Process the payment ...
    }
});

You can also create spans with your own ActivitySource. If your application registers its own tracer provider, add the source to it with AddSource().

using System.Diagnostics;

public class OrderService
{
    private static readonly ActivitySource Source = new("MyApp");

    public void ProcessOrder()
    {
        using var activity = Source.StartActivity("process_order");
        // Process the order ...
    }
}

Capture handled exceptions

Apitally includes exceptions in request traces to help you diagnose server errors. Exceptions that propagate through ASP.NET Core are captured automatically. If your application catches an exception and handles it without rethrowing it, call CaptureException() on the IApitally service to include it in the current request trace.

try
{
    ProcessOrder();
}
catch (Exception exception)
{
    apitally.CaptureException(exception);
    // Return an error response without rethrowing the exception
}

SDK reference

Setup guides

Instrument libraries

Create custom spans

`StartActivity()` method

Capture handled exceptions

​Instrument libraries

​Create custom spans

​StartActivity() method

​Capture handled exceptions

Instrument libraries

Create custom spans

`StartActivity()` method

Capture handled exceptions