OpenTracing Instrumentation for C#

This article describes how to manually extract traces from your C#-based application with OpenTracing instrumentation.

OpenTracing and Jaeger

OpenTracing is an API standard of instrumentation for distributed tracing. Jaeger is one implementation of that standard and our most recommended practice for C#. It has a set of libraries and tools to provide open source implementation for distributed tracing

Requirements

Add the following packages to your solution:

  • OpenTracing.Contrib.NetCore
  • OpenTracing
  • Jaeger

Examples

To see an actual example, head to our examples repository.

Manually instrument your C# code

Set up a tracer

Configure an existing tracer or set up a new tracer.

  • Configure an existing tracer

    If you already have a tracer in your application that forwards traces to an agent, use this code:

       var tracer = GlobalTracer.Instance;
    
  • Set up a new tracer

    To set up a new tracer, use the code snippet below.

    • Replace <<JAEGER_AGENT_HOST>> with the host address of your Jaeger agent: Use localhost if it’s on the same machine.
    • For a Kubernetes deployment, use Environment.GetEnvironmentVariable(Jaeger. Configuration.JaegerAgentHost) and make sure your application deployment contains the environment variables as shown in the tab Kubernetes reference.
       string appName = System.Reflection.Assembly.GetEntryAssembly().GetName().Name;
       string hostName = <<JAEGER_AGENT_HOST>>;
       var tracer =
               new Tracer.Builder(appName)
                   .WithSampler(new ConstSampler(true))
                   .WithReporter(new RemoteReporter.Builder().WithSender(
                           new UdpSender(hostName, 6831, 0)).Build()
                   )
                   .Build();
    

Within the snippet:

  • Replace <<JAEGER_AGENT_HOST>> with the host address of your Jaeger agent: Use localhost if it’s on the same machine.
  • For a Kubernetes deployment, use Environment.GetEnvironmentVariable(Jaeger.Configuration. JaegerAgentHost) and make sure your application deployment contains the environment variables as shown in the Kubernetes reference, below.
Kubernetes Reference

If you are deploying your application on Kubernetes, first deploy Jaeger/OpenTelemetry collector and agents. Then add the following environment variables to your application containers:

 env:
 - name: JAEGER_AGENT_HOST
   valueFrom:
     fieldRef:
       fieldPath: status.hostIP
 - name: JAEGER_AGENT_PORT
   value: "6831"
Construct traces

Use the code snippet below to construct your traces with spans where you want.

You can nest the code to create child spans. For more information on manual tracing instrumentation, see OpenTracing’s C# Guide.

 using (IScope scope = _tracer.BuildSpan("Operation").StartActive(finishSpanOnDispose: true))
            {
                try
                {
                    // Do something
                }
                catch (Exception ex)
                {
                    Tags.Error.Set(scope.Span, true);
                }

                // No need to call scope.Span.Finish() as we've set finishSpanOnDispose:true in StartActive.
            }