Skip to content
This repository has been archived by the owner on Jan 19, 2023. It is now read-only.

vmware-archive/wavefront-opentracing-sdk-go

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

75 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

wavefront-opentracing-sdk-go

build status Go Report Card GoDoc OpenTracing Badge

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

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!

Go Tracing SDK Decision Tree

Note:

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.
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.
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.
Sender SDK Lets you send raw values to Wavefront for storage as metrics, histograms, or traces, e.g., to import CSV data into Wavefront.

Prerequisites

  • 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.

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.