wavefront-opentracing-sdk-csharp

We are deprecating the OpenTracing repositories, and they are no longer supported. To migrate from OpenTracing to OpenTelemetry, see the migration steps in our documentation

Contact our support team if you have any questions (support@wavefront.com). Thank you!

Table of Content

• Requirements and Installation
• Usage
  • Application Tags
  • IWavefrontSender
  • Reporter
  • WavefrontTracer
• Span Logs
• Cross Process Context Propagation
• RED Metrics
• Monitoring the SDK
• License
• How to Contribute

Welcome to Wavefront's OpenTracing C# SDK

This is the Wavefront by VMware OpenTracing SDK for C# that provides distributed tracing support for Wavefront.

Before you start implementing, let us make sure you are using the correct SDK!

Note:

• This is the Wavefront by VMware OpenTracing SDK for C#! If this SDK is not what you were looking for, see the table given below.
• See instrument your application for tracing for more information.

Wavefront SDKs

SDK Type	SDK Description	Supported Languages
OpenTracing SDK	Implements the OpenTracing specification. Lets you define, collect, and report custom trace data from any part of your application code. Automatically derives RED metrics from the reported spans.	Java: OpenTracing SDK | Tracing Agent Python: OpenTracing SDK Go: OpenTracing SDK .Net/C#: OpenTracing SDK
Metrics SDK	Implements a standard metrics library. Lets you define, collect, and report custom business metrics and histograms from any part of your application code.	Java: Dropwizard | JVM Python: Pyformance SDK Go: Go Metrics SDK .Net/C#: App Metrics SDK
Framework SDK	Reports predefined traces, metrics, and histograms from the APIs of a supported app framework. Lets you get started quickly with minimal code changes.	Java: Dropwizard | gRPC | JAX-RS | Jersey .Net/C#: ASP.Net core
Sender SDK	Lets you send raw values to Wavefront for storage as metrics, histograms, or traces, e.g., to import CSV data into Wavefront.	Java: Sender SDK Python: Sender SDK Go: Sender SDK .Net/C#: Sender SDK C++: Sender SDK

Requirements and Installation

• Supported Frameworks

  • .NET Framework (>= 4.5.2)
  • .NET Standard (>= 2.0)

• Installation
  Install the NuGet package.

  • Package Manager Console

    PM> Install-Package Wavefront.OpenTracing.SDK.CSharp
    

  • .NET CLI Console

    > dotnet add package Wavefront.OpenTracing.SDK.CSharp
    

Usage

Tracer is an OpenTracing interface for creating spans and propagating them across arbitrary transports.

This SDK provides a WavefrontTracer that:

• Creates spans and sends them to Wavefront.
• Automatically generates and reports RED metrics from your spans.

The steps for creating a WavefrontTracer are:

1. Create an ApplicationTags instance to specify metadata about your application.
2. Create an IWavefrontSender instance to send trace data to Wavefront.
3. Create a WavefrontSpanReporter instance to report trace data to Wavefront.
4. Create a WavefrontTracer instance.

The following code sample creates a Tracer. For details of each step, see the sections below.

Tracer CreateWavefrontTracer(string application, string service) {
  // Step 1. Create ApplicationTags.
  ApplicationTags applicationTags = new ApplicationTags.Builder(application, service).Build();
  
  // Step 2. Create an IWavefrontSender instance for sending trace data via a Wavefront proxy.
  //         Assume you have installed and started the proxy on <proxyHostname>.
  IWavefrontSender wavefrontSender = new WavefrontProxyClient.Builder(<proxyHostname>)
    .MetricsPort(2878).TracingPort(30000).DistributionPort(40000).Build();
        
  // Step 3. Create a WavefrontSpanReporter for reporting trace data that originates on <sourceName>.
  IReporter wfSpanReporter = new WavefrontSpanReporter.Builder()
    .WithSource(<sourceName>).Build(wavefrontSender);
        
  // Step 4. Create the WavefrontTracer.
  return new WavefrontTracer.Builder(wfSpanReporter, applicationTags).Build();
}

1. Set Up Application Tags

Application tags determine the metadata (span tags) that are included with every span reported to Wavefront. These tags enable you to filter and query trace data in Wavefront.

You encapsulate application tags in an ApplicationTags object. See Instantiating ApplicationTags for details.

2. Set Up an IWavefrontSender

An IWavefrontSender object implements the low-level interface for sending data to Wavefront. You can choose to send data to Wavefront using the Wavefront proxy or direct ingestion.

