Contact our support team if you have any questions ([email protected]). Thank you!

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

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.

• 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
    

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();
}

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.

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.

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.

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.

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);

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();

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

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();

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" });

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

tracer.Close();

Note: Span logs are disabled by default and require Wavefront proxy version 5.0 or later. Contact [email protected] 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.

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

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

Apache 2.0 License.

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