| Name | otelize JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | A Python decorator to add OTEL auto-instrumentation to your functions |
| upload_time | 2025-10-11 17:35:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
telemetry
otel
auto-instrumentation
decorator
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# otelize
[](https://opensource.org/licenses/MIT)
[](https://github.com/diegojromerolopez/otelize/graphs/commit-activity)
[](https://www.python.org/)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](https://pypi.python.org/pypi/otelize/)
[](https://pypi.python.org/pypi/otelize/)
[](https://pypi.python.org/pypi/otelize/)
[](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
See the [official documentation in readthedocs.io](https://otelize.readthedocs.io/en/latest/).
### 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:
```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, and if you call the arguments as positional arguments, e.g.
```python
your_function(a_param, another_param, a_list, a_dict)
```
it would be equivalent to doing:
```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({
'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.
```python
your_function(a_param='a', another_param=2, a_list=[1,2,3], a_dict={'a': 1})
```
it would be equivalent to doing:
```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({
'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:
```python
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.
```python
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.
```python
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.:
```python
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
```python
your_function('a_param', 'another_param', a_list=[1, 2, 3], a_dict={'a': 'a'})
```
would be equal to this code:
```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.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:
```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.
Raw data
{
"_id": null,
"home_page": null,
"name": "otelize",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "telemetry, OTEL, auto-instrumentation, decorator",
"author": null,
"author_email": "\"Diego J. Romero L\u00f3pez\" <diegojromerolopez@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/27/da/08753909fcc8e41a42abc82d20f6a48ce95e399740ccc0c289231e9e539c/otelize-0.4.1.tar.gz",
"platform": null,
"description": "# otelize\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/diegojromerolopez/otelize/graphs/commit-activity)\n[](https://www.python.org/)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n[](https://pypi.python.org/pypi/otelize/)\n[](https://pypi.python.org/pypi/otelize/)\n[](https://pypi.python.org/pypi/otelize/)\n[](https://pypi.python.org/pypi/otelize/)\n\nAdd OTEL auto-instrumentation to your functions.\n\n## Introduction\nThis is a simple package intended for the use of lazy developers that want to included basic OTEL telemetry to their\nproject without bothering much with adding a lot of boilerplate. \n\n## How it works\nThis package provides the otelize decorator that wraps a function and adds all your parameters (with their values) and\nthe returning value as span attributes. \n\n## How to use it\n\nSee the [official documentation in readthedocs.io](https://otelize.readthedocs.io/en/latest/).\n\n### The otelize decorator\n\nThis package provides an `@otelize` decorator for applying it on functions and classes.\n\n#### The otelize decorator on functions\n\nJust add the `@otelize` decorator to your functions:\n\n```python\nfrom otelize import otelize\n\n@otelize\ndef your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):\n ...\n```\n\nAll the parameters and the return value will be added as attributes to the OTEL span created for the function.\n\nIn this case, and if you call the arguments as positional arguments, e.g.\n\n```python\nyour_function(a_param, another_param, a_list, a_dict)\n```\n\nit would be equivalent to doing:\n\n```python\nimport json\n\nfrom opentelemetry import trace\n\ntracer = trace.get_tracer(__name__)\n\ndef your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):\n with tracer.start_as_current_span('your_function') as span:\n span.set_attributes({\n 'function.call.arg.0.value': a_param,\n 'function.call.arg.1.value': another_param,\n 'function.call.arg.2.value': json.dumps(a_list),\n 'function.call.arg.3.value': json.dumps(a_dict),\n })\n```\n\nOn the other hand, in the case of using named-arguments, it will be slightly different, e.g.\n\n```python\nyour_function(a_param='a', another_param=2, a_list=[1,2,3], a_dict={'a': 1})\n```\n\nit would be equivalent to doing:\n\n```python\nimport json\n\nfrom opentelemetry import trace\n\ntracer = trace.get_tracer(__name__)\n\ndef your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):\n with tracer.start_as_current_span('your_function') as span:\n span.set_attributes({\n 'function.call.kwarg.a_param': a_param,\n 'function.call.kwarg.another_param': another_param,\n 'function.call.kwarg.a_list': json.dumps(a_list),\n 'function.call.kwarg.a_dict': json.dumps(a_dict),\n })\n```\n\n#### The otelize decorator on classes\n\nJust add the @otelize decorator to a class, like in the following example:\n\n```python\nfrom otelize import otelize\n\n@otelize\nclass DummyCalculator:\n floating_point_character = '.'\n\n def __init__(self, initial_value: float) -> None:\n self.__value = initial_value\n\n def __str__(self) -> str:\n return f'Calculator with {self.__value}'\n\n def add(self, other: float) -> float:\n self.__value += other\n return self.__value\n\n def subtract(self, other: float) -> float:\n self.__value -= other\n return self.__value\n```\n\nThis will add a span context in each instance method, class method or static method.\n\nThe arguments will be added in the same way that they were being added to functions.\n\nThere is a limitation, that is that the dunder methods (e.g. `__method__`) are ignored.\n\n### The otelize_iterable wrapper\n\n#### otelize_iterable on iterables\n\nJust wrap your loopable data structure with the otelize_iterable wrapper to get a generator that yields a span\nand the item.\n\n```python\nfrom otelize import otelize_iterable\n\nfor span, item in otelize_iterable([1, 2, 3]):\n pass\n # span.set_attributes({ your other attributes })\n```\n\n#### otelize_iterable on generators\n\nJust wrap your iterable with the otelize_iterable wrapper to get a generator that yields a span and the item.\n\n```python\nfrom collections.abc import Generator\nfrom otelize import otelize_iterable\n\n\ndef dummy_generator() -> Generator[str, None, None]:\n yield 'first'\n yield 'second'\n yield 'third'\n\n\nfor span, item in otelize_iterable(dummy_generator()):\n pass\n # span.set_attributes({ your other attributes })\n```\n\n### The otelize_context_manager wrapper\nWrap a context manager with `otelize_context_manager` and you will get a span that you can use inside the inner code.\ne.g.:\n\n```python\nimport os\nimport tempfile\n\nwith otelize_context_manager(tempfile.NamedTemporaryFile()) as (temp_file_span, temp_file):\n temp_file.write(b'hello')\n # more writing ...\n temp_file.flush()\n\n temp_file_span.set_attributes({\n 'temp_file.size': os.path.getsize(temp_file.name)\n })\n```\n\n### Configuration\n\nThe following configuration settings can be set via environment variables:\n\n- `OTELIZE_USE_SPAN_ATTRIBUTES`: if true it will use OTEL span attributes. By default is `'true'`.\n- `OTELIZE_USE_EVENT_ATTRIBUTES`: if true it will create anew OTEL event with attributes. By default is `'true'`.\n- `OTELIZE_SPAN_REDACTABLE_ATTRIBUTES`: JSON array of attributes that need to be redacted in your OTEL. By default is `'[]'`\n- `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: `'(?!)'`.\n- `OTELIZE_SPAN_RETURN_VALUE_IS_INCLUDED`: Truthy or falsy value. By default, it is `'true'`.\n\n### Use span events\n\nIf you set the environment variable `OTELIZE_USE_EVENT_ATTRIBUTES` to true, a new span event will be added with the\nfunction arguments and return value.\n\nFor example:\n\nThis call\n\n```python\nyour_function('a_param', 'another_param', a_list=[1, 2, 3], a_dict={'a': 'a'})\n```\n\nwould be equal to this code:\n\n```python\nimport json\n\nfrom opentelemetry import trace\n\ntracer = trace.get_tracer(__name__)\n\ndef your_function(a_param: str, another_param: int, a_list: list[float], a_dict: dict[str, str]):\n with tracer.start_as_current_span('your_function') as span:\n span.add_event(\n 'function.call', {\n 'args': json.dumps(('a_param', 'another_param')),\n 'kwarg': json.dumps({'a_list': [1, 2, 3], 'a_dict': {'a': 'a'}}),\n 'return_value': None,\n },\n )\n```\n\n### Avoid leaks of secrets\n\nTo avoid leaking values of sensitive parameters, define the following environment values:\n\n- `OTELIZE_SPAN_REDACTABLE_ATTRIBUTES` or\n- `OTELIZE_SPAN_REDACTABLE_ATTRIBUTES_REGEX`\n\nThe redacted attributes will have the `'[REDACTED]'` value.\n\n### Adding additional information from the decorated function\n\nCall `trace.get_current_span()` to get the current span from inside the function:\n\n```python\nfrom typing import Any\nfrom opentelemetry import trace\nfrom otelize import otelize\n\n\n@otelize\ndef your_function(a_param: str, another_param: int, and_another_one: Any):\n span = trace.get_current_span()\n span.set_attribute('custom_attr', 'your value')\n```\n\n### Examples\nThere are more examples in the [test folder](otelize/tests).\n\n## Dependencies\nThe runtime depends only on [opentelemetry-api](https://pypi.org/project/opentelemetry-api/), and for testing\nit depends on [opentelemetry-sdk](https://pypi.org/project/opentelemetry-sdk/) and other test coverage and\nformatting packages (coverage, black, flake8...).\n\n## Python version support\nThe minimum Python supported version is 3.10.\n\n## Collaborations\nThis project is open to collaborations. Make a PR or an issue,\nand I'll take a look to it.\n\n## License\n[MIT](LICENSE) license, but if you need any other contact me.\n\n## Disclaimer\nThis project is not affiliated with, endorsed by, or sponsored by\nthe [OpenTelemetry](https://opentelemetry.io/) project owners,\nthe [Cloud Native Computing Foundation](https://www.cncf.io/).\n\nThe use of the names \"OTEL\" and \"otelize\"\nin this repository is solely for descriptive purposes\nand does not imply any association or intent to infringe\non any trademarks.\n\nThe project is named \"otelize\" for purposes of having\na short name that can be used as a Python decorator.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python decorator to add OTEL auto-instrumentation to your functions",
"version": "0.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/diegojromerolopez/otelize/issues",
"documentation": "https://otelize.readthedocs.io/en/latest/",
"repository": "https://github.com/diegojromerolopez/otelize"
},
"split_keywords": [
"telemetry",
" otel",
" auto-instrumentation",
" decorator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8721b3e5834084857118bc866e9c7b64d7e2d26a3634c7131ee366b0a0cdedd4",
"md5": "af3b50cd94d3ed6010657620124c5eaa",
"sha256": "7fadd2ca5a9357235ec522771b643bd8a9b3b78cca2a86a1a7e9b3de318133f1"
},
"downloads": -1,
"filename": "otelize-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af3b50cd94d3ed6010657620124c5eaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18729,
"upload_time": "2025-10-11T17:35:23",
"upload_time_iso_8601": "2025-10-11T17:35:23.117996Z",
"url": "https://files.pythonhosted.org/packages/87/21/b3e5834084857118bc866e9c7b64d7e2d26a3634c7131ee366b0a0cdedd4/otelize-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "27da08753909fcc8e41a42abc82d20f6a48ce95e399740ccc0c289231e9e539c",
"md5": "90f95fc386910ac57a1ff02bea2973a5",
"sha256": "25c89df39b91f578bbd5ce96b314646dfa14eefa594e0aa68e0a75e544c9ad77"
},
"downloads": -1,
"filename": "otelize-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "90f95fc386910ac57a1ff02bea2973a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15411,
"upload_time": "2025-10-11T17:35:24",
"upload_time_iso_8601": "2025-10-11T17:35:24.844050Z",
"url": "https://files.pythonhosted.org/packages/27/da/08753909fcc8e41a42abc82d20f6a48ce95e399740ccc0c289231e9e539c/otelize-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 17:35:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "diegojromerolopez",
"github_project": "otelize",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "otelize"
}
