The Python special interest group (SIG) meets regularly. See the OpenTelemetry community repo for information on this and other language SIGs.
See the public meeting notes for a summary description of past meetings. To request edit access, join the meeting or get in touch on Slack.
See to the community membership document on how to become a Member, Approver and Maintainer.
Before you can contribute, you will need to sign the Contributor License Agreement.
Please also read the OpenTelemetry Contributor Guide.
- Find a Buddy and get Started Quickly
- Development
- Pull requests
- Design Choices
- Running Tests Locally
- Style Guide
- Guideline for instrumentations
- Expectations from contributors
If you are looking for someone to help you find a starting point and be a resource for your first contribution, join our Slack and find a buddy!
- Join Slack and join our chat room.
- Post in the room with an introduction to yourself, what area you are interested in (check issues marked "Help Wanted"), and say you are looking for a buddy. We will match you with someone who has experience in that area.
Your OpenTelemetry buddy is your resource to talk to directly on all aspects of contributing to OpenTelemetry: providing context, reviewing PRs, and helping those get merged. Buddies will not be available 24/7, but is committed to responding during their normal contribution hours.
This project uses tox to automate
some aspects of development, including testing against multiple Python versions.
To install tox
, run:
$ pip install tox
You can run tox
with the following arguments:
tox
to run all existing tox commands, including unit tests for all packages under multiple Python versionstox -e docs
to regenerate the API docstox -e py312-test-instrumentation-aiopg
to e.g. run the aiopg instrumentation unit tests under a specific Python versiontox -e spellcheck
to run a spellcheck on all the codetox -e lint-some-package
to run lint checks onsome-package
black
and isort
are executed when tox -e lint
is run. The reported errors can be tedious to fix manually.
An easier way to do so is:
- Run
.tox/lint/bin/black .
- Run
.tox/lint/bin/isort .
Or you can call formatting and linting in one command by pre-commit:
$ pre-commit
You can also configure it to run lint tools automatically before committing with:
$ pre-commit install
See
tox.ini
for more detail on available tox commands.
Some packages may require additional system wide dependencies to be installed. For example, you may need to install
libpq-dev
to run the postgresql client libraries instrumentation tests. orlibsnappy-dev
to run the prometheus exporter tests. If you encounter a build error, please check the installation instructions for the package you are trying to run tests for.
Some packages have benchmark tests. To run them, run tox -f benchmark
. Benchmark tests use pytest-benchmark
and they output a table with results to the console.
To write benchmarks, simply use the pytest benchmark fixture like the following:
def test_simple_start_span(benchmark):
def benchmark_start_as_current_span(span_name, attribute_num):
span = tracer.start_span(
span_name,
attributes={"count": attribute_num},
)
span.end()
benchmark(benchmark_start_as_current_span, "benchmarkedSpan", 42)
Make sure the test file is under the benchmarks/
folder of
the package it is benchmarking and further has a path that corresponds to the
file in the package it is testing. Make sure that the file name begins with
test_benchmark_
. (e.g. propagator/opentelemetry-propagator-aws-xray/benchmarks/trace/propagation/test_benchmark_aws_xray_propagator.py
)
Everyone is welcome to contribute code to opentelemetry-python-contrib
via GitHub
pull requests (PRs).
To create a new PR, fork the project in GitHub and clone the upstream repo:
$ git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git
$ cd opentelemetry-python-contrib
Add your fork as an origin:
$ git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-python-contrib.git
Run tests:
# make sure you have all supported versions of Python installed
$ pip install tox # only first time.
$ tox # execute in the root of the repository
Check out a new branch, make modifications and push the branch to your fork:
$ git checkout -b feature
# edit files
$ git commit
$ git push fork feature
Open a pull request against the main opentelemetry-python-contrib
repo.
- If the PR is not ready for review, please put
[WIP]
in the title, tag it aswork-in-progress
, or mark it asdraft
. - Make sure tests and lint are passing locally before requesting a review.
- Make sure CLA is signed and CI is clear.
The maintainers and approvers of this repo are not experts in every instrumentation there is here.
In fact each one of us knows enough about them to only review a few. Unfortunately it can be hard
to find enough experts in every instrumentation to quickly review every instrumentation PR. The
instrumentation experts are listed in .github/component_owners.yml
with their corresponding files
or directories that they own. The owners listed there will be notified when PRs that modify their
files are opened.
If you are not getting reviews, please contact the respective owners directly.
A PR is considered to be ready to merge when:
- It has received two approvals from Approvers / Maintainers (at different companies).
- Major feedbacks are resolved.
- It has been open for review for at least one working day. This gives people reasonable time to review.
- Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
- Urgent fix can take exception as long as it has been actively communicated.
- A changelog entry is added to the corresponding changelog for the code base, if there is any impact on behavior. e.g. doc entries are not required, but small bug entries are.
Any Approver / Maintainer can merge the PR once it is ready to merge.
As with other OpenTelemetry clients, opentelemetry-python follows the opentelemetry-specification.
It's especially valuable to read through the library guidelines.
OpenTelemetry is an evolving specification, one where the desires and use cases are clear, but the method to satisfy those uses cases are not.
As such, contributions should provide functionality and behavior that conforms to the specification, but the interface and structure is flexible.
It is preferable to have contributions follow the idioms of the language rather than conform to specific API names or argument patterns in the spec.
For a deeper discussion, see: open-telemetry/opentelemetry-specification#165
- Go to your Contrib repo directory.
git clone [email protected]:open-telemetry/opentelemetry-python-contrib.git && cd opentelemetry-python-contrib
. - Make sure you have
tox
installed.pip install tox
. - Run
tox
without any arguments to run tests for all the packages. Read more about tox.
Some tests can be slow due to pre-steps that do dependencies installs. To help with that, you can run tox a first time, and after that run the tests using previous installed dependencies in toxdir as following:
- First time run (e.g., opentelemetry-instrumentation-aiopg)
tox -e py312-test-instrumentation-aiopg
- Run tests again without pre-steps:
.tox/py312-test-instrumentation-aiopg/bin/pytest instrumentation/opentelemetry-instrumentation-aiopg
Some of the tox targets install packages from the OpenTelemetry Python Core Repository via pip. The version of the packages installed defaults to the main branch in that repository when tox is run locally. It is possible to install packages tagged with a specific git commit hash by setting an environment variable before running tox as per the following example:
CORE_REPO_SHA=c49ad57bfe35cfc69bfa863d74058ca9bec55fc3 tox
The continuous integration overrides that environment variable with as per the configuration here.
- docstrings should adhere to the Google Python Style Guide as specified with the napoleon extension extension in Sphinx.
Below is a checklist of things to be mindful of when implementing a new instrumentation or working on a specific instrumentation. It is one of our goals as a community to keep the implementation specific details of instrumentations as similar across the board as possible for ease of testing and feature parity. It is also good to abstract as much common functionality as possible.
- Follow semantic conventions
- The instrumentation should follow the semantic conventions defined here.
- To ensure consistency, we encourage contributions that align with STABLE semantic conventions if available. This approach helps us avoid potential confusion and reduces the need to support multiple outdated versions of semantic conventions. However, we are still open to considering exceptional cases where changes are well justified.
- Contributions related to outdated HTTP semantic conventions (conventions prior to becoming stable) will likely be discouraged, as they increase complexity and the potential for misconceptions.
- Contains a name that is not already claimed in Pypi. Contact a maintainer, bring the issue up in the weekly Python SIG or create a ticket in Pypi if a desired name has already been taken.
- Extends from BaseInstrumentor
- Supports auto-instrumentation
- Add an entry point (ex. )
- Run
python scripts/generate_instrumentation_bootstrap.py
after adding a new instrumentation package.
- Functionality that is common amongst other instrumentation and can be abstracted here
- Request/response hooks for http instrumentations
suppress_instrumentation
functionality- ex.
- Suppress propagation functionality
- #344 for more context
exclude_urls
functionality- ex.
url_filter
functionality- ex.
is_recording()
optimization on non-sampled spans- ex.
- Appropriate error handling
- ex.
- Isolate sync and async test
- For synchronous tests, the typical test case class is inherited from
opentelemetry.test.test_base.TestBase
. However, if you want to write asynchronous tests, the test case class should inherit also fromIsolatedAsyncioTestCase
. Adding asynchronous tests to a common test class can lead to tests passing without actually running, which can be misleading. - ex.
- For synchronous tests, the typical test case class is inherited from
- All instrumentations have the same version. If you are going to develop a new instrumentation it would probably have
X.Y.dev
version and depends onopentelemetry-instrumentation
andopentelemetry-semantic-conventions
for the same version. That means that if you want to install your instrumentation you need to install its dependencies from this repo and the core repo also from git.
OpenTelemetry is an open source community, and as such, greatly encourages contributions from anyone interested in the project. With that being said, there is a certain level of expectation from contributors even after a pull request is merged, specifically pertaining to instrumentations. The OpenTelemetry Python community expects contributors to maintain a level of support and interest in the instrumentations they contribute. This is to ensure that the instrumentation does not become stale and still functions the way the original contributor intended. Some instrumentations also pertain to libraries that the current members of the community are not so familiar with, so it is necessary to rely on the expertise of the original contributing parties.
When updating the minimum supported Python version remember to:
- Remove the version in
pyproject.toml
trove classifiers - Remove the version from
tox.ini
- Search for
sys.version_info
usage and remove code for unsupported versions - Bump
py-version
in.pylintrc
for Python version dependent checks
When adding support for a new Python release remember to:
- Add the version in
tox.ini
- Add the version in
pyproject.toml
trove classifiers - Update github workflows accordingly; lint and benchmarks use the latest supported version
- Update
.pre-commit-config.yaml
- Update tox examples in the documentation