Tracing

.. contents:: Table of Contents :depth: 2 :local: .. _break: http://break.do

Feature of: :doc:../features/logging

.NET logging and tracing | .NET | Microsoft Learn <https://learn.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing>_
.NET distributed tracing | .NET | Microsoft Learn <https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing>_

This chapter explains how to perform distributed tracing using Ocelot.

.. |opentracing-csharp Logo| image:: https://avatars.githubusercontent.com/u/15482765 :alt: opentracing-csharp Logo :width: 30

|opentracing-csharp Logo| OpenTracing

.. _OpenTracing: https://opentracing.io .. _Ocelot.Tracing.OpenTracing: https://www.nuget.org/packages/Ocelot.Tracing.OpenTracing .. _ThreeMammals/Ocelot.Tracing.OpenTracing: https://github.com/ThreeMammals/Ocelot.Tracing.OpenTracing

| Package: Ocelot.Tracing.OpenTracing_ | Namespace: Ocelot.Tracing.OpenTracing | Repository: ThreeMammals/Ocelot.Tracing.OpenTracing_

Ocelot provides tracing functionality through the project from opentracing-csharp <https://github.com/opentracing/opentracing-csharp>_ repository.

.. code-block:: shell

dotnet add package Ocelot.Tracing.OpenTracing

The example below uses the C# Client for Jaeger <https://github.com/jaegertracing/jaeger-client-csharp>_ to provide the tracer used in Ocelot. To add OpenTracing_ services, you must call the AddOpenTracing() extension method on the OcelotBuilder returned by AddOcelot() [#f1]_, as shown below:

.. code-block:: csharp :emphasize-lines: 11

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 <https://github.com/ThreeMammals/Ocelot/blob/main/samples/OpenTracing/ocelot.json>__, add the following to the route you want to trace:

.. code-block:: json

"HttpHandlerOptions": { "UseTracing": true }

Ocelot will now send tracing information to Jaeger <https://www.jaegertracing.io/>_ whenever this route is called.

.. note::

A clean yet functional sample can be found here: Ocelot.Samples.OpenTracing <https://github.com/ThreeMammals/Ocelot/tree/main/samples/OpenTracing>_.
The OpenTracing_ project was archived on January 31, 2022 (see the article <https://www.cncf.io/blog/2022/01/31/cncf-archives-the-opentracing-project/>). The Ocelot team is planning to decide on a migration to OpenTelemetry <https://opentelemetry.io>, which is highly desirable.

.. warning:: Starting with version 25.0, the Ocelot.Tracing.OpenTracing package has been extracted from the Ocelot mono-repo into its own dedicated repository. The package ID and namespace remain unchanged, but the source code, issues, and releases are now hosted at ThreeMammals/Ocelot.Tracing.OpenTracing_.

.. _tr-butterfly:

Butterfly

.. _Butterfly: https://github.com/liuhaoyang/butterfly .. _Ocelot.Tracing.Butterfly: https://www.nuget.org/packages/Ocelot.Tracing.Butterfly .. _ThreeMammals/Ocelot.Tracing.Butterfly: https://github.com/ThreeMammals/Ocelot.Tracing.Butterfly

| Package: Ocelot.Tracing.Butterfly_ | Namespace: Ocelot.Tracing.Butterfly | Repository: ThreeMammals/Ocelot.Tracing.Butterfly_

Ocelot provides tracing functionality through the excellent Butterfly_ 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:

.. code-block:: shell

dotnet add 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:

.. code-block:: csharp :emphasize-lines: 5

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:

.. code-block:: json

"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 2026. The latest release of the Butterfly.Client <https://www.nuget.org/packages/Butterfly.Client>_ package (version 0.0.8 <https://www.nuget.org/packages/Butterfly.Client/0.0.8>) was made on February 22, 2018. As planned, the Ocelot team discontinued distribution of the Ocelot.Tracing.Butterfly package from the main Ocelot mono-repo in version 25.0_, moving it to its own dedicated repository instead.

.. warning:: Starting with version 25.0, the Ocelot.Tracing.Butterfly package has been extracted from the Ocelot mono-repo into its own dedicated repository. The package ID and namespace remain unchanged, but the source code, issues, and releases are now hosted at ThreeMammals/Ocelot.Tracing.Butterfly_.

""""

.. [#f1] The :ref:di-services-addocelot-method adds default ASP.NET services to the DI container. You can call another extended :ref:di-addocelotusingbuilder-method while configuring services to develop your own :ref:di-custom-builder. See more instructions in the ":ref:di-addocelotusingbuilder-method" section of the :doc:../features/dependencyinjection feature.

.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs .. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json .. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0 .. _25.0: https://github.com/ThreeMammals/Ocelot/releases/tag/25.0.0