# otel-extensions-pytest: A pytest extension for OpenTelemetry
`otel-extensions-pytest` is a pytest plugin that will automatically instrument a pytest-based test session,
wrapping the test session in a span and wrapping each test in a child span.
## Dependencies
* Python >= 3.6
* pytest >= 6.2
## Installation
### pip install
You can install through pip using:
```sh
pip install otel-extensions-pytest
```
(you may need to run `pip` with root permission: `sudo pip install otel-extensions-pytest`)
### Setuptools
Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
```sh
python setup.py install --user
```
(or `sudo python setup.py install` to install the package for all users)
## Usage
Enable the plugin by adding
```python
pytest_plugins = ("otel_extensions_pytest",)
```
to your `conftest.py`, or by adding the option `-p otel_extensions_pytest` to the pytest command line.
For tracing to be enabled, you need to specify a trace receiver endpoint using the command-line option
`--otel-endpoint` or by setting the environment variable `OTEL_EXPORTER_OTLP_ENDPOINT`.
e.g. `--otel-endpoint http://localhost:4317/`
The full set of options are shown here:
| Command-line Option | Environment Variable | Description |
|-------------------------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--otel_service_name` | `OTEL_SERVICE_NAME` | Name of resource/service for traces |
| `--otel_session_name` | `OTEL_SESSION_NAME` | Name of parent session span |
| `--otel_endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP Receiver Endpoint |
| `--otel_protocol` | `OTEL_EXPORTER_OTLP_PROTOCOL` | protocol for OTLP receiver (supported: `gprc` , `http/protobuf` , `custom`) |
| `--otel_processor_type` | `OTEL_PROCESSOR_TYPE` | Span Processor type (batch: use `BatchSpanProcessor`, simple: use `SimpleSpanProcessor` |
| `--otel_traceparent` | `TRACEPARENT` | Parent span id. Will be injected into current context (useful when running automated tests using the [OpenTelemetry Jenkins](https://plugins.jenkins.io/opentelemetry/) plugin) |
| n/a | `OTEL_EXPORTER_OTLP_CERTIFICATE` | path to CA bundle for verifying TLS cert of receiver endpoint |
| n/a | `OTEL_EXPORTER_CUSTOM_SPAN_EXPORTER_TYPE` | Custom span exporter class (needed if protocol set to `custom`) |
## Additional Features
### `@instrumented_fixture` decorator
You can decorate fixtures by using the `@instrumented_fixture` decorator. If the fixture is a generator (i.e. has a `yield` statement), separate spans will be created for the setup and teardown phases.
```python
from otel_extensions_pytest import instrumented_fixture
# note: all options of pytest.fixture() are supported (autouse, etc)
@instrumented_fixture(scope="function")
def my_fixture():
""" Span is automatically created using `my_fixture` as span name """
return "foo"
@instrumented_fixture(scope="function")
def my_generator_fixture():
# A span named `my_generator_fixture (setup)` is automatically created for this section
time.sleep(5)
yield "foo"
# A span named `my_generator_fixture (teardown)` is automatically created for this section
time.sleep(5)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/s4v4g3/otel-extensions-pytest",
"name": "otel-extensions-pytest",
"maintainer": "Joe Savage",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "joe.savage@gmail.com",
"keywords": "otel,opentelemetry,debug,pytest",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/84/2d/a31966cba1e0946e7e833c8be2d15d5039c6cace1c773651fd5491bbd4b4/otel-extensions-pytest-0.2.1.tar.gz",
"platform": "any",
"description": "# otel-extensions-pytest: A pytest extension for OpenTelemetry\r\n\r\n`otel-extensions-pytest` is a pytest plugin that will automatically instrument a pytest-based test session, \r\nwrapping the test session in a span and wrapping each test in a child span.\r\n\r\n## Dependencies\r\n\r\n* Python >= 3.6\r\n* pytest >= 6.2\r\n\r\n## Installation\r\n### pip install\r\n\r\nYou can install through pip using:\r\n\r\n```sh\r\npip install otel-extensions-pytest\r\n```\r\n(you may need to run `pip` with root permission: `sudo pip install otel-extensions-pytest`)\r\n\r\n\r\n### Setuptools\r\n\r\nInstall via [Setuptools](http://pypi.python.org/pypi/setuptools).\r\n\r\n```sh\r\npython setup.py install --user\r\n```\r\n(or `sudo python setup.py install` to install the package for all users)\r\n\r\n\r\n\r\n## Usage\r\n\r\nEnable the plugin by adding\r\n```python\r\npytest_plugins = (\"otel_extensions_pytest\",)\r\n```\r\nto your `conftest.py`, or by adding the option `-p otel_extensions_pytest` to the pytest command line. \r\n\r\nFor tracing to be enabled, you need to specify a trace receiver endpoint using the command-line option\r\n`--otel-endpoint` or by setting the environment variable `OTEL_EXPORTER_OTLP_ENDPOINT`.\r\ne.g. `--otel-endpoint http://localhost:4317/`\r\n\r\n\r\nThe full set of options are shown here:\r\n\r\n| Command-line Option | Environment Variable | Description |\r\n|-------------------------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| `--otel_service_name` | `OTEL_SERVICE_NAME` | Name of resource/service for traces |\r\n| `--otel_session_name` | `OTEL_SESSION_NAME` | Name of parent session span |\r\n| `--otel_endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP Receiver Endpoint |\r\n| `--otel_protocol` | `OTEL_EXPORTER_OTLP_PROTOCOL` | protocol for OTLP receiver (supported: `gprc` , `http/protobuf` , `custom`) |\r\n| `--otel_processor_type` | `OTEL_PROCESSOR_TYPE` | Span Processor type (batch: use `BatchSpanProcessor`, simple: use `SimpleSpanProcessor` |\r\n| `--otel_traceparent` | `TRACEPARENT` | Parent span id. Will be injected into current context (useful when running automated tests using the [OpenTelemetry Jenkins](https://plugins.jenkins.io/opentelemetry/) plugin) |\r\n| n/a | `OTEL_EXPORTER_OTLP_CERTIFICATE` | path to CA bundle for verifying TLS cert of receiver endpoint |\r\n| n/a | `OTEL_EXPORTER_CUSTOM_SPAN_EXPORTER_TYPE` | Custom span exporter class (needed if protocol set to `custom`) |\r\n\r\n## Additional Features\r\n\r\n### `@instrumented_fixture` decorator\r\n\r\nYou can decorate fixtures by using the `@instrumented_fixture` decorator. If the fixture is a generator (i.e. has a `yield` statement), separate spans will be created for the setup and teardown phases.\r\n\r\n\r\n```python\r\nfrom otel_extensions_pytest import instrumented_fixture\r\n\r\n# note: all options of pytest.fixture() are supported (autouse, etc)\r\n@instrumented_fixture(scope=\"function\")\r\ndef my_fixture():\r\n \"\"\" Span is automatically created using `my_fixture` as span name \"\"\"\r\n return \"foo\"\r\n\r\n@instrumented_fixture(scope=\"function\")\r\ndef my_generator_fixture():\r\n # A span named `my_generator_fixture (setup)` is automatically created for this section\r\n time.sleep(5)\r\n \r\n yield \"foo\"\r\n \r\n # A span named `my_generator_fixture (teardown)` is automatically created for this section\r\n time.sleep(5)\r\n \r\n```\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "pytest extensions for OpenTelemetry",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/s4v4g3/otel-extensions-pytest",
"Source": "https://github.com/s4v4g3/otel-extensions-pytest",
"Tracker": "https://github.com/s4v4g3/otel-extensions-pytest/issues"
},
"split_keywords": [
"otel",
"opentelemetry",
"debug",
"pytest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e59f21d5b5896516de3270d5f537da0aaee8e3245b44bfdb33906746ae8f123",
"md5": "207e1b8fc0766611795a5fb2427ed571",
"sha256": "e7ab3adbc0ff469eb8e04e973e4a197265fd929c95f35781e1e9fff91a1ea0ea"
},
"downloads": -1,
"filename": "otel_extensions_pytest-0.2.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "207e1b8fc0766611795a5fb2427ed571",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 11843,
"upload_time": "2024-03-08T22:06:56",
"upload_time_iso_8601": "2024-03-08T22:06:56.636650Z",
"url": "https://files.pythonhosted.org/packages/3e/59/f21d5b5896516de3270d5f537da0aaee8e3245b44bfdb33906746ae8f123/otel_extensions_pytest-0.2.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "842da31966cba1e0946e7e833c8be2d15d5039c6cace1c773651fd5491bbd4b4",
"md5": "83c3f7b27c41990df2d11f2e6a92b5ee",
"sha256": "2812572eed594c7e7e0e526d186aeb83be698e45b1130f15c280c094b805bfdd"
},
"downloads": -1,
"filename": "otel-extensions-pytest-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "83c3f7b27c41990df2d11f2e6a92b5ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12527,
"upload_time": "2024-03-08T22:06:58",
"upload_time_iso_8601": "2024-03-08T22:06:58.400457Z",
"url": "https://files.pythonhosted.org/packages/84/2d/a31966cba1e0946e7e833c8be2d15d5039c6cace1c773651fd5491bbd4b4/otel-extensions-pytest-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 22:06:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "s4v4g3",
"github_project": "otel-extensions-pytest",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "opentelemetry-api",
"specs": []
},
{
"name": "opentelemetry-sdk",
"specs": []
},
{
"name": "otel-extensions",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.2.0"
]
]
},
{
"name": "typing_extensions",
"specs": []
}
],
"tox": true,
"lcname": "otel-extensions-pytest"
}
JSON
