Skip to main content

Python extensions for OpenTelemetry

Project description

otel-extensions-python: OpenTelemetry Extensions for Python

OpenTelemetry Extensions for Python is a collection of helper classes, functions, and decorators to facilitate the use of the OpenTelemetry Python API & SDK packages

Version Support

Python >= 3.6

Installation

pip install

You can install through pip using:

pip install otel-extensions

(you may need to run pip with root permission: sudo pip install otel-extensions)

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Features

Tracer Provider Initialization

from otel_extensions import init_telemetry_provider, TelemetryOptions

# Provide options for telemetry provider
# Alternatively, any of the following options can be specified through
# environment variables with the equivalent name
options = TelemetryOptions(
    # OTLP receiver endpoint
    OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317/",
    # CA bundle for TLS verification of endpoint (if endpoint scheme is https)
    OTEL_EXPORTER_OTLP_CERTIFICATE="/path/to/ca/bundle",
    # protocol for OTLP receiver (supported: gprc | http/protobuf | custom)
    OTEL_EXPORTER_OTLP_PROTOCOL="grpc",
    # Custom span exporter class name (needed if protocol set to 'custom')
    OTEL_EXPORTER_CUSTOM_SPAN_EXPORTER_TYPE="pkg.ClassName",
    # Name of service
    OTEL_SERVICE_NAME="My Service",
    # Processor type
    #   batch:  use BatchSpanProcessor
    #   simple: use SimpleSpanProcessor
    OTEL_PROCESSOR_TYPE="batch",
    # Optional parent span id.  Will be injected into current context
    TRACEPARENT="001233454656...."
)
# Initialize the global tracer provider
init_telemetry_provider(options)

Instrumentation Decorator

You can use the @instrumented decorator to automatically wrap a span around a function or method

from otel_extensions import init_telemetry_provider, instrumented

@instrumented
def foo():
    """Creates a span named 'foo'"""
    bar()

@instrumented(span_name="custom span name")
def bar():
    """Creates a span named 'custom span name'"""
    print("Hello World")

if __name__ == '__main__':
    # init telemetry provider (using options from environment variables)
    init_telemetry_provider()
    foo()

Trace Context helper class

The TraceContextCarrier class is useful when propagating context across process or thread boundaries

from otel_extensions import TraceContextCarrier
from threading import Thread


def main_program():
    ...
    # capture current context
    ctx = TraceContextCarrier()
    thread = Thread(thread_func, args=(ctx))
    thread.start()
    ...

def thread_func(ctx: TraceContextCarrier):
    # attach to context stored in ctx
    ctx.attach()
    ...

Also, the TraceContextCarrier class can attach to context stored in the TRACEPARENT environment variable. Note that this is done automatically when calling the init_telemetry_provider() function.

from otel_extensions import TraceContextCarrier

TraceContextCarrier.attach_from_env()

TraceContextCarrier can also inject the current context into the TRACEPARENT environment variable. This is useful for context propagation when using Popen to create a subprocess

from otel_extensions import TraceContextCarrier
from subprocess import Popen

TraceContextCarrier.inject_to_env()
process = Popen(...)

Log messages as events

The TraceEventLogHandler class is a logging.Handler class that creates events for any log message that occurs in a span.

from otel_extensions import TraceEventLogHandler, init_telemetry_provider, get_tracer
import logging

init_telemetry_provider()

logging.basicConfig()
logging.getLogger(__name__).addHandler(TraceEventLogHandler())

with get_tracer(__name__).start_as_current_span("foo") as span:
    logging.getLogger(__name__).warning("Some log message")
    # 'Some Log message' will be created as an event in 'span',
    # as if you had called
    # span.add_event('Some Log message')

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

otel-extensions-0.1.2.tar.gz (10.3 kB view hashes)

Uploaded source

Built Distribution

otel_extensions-0.1.2-py2.py3-none-any.whl (10.3 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page