otelize 0.4.0

A Python decorator to add OTEL auto-instrumentation to your functions

otelize

Add OTEL auto-instrumentation to your functions.

Introduction

This is a simple package intended for the use of lazy developers that want to included basic OTEL telemetry to their project without bothering much with adding a lot of boilerplate.

How it works

This package provides the otelize decorator that wraps a function and adds all your parameters (with their values) and the returning value as span attributes.

How to use it

See the official documentation in readthedocs.io.

The otelize decorator

This package provides an @otelize decorator for applying it on functions and classes.

The otelize decorator on functions

Just add the @otelize decorator to your functions:

from otelize import otelize

@otelize
def your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):
    ...

All the parameters and the return value will be added as attributes to the OTEL span created for the function.

In this case, and if you call the arguments as positional arguments, e.g.

your_function(a_param, another_param, a_list, a_dict)

it would be equivalent to doing:

import json

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):
    with tracer.start_as_current_span('your_function') as span:
        span.set_attributes({
            'function.call.arg.0.value': a_param,
            'function.call.arg.1.value': another_param,
            'function.call.arg.2.value': json.dumps(a_list),
            'function.call.arg.3.value': json.dumps(a_dict),
        })

On the other hand, in the case of using named-arguments, it will be slightly different, e.g.

your_function(a_param='a', another_param=2, a_list=[1,2,3], a_dict={'a': 1})

it would be equivalent to doing:

import json

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):
    with tracer.start_as_current_span('your_function') as span:
        span.set_attributes({
            'function.call.kwarg.a_param': a_param,
            'function.call.kwarg.another_param': another_param,
            'function.call.kwarg.a_list': json.dumps(a_list),
            'function.call.kwarg.a_dict': json.dumps(a_dict),
        })

The otelize decorator on classes

Just add the @otelize decorator to a class, like in the following example:

from otelize import otelize

@otelize
class DummyCalculator:
    floating_point_character = '.'

    def __init__(self, initial_value: float) -> None:
        self.__value = initial_value

    def __str__(self) -> str:
        return f'Calculator with {self.__value}'

    def add(self, other: float) -> float:
        self.__value += other
        return self.__value

    def subtract(self, other: float) -> float:
        self.__value -= other
        return self.__value

This will add a span context in each instance method, class method or static method.

The arguments will be added in the same way that they were being added to functions.

There is a limitation, that is that the dunder methods (e.g. __method__) are ignored.

The otelize_iterable wrapper

otelize_iterable on iterables

Just wrap your loopable data structure with the otelize_iterable wrapper to get a generator that yields a span and the item.

from otelize import otelize_iterable

for span, item in otelize_iterable([1, 2, 3]):
    pass
    # span.set_attributes({ your other attributes })

otelize_iterable on generators

Just wrap your iterable with the otelize_iterable wrapper to get a generator that yields a span and the item.

from collections.abc import Generator
from otelize import otelize_iterable


def dummy_generator() -> Generator[str, None, None]:
    yield 'first'
    yield 'second'
    yield 'third'


for span, item in otelize_iterable(dummy_generator()):
    pass
    # span.set_attributes({ your other attributes })

The otelize_context_manager wrapper

Wrap a context manager with otelize_context_manager and you will get a span that you can use inside the inner code. e.g.:

import os
import tempfile

with otelize_context_manager(tempfile.NamedTemporaryFile()) as (temp_file_span, temp_file):
    temp_file.write(b'hello')
    # more writing ...
    temp_file.flush()

    temp_file_span.set_attributes({
        'temp_file.size': os.path.getsize(temp_file.name)
    })

Configuration

The following configuration settings can be set via environment variables:

• OTELIZE_USE_SPAN_ATTRIBUTES: if true it will use OTEL span attributes. By default is 'true'.
• OTELIZE_USE_EVENT_ATTRIBUTES: if true it will create anew OTEL event with attributes. By default is 'true'.
• OTELIZE_SPAN_REDACTABLE_ATTRIBUTES: JSON array of attributes that need to be redacted in your OTEL. By default is '[]'
• OTELIZE_SPAN_REDACTABLE_ATTRIBUTES_REGEX: string with a Python regex that will redact all attributes that match the regulax expression. By default, is an impossible regex: '(?!)'.
• OTELIZE_SPAN_RETURN_VALUE_IS_INCLUDED: Truthy or falsy value. By default, it is 'true'.

Use span events

If you set the environment variable OTELIZE_USE_EVENT_ATTRIBUTES to true, a new span event will be added with the function arguments and return value.

For example:

This call

your_function('a_param', 'another_param', a_list=[1, 2, 3], a_dict={'a': 'a'})

would be equal to this code:

import json

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):
    with tracer.start_as_current_span('your_function') as span:
        span.add_event(
            'function.call', {
                'args': json.dumps(('a_param', 'another_param')),
                'kwarg': json.dumps({'a_list': [1, 2, 3], 'a_dict': {'a': 'a'}}),
                'return_value': None,
            },
        )

Avoid leaks of secrets

To avoid leaking values of sensitive parameters, define the following environment values:

• OTELIZE_SPAN_REDACTABLE_ATTRIBUTES or
• OTELIZE_SPAN_REDACTABLE_ATTRIBUTES_REGEX

The redacted attributes will have the '[REDACTED]' value.

Adding additional information from the decorated function

Call trace.get_current_span() to get the current span from inside the function:

from typing import Any
from opentelemetry import trace
from otelize import otelize


@otelize
def your_function(a_param: str, another_param: int, and_another_one: Any):
    span = trace.get_current_span()
    span.set_attribute('custom_attr', 'your value')

Examples

There are more examples in the test folder.

Dependencies

The runtime depends only on opentelemetry-api, and for testing it depends on opentelemetry-sdk and other test coverage and formatting packages (coverage, black, flake8...).

Python version support

The minimum Python supported version is 3.10.

Collaborations

This project is open to collaborations. Make a PR or an issue, and I'll take a look to it.

License

MIT license, but if you need any other contact me.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by the OpenTelemetry project owners, the Cloud Native Computing Foundation.

The use of the names "OTEL" and "otelize" in this repository is solely for descriptive purposes and does not imply any association or intent to infringe on any trademarks.

The project is named "otelize" for purposes of having a short name that can be used as a Python decorator.