C# Client for Jaeger (https://jaegertracing.io)

• Implements C# OpenTracing API
• Supports netstandard 2.0

Status

This library is still under construction and needs to be peer reviewed as well as have features added.

Usage

This package contains everything you need to get up and running. The meta-package includes the following packages: * Jaeger.Core * Jaeger.Senders.Thrift

Senders

The implementation of

Jaeger.Core

This is a list of sender implementations known to the Jaeger team: * Jaeger.Senders.Thrift (default, included in

Jaeger

The Tracer

The following will give you a tracer that reports spans to an

ILogger

ILoggerFactory

using Jaeger;
using Jaeger.Reporters;
using Jaeger.Samplers;
using Microsoft.Extensions.Logging;

var loggerFactory = ; // get Microsoft.Extensions.Logging ILoggerFactory
var serviceName = "initExampleService";
var reporter = new LoggingReporter(loggerFactory);
var sampler = new ConstSampler(true);
var tracer = new Tracer.Builder(serviceName)
    .WithLoggerFactory(loggerFactory)
    .WithReporter(reporter)
    .WithSampler(sampler)
    .Build();

This works well if you only want to log to a logging framework. As soon as you want to also get metrics and use a real remote tracer, manually building will get hard pretty fast.

Configuration

using Jaeger;
using Jaeger.Samplers;
using Microsoft.Extensions.Logging;

var loggerFactory = ; // get Microsoft.Extensions.Logging ILoggerFactory
var serviceName = "initExampleService";
Configuration.SenderConfiguration.DefaultSenderResolver = new SenderResolver(loggerFactory)
    .RegisterSenderFactory();
Configuration config = new Configuration("myServiceName")
    .WithSampler(...)   // optional, defaults to RemoteControlledSampler with HttpSamplingManager on localhost:5778
    .WithReporter(...); // optional, defaults to RemoteReporter with UdpSender on localhost:6831 when ThriftSenderFactory is registered
ITracer tracer = config.GetTracer();

The config objects lazily builds and configures Jaeger Tracer. Multiple calls to GetTracer() return the same instance.

Notice

The

ThriftSenderFactory

Jaeger.Senders.Thrift

Jaeger

ApacheThrift

Jaeger.Senders.*

ISender

ISenderFactory

Jaeger.Core

Jaeger

By default,

Configuration.SenderConfiguration.DefaultSenderResolver

ISenderFactory

Jaeger.Core

ISender

SenderResolver.Resolve

NoopSender.Instance

Configuration via Environment

It is also possible to obtain a

Jaeger.Configuration

Configuration config = Configuration.FromEnv();

The property names are:

name = value

${envVarName:default}

:default

Setting

JAEGER_AGENT_HOST

JAEGER_AGENT_PORT

UdpSender

JAEGER_ENDPOINT

JAEGER_AGENT_*

When the

JAEGER_ENDPOINT

HttpSender

JAEGER_AUTH_TOKEN

Reporting

For more information on reporting see the reporting README

Sampling

For more information on sampling see the sampling README

Extracting Span Information

When your code is called you might want to pull current trace information out of calling information before building and starting a span. This allows you to link your span into a current trace and track its relation to other spans. By default text map and http headers are supported. More support is planned for the future as well as allowing custom extractors.

using OpenTracing.Propagation; // where you get Format from

var callingHeaders = new TextMapExtractAdapter(...); // get the calling headers
var callingSpanContext = tracer.Extract(BuiltinFormats.HttpHeaders, callingHeaders);

You can then use the callingSpanContext when adding references with the SpanBuilder.

Injecting Span Information

In order to pass along the trace information in calls so others can extract it you need to inject it into the carrier.

using OpenTracing.Propagation; // where you get BuiltinFormats from

var spanContext = span.Context; // pulled from your current span
var newCallHeaders = new TextMapInjectAdapter(null); // get the calling headers
tracer.Inject(spanContext, BuiltinFormats.HttpHeaders, newCallHeaders);

You can then pass along the headers and as along as what you are calling knows how to extract that format you are good to go.

Building a Span

Before you start a span you will want to build it out. You can do this using the span builder. You would build a span for each operation you wanted to trace.

var operationName = "Get::api/values/";
var builder = tracer.BuildSpan(operationName);

Adding Tags

Any tags you add to the span builder will be added to the span on start and reported to the reporting system you have setup when the span is reported. The following types are supported as tags:

bool

double

int

string

builder.WithTag("machine.name", "machine1").WithTag("cpu.cores", 8);

Some well-known tags are defined in

OpenTracing.Tag

using OpenTracing.Tag;

builder.WithTag(Tags.SpanKind, Tags.SpanKindClient).WithTag(Tags.DbType, "sql");

Adding References

References allow you to show how this span relates to another span. You need the

SpanContext

child_of

builder.AddReference(References.FollowsFrom, spanContext);

There also exist helper methods to simplify adding child of references.

As Child Of

Shorthand for adding a chold of reference. You can pass in an

ISpan

ISpanContext

builder.AsChildOf(iSpanOrISpanContext);

Starting the Span

Starting the span from the span builder will figure out if there is a parent for the span, create a context for the span, and pass along all references and tags.

You can start the span right now:

C#
var span = builder.Start();

Or you can start it at a specific time:

C#
var startTime = DateTimeOffset.Now;
var span = builder.WithStartTimestamp(startTime).Start();

If you want to start a span and use it as an active span, you can use a scoped span.

C#
using (var scope = builder.StartActive(true))
{
    var span = scope.Span;
}

This will automatically define the newly created span as child of the span that was active at that time. If no span was active, it will be created as root span. In addition will the scope span be automatically finished when the scope ends, even if the

using

Spans

After creating a span and before finishing it, you can add and change some information on a span.

Baggage Items

Baggage is key/value data that is passed along the wire and shared with other spans. You can get and set baggage data from the span object.

var mobileVersion = span.GetBaggageItem("mobile.version");

span.SetBaggageItem("back-end.version", "0.0.1");

Logging

You can log structured data which allows you to tie information from what's happening along the lifetime of a span to the time that it happened. You can log a list of key/value data or an event at a specific time.

var logData = new List> {
    { "handling number of events", 6 },
    { "using legacy system", false }
};

span.Log(DateTimeOffset.Now, logData);

or you can pass it without a timestamp and the timestamp will be sent for you:

C#
span.Log(logData);

Events are a little different in that they're just a string. ```C# var event = "loop_finished";

span.Log(DateTimeOffset.Now, event);

and as above you can send an event in without a timestamp:

Tags

Tags can be set using

SetTag(, )

Operation Name

You can change the operation name from what was originally set on the span when it was created.

span.SetOperationName("PUT::api/values/");

Finishing

Span

IDisposable

Finish

span.Finish(DateTimeOffset.Now);

or

C#
span.Finish();

Contributing

We welcome community contributions to this project. Please see CONTRIBUTING.md for more details.

By contributing your code, you agree to license your contribution under the terms of the APLv2.

License

All files are released with the Apache 2.0 license.