• If you have already set up an IWavefrontSender for another C# SDK that runs in the same process, use that one. (For details about sharing a single instance of IWavefrontSender instance across SDKs, see Share an IWavefrontSender Instance.

• Otherwise, Set Up an IWavefrontSender Instance.

3. Set Up a Reporter

You must create a WavefrontSpanReporter to report trace data to Wavefront. Optionally, you can create a CompositeReporter to send data to Wavefront and print it to the console.

Create a WavefrontSpanReporter

To build a WavefrontSpanReporter, you must specify an IWavefrontSender. Optionally, you can specify a string that represents the source for the reported spans. If you omit the source, the host name is automatically used.

Example: Create a WavefrontSpanReporter:

// Create a WavefrontProxyClient or WavefrontDirectIngestionClient
IWavefrontSender sender = BuildWavefrontSender(); // pseudocode; see above

IReporter wfSpanReporter = new WavefrontSpanReporter.Builder()
  .WithSource("wavefront-tracing-example") // optional nondefault source name
  .Build(sender);

//  To get the number of failures observed while reporting
int totalFailures = wfSpanReporter.GetFailureCount();

Note: After you initialize the WavefrontTracer with the WavefrontSpanReporter (below), completed spans will automatically be reported to Wavefront. You do not need to start the reporter explicitly.

Create a CompositeReporter (Optional)

A CompositeReporter enables you to chain a WavefrontSpanReporter to another reporter, such as a ConsoleReporter. A console reporter is useful for debugging.

Example:

// Create a console reporter that reports span to console
IReporter consoleReporter = new ConsoleReporter("wavefront-tracing-example"); // Specify the same source you used for the WavefrontSpanReporter

// Instantiate a composite reporter composed of a console reporter and a WavefrontSpanReporter
IReporter compositeReporter = new CompositeReporter(wfSpanReporter, consoleReporter);

4. Create a WavefrontTracer

To create a WavefrontTracer, you pass the ApplicationTags and Reporter instances you created above to a Builder:

Example:

ApplicationTags appTags = BuildTags(); // pseudocode; see above
IReporter wfSpanReporter = BuildReporter();  // pseudocode; see above
WavefrontTracer.Builder wfTracerBuilder = new WavefrontTracer.Builder(wfSpanReporter, appTags);
// Optionally, configure sampling and add multi-valued span tags before building
ITracer tracer = wfTracerBuilder.Build();

Sampling (Optional)

Optionally, you can apply one or multiple sampling strategies to the WavefrontTracer. See the sampling documentation for details.

Multi-valued Span Tags (Optional)

Optionally, you can add metadata to OpenTracing spans in the form of multi-valued tags. The WavefrontTracer Builder supports different methods to add those tags.

Example:

// Construct WavefrontTracer.Builder instance
WavefrontTracer.Builder wfTracerBuilder = new WavefrontTracer.Builder(...);

// Add individual tag key value
wfTracerBuilder.WithGlobalTag("env", "Staging");

// Add a dictionary of tags
wfTracerBuilder.WithGlobalTags(new Dictionary<string, string>{ { "severity", "sev-1" } });

// Add a dictionary of multivalued tags since Wavefront supports repeated tags
wfTracerBuilder.WithGlobalMultiValuedTags(new Dictionary<string, IEnumerable<string>>
{
    { "location", new string[]{ "SF", "NY", "LA" } }
});

// Construct Wavefront OpenTracing Tracer
ITracer tracer = wfTracerBuilder.Build();

Add Custom Span-Level RED metrics

Optionally, you can add custom span-level tags to propagate RED metrics. See Custom Span-Level Tags for RED Metrics for details.

wfTracerBuilder.RedMetricsCustomTagKeys(new HashSet<string>{ "env", "location" });

Close the Tracer

Always close the tracer before exiting your application to flush all buffered spans to Wavefront.

tracer.Close();

Span Logs

Note: Span logs are disabled by default and require Wavefront proxy version 5.0 or later. Contact support@wavefront.com to enable the feature.

You can instrument your application to emit logs or events with spans, and examine them from the Wavefront Tracing UI.

Use the OpenTracing Span object’s log() method in your application.

Cross Process Context Propagation

See the context propagation documentation for details on propagating span contexts across process boundaries.

RED Metrics

See the RED metrics documentation for details on the out-of-the-box metrics and histograms that are provided.

License

Apache 2.0 License.

How to Contribute

• Reach out to us on our public Slack channel.
• If you run into any issues, let us know by creating a GitHub issue.