wavefront-opentracing-sdk-go

wavefront-opentracing-sdk-go

Table of Content

• Prerequisites
• Usage
  • Application Tags
  • Wavefront Sender
  • Reporter
  • WavefrontTracer
  • Global Tracer
• Span Logs
• Cross Process Context Propagation
• RED Metrics
• Monitoring the SDK
• License
• How to Contribute

Welcome to Wavefront's OpenTracing Go SDK

This is the Wavefront by VMware OpenTracing SDK for Go 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 Go! 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

Prerequisites

• Go 1.9 or higher.
• Import Wavefront packages.

  import (
  	"github.com/wavefronthq/wavefront-opentracing-sdk-go/reporter"
  	"github.com/wavefronthq/wavefront-opentracing-sdk-go/tracer"
  	"github.com/wavefronthq/wavefront-sdk-go/application"
  	"github.com/wavefronthq/wavefront-sdk-go/senders"
  )
  

Usage

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

This SDK provides a WavefrontTracer that implements the Tracer interface to create spans and send them to Wavefront. A WaverfrontTracer:

• 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 a Tags instance to specify metadata about your application.
2. Create a Wavefront Sender instance to send trace data to Wavefront.
3. Create a WavefrontSpanReporter instance to report trace data to Wavefront.
4. Create the WavefrontTracer instance.
5. Initialize the OpenTracing global tracer.

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

func NewGlobalTracer(serviceName string) io.Closer {

    config := &wavefront.ProxyConfiguration{
        Host:        "<PROXY_IP/PROXY_FQDN>",
        TracingPort: <PROXY_TRACING_PORT>,
    }
    sender, err := wavefront.NewProxySender(config)
    if err != nil {
        log.Printf("Couldn't create Wavefront Sender: %s\n", err.Error())
        os.Exit(1)
    }

    appTags     := application.New(applicationName, serviceName)
    directrep   := wfreporter.New(sender, appTags)
    consolerep  := wfreporter.NewConsoleSpanReporter(serviceName)
    reporter    := wfreporter.NewCompositeSpanReporter(directrep, consolerep)
    tracer      := wftracer.New(reporter)

    opentracing.SetGlobalTracer(tracer)

    return ioutil.NopCloser(nil)

}

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 a Tags object. See Application Tags for details.

The following example specifies values for the 2 required tags (application and service).
Example:

appTags := application.New("OrderingApp", "inventory")

2. Set Up a Wavefront Sender

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

• If you have already set up a Wavefront sender for another SDK that runs in the same process, use that one. For details, see Share a Wavefront Sender.

• Otherwise, set up a Wavefront Sender to configure a proxy Sender or a direct Sender.

The following example configures a direct Sender with default direct ingestion properties.
Example:

directCfg := &senders.DirectConfiguration{
  Server: "https://INSTANCE.wavefront.com",
  Token:  "YOUR_API_TOKEN",
}

sender, err := senders.NewDirectSender(directCfg)
if err != nil {
  panic(err)
}

3. Set Up a Reporter

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

Create a WavefrontSpanReporter

To create a WavefrontSpanReporter, you specify:

• The Wavefront sender from Step 2, i.e., either a proxy Sender or a direct Sender.
• The Tags instance from Step 1.
• (Optional) A nondefault source for the reported spans.

This example creates a WavefrontSpanReporter that assigns the default source (the hostname) to the reported spans.
Example:

reporter := reporter.New(sender, appTags)

This example creates a WavefrontSpanReporter that assigns the specified source to the reported spans.
Example:

reporter := reporter.New(sender, appTags, reporter.Source("app1.foo.com"))

Add Custom Span-Level RED metrics (Optional)

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

Example:

reporter := reporter.New(sender, appTags, reporter.RedMetricsCustomTagKeys([2]string{"env", "location"}))

Create a CompositeSpanReporter (Optional)

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

wfReporter := reporter.New(sender, appTags, reporter.Source("app1.foo.com"))
clReporter := reporter.NewConsoleSpanReporter("app1.foo.com") //Specify the same source you used for the WavefrontSpanReporter
reporter := reporter.NewCompositeSpanReporter(wfReporter, clReporter)

4. Create the WavefrontTracer

To create a WavefrontTracer, you initialize it with the Reporter instance you created in the previous step:

tracer := tracer.New(reporter)

Sampling (Optional)

Optionally, you can create the WavefrontTracer with one or more sampling strategies. See the sampling documentation for details.

tracer.New(reporter, WithSampler(sampler))

5. Initialize the Global Tracer

To create a global tracer, you initialize it with the WavefrontTracer you created in the previous step:

opentracing.InitGlobalTracer(tracer)

Note: After you initialize the global tracer, completed spans are automatically reported to Wavefront and you do not need to start the reporter explicitly.

Span Logs

You can instrument your application to emit one or more logs with a span, and examine the logs from the Tracing UI.

Use the OpenTracing Span object’s LogFields() 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.

Monitoring the SDK

See the diagnostic metrics documentation for details on the internal metrics that this SDK collects and reports to Wavefront.

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.