wavefront-opentracing-sdk-python

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
Span Logs
Cross Process Context Propagation
RED Metrics
License
How to Contribute

Welcome to Wavefront's Python SDK

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

The Wavefront OpenTracing SDK for Python automatically reports metrics, custom trace data, and derived metrics.

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

Note:

This is the Wavefront by VMware OpenTracing SDK for Python! 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 Rate Errors Duration (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

This SDK supports Python 3.x.

pip install wavefront-opentracing-sdk-python

Usage

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

This SDK provides a WavefrontTracer to create spans and send them to Wavefront. The WavefrontTracer also automatically generates and reports RED metrics from your spans.

Follow these steps to create a WavefrontTracer:

Create an ApplicationTags instance, to specify metadata about your application.
Create a WavefrontSender instance to send trace data to Wavefront.
Create a WavefrontSpanReporter instance to report trace data to Wavefront.
Create the WavefrontTracer instance.

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

tracer = WavefrontTracer(reporter=reporter, application_tags=application_tags)

1. Set Up Application Tags

Application tags describe the structure of your application. They are included with every span reported to Wavefront and are associated with span tags that you can use to filter and query trace data in Wavefront.

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

2. Set Up a WavefrontSender

A WavefrontSender 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 WavefrontSender for another SDK that runs in the same process, use that one. (For details about sharing a Wavefront sender, see Share a Wavefront Sender.
Otherwise, Set Up a Wavefront Sender.

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 to print to the console.

Create a WavefrontSpanReporter

To create a WavefrontSpanReporter:

Specify the Wavefront sender from Step 2, i.e. either WavefrontProxyClient or WavefrontDirectClient.
(Optional) Specify a string that represents the source for the reported spans. If you omit the source, the host name is used.

Example: Create a WavefrontSpanReporter:

import wavefront_opentracing_sdk.reporting
from wavefront_sdk import WavefrontDirectClient
  # or
  # from wavefront_sdk import WavefrontProxyClient

wavefront_sender = ...   # see Step 2

wf_span_reporter = wavefront_opentracing_sdk.reporting.WavefrontSpanReporter(
    client=wavefront_sender,
    source='wavefront-tracing-example'   # optional nondefault source name
)

# To get failures observed while reporting.
total_failures = wf_span_reporter.get_failure_count()

Note: After you initialize the WavefrontTracer with the WavefrontSpanReporter (below), completed spans are automatically 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.

from wavefront_opentracing_sdk.reporting import CompositeReporter
from wavefront_opentracing_sdk.reporting import ConsoleReporter
from wavefront_opentracing_sdk.reporting import WavefrontSpanReporter

wf_span_reporter = ...

# Create a console reporter that reports span to stdout
console_reporter = ConsoleReporter(source='wavefront-tracing-example')

# Instantiate a composite reporter composed of console and WavefrontSpanReporter.
composite_reporter = CompositeReporter(wf_span_reporter, console_reporter)

4. Create a WavefrontTracer

To create a WavefrontTracer, you pass the ApplicationTags and Reporter instances you created in the previous steps:

import wavefront_opentracing_sdk

from wavefront_opentracing_sdk.reporting import WavefrontSpanReporter
from wavefront_sdk.common import ApplicationTags
from wavefront_sdk import WavefrontDirectClient
  # or
  # from wavefront_sdk import WavefrontProxyClient

application_tags = ...   # see Step 1 above
wf_span_reporter = ...   # see Step 3 above

# Construct Wavefront opentracing Tracer
tracer = wavefront_opentracing_sdk.WavefrontTracer(
    reporter=wf_span_reporter,
    application_tags=application_tags)

Add Custom Span-Level RED metrics

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

# Construct Wavefront opentracing Tracer
tracer = wavefront_opentracing_sdk.WavefrontTracer(
    reporter=wf_span_reporter,
    application_tags=application_tags,
    red_metrics_custom_tag_keys={'env', 'location'})

Close the Tracer

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

tracer.close()

Span Logs

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_kv() 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.

vmware-archive/wavefront-opentracing-sdk-python