Metadata-Version: 2.4
Name: otelize
Version: 0.0.2
Summary: A Python decorator to add OTEL auto-instrumentation to your functions
Author-email: "Diego J. Romero López" <diegojromerolopez@gmail.com>
Project-URL: repository, https://github.com/diegojromerolopez/otelize
Project-URL: documentation, https://github.com/diegojromerolopez/otelize/blob/main/README.md
Project-URL: Bug Tracker, https://github.com/diegojromerolopez/otelize/issues
Keywords: telemetry,OTEL,auto-instrumentation,decorator
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api>=1.36.0
Dynamic: license-file

# otelize

![test](https://github.com/diegojromerolopez/otelize/actions/workflows/test.yml/badge.svg)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/diegojromerolopez/otelize/graphs/commit-activity)
[![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/otelize.svg)](https://pypi.python.org/pypi/otelize/)
[![PyPI version otelize](https://badge.fury.io/py/otelize.svg)](https://pypi.python.org/pypi/otelize/)
[![PyPI status](https://img.shields.io/pypi/status/otelize.svg)](https://pypi.python.org/pypi/otelize/)
[![PyPI download month](https://img.shields.io/pypi/dm/otelize.svg)](https://pypi.python.org/pypi/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

### The otelize decorator

Just add the `@otelize` decorator to your functions:

```python
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 it would be equivalent to do this:

```python
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({
            'a_param': a_param,
            'another_param': another_param,
            'a_list': json.dumps(a_list),
            'a_dict': json.dumps(a_dict),
        })
```

### Avoiding leaking secrets

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

- `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 False.

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:

```python
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](otelize/tests).

## Dependencies
The runtime depends only on [opentelemetry-api](https://pypi.org/project/opentelemetry-api/), and for testing
it depends on [opentelemetry-sdk](https://pypi.org/project/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) license, but if you need any other contact me.

## Disclaimer
This project is not affiliated with, endorsed by, or sponsored by
the [OpenTelemetry](https://opentelemetry.io/) project owners,
the [Cloud Native Computing Foundation](https://www.cncf.io/).

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.
