Tracing

This chapter explains how to perform distributed tracing using Ocelot.

opentracing-csharp Logo OpenTracing

Package: Ocelot.Tracing.OpenTracing
Namespace: Ocelot.Tracing.OpenTracing

Ocelot provides tracing functionality through the excellent project from opentracing-csharp repository. The code for Ocelot integration can be found in this Ocelot project.

The example below uses the C# Client for Jaeger to provide the tracer used in Ocelot. To add OpenTracing services, you must call the AddOpenTracing() extension method on the OcelotBuilder returned by AddOcelot() [1], as shown below:

builder.Services
    .AddSingleton(serviceProvider =>
    {
        var loggerFactory = serviceProvider.GetService<ILoggerFactory>();
        var config = new Jaeger.Configuration(builder.Environment.ApplicationName, loggerFactory);
        var tracer = config.GetTracer();
        GlobalTracer.Register(tracer);
        return tracer;
    })
    .AddOcelot(builder.Configuration)
    .AddOpenTracing();

Then, in your ocelot.json, add the following to the route you want to trace:

"HttpHandlerOptions": {
  "UseTracing": true
}

Ocelot will now send tracing information to Jaeger whenever this route is called.

Note 1: A clean yet functional sample can be found here: Ocelot.Samples.OpenTracing.

Note 2: The OpenTracing project was archived on January 31, 2022 (see the article). The Ocelot team is planning to decide on a migration to OpenTelemetry, which is highly desirable.

Butterfly

Package: Ocelot.Tracing.Butterfly
Namespace: Ocelot.Tracing.Butterfly

Ocelot provides tracing functionality through the excellent Butterfly project. The code for the Ocelot integration can be found in this Ocelot project. To use the tracing functionality, please refer to the Butterfly documentation.

In Ocelot, you need to add the NuGet package if you wish to trace a route:

Install-Package Ocelot.Tracing.Butterfly

In your Program, to add Butterfly services, you must call the AddButterfly() extension method on the OcelotBuilder returned by AddOcelot(), as shown below:

using Ocelot.Tracing.Butterfly;

builder.Services
    .AddOcelot(builder.Configuration)
    .AddButterfly(options =>
    {
        // This is the URL that the Butterfly collector server is running on...
        options.CollectorUrl = "http://localhost:9618";
        options.Service = "Ocelot";
    });

Then, in your ocelot.json, add the following to the route you want to trace:

"HttpHandlerOptions": {
  "UseTracing": true
}

Ocelot will now send tracing information to Butterfly whenever this route is called.

Note: The Butterfly project has not been supported for more than seven years, as of 2025. The latest release of the Butterfly.Client package (version 0.0.8) was made on February 22, 2018. The Ocelot team is planning to discontinue the Ocelot.Tracing.Butterfly package, which is scheduled to happen after the release of Ocelot version 24.0.