mirror of
https://github.com/open-telemetry/opentelemetry-python-contrib.git
synced 2025-07-28 20:52:57 +08:00
updating readme, adding contributing doc
This commit is contained in:
Alex Boten
168
CONTRIBUTING.md
Normal file
168
CONTRIBUTING.md
Normal file
@ -0,0 +1,168 @@
|
||||
# Contributing to opentelemetry-python-contrib
|
||||
|
||||
The Python special interest group (SIG) meets regularly. See the OpenTelemetry
|
||||
[community](https://github.com/open-telemetry/community#python-sdk) repo for
|
||||
information on this and other language SIGs.
|
||||
|
||||
See the [public meeting notes](https://docs.google.com/document/d/1CIMGoIOZ-c3-igzbd6_Pnxx1SjAkjwqoYSUWxPY8XIs/edit)
|
||||
for a summary description of past meetings. To request edit access, join the
|
||||
meeting or get in touch on [Gitter](https://gitter.im/open-telemetry/opentelemetry-python).
|
||||
|
||||
See to the [community membership document](https://github.com/open-telemetry/community/blob/master/community-membership.md)
|
||||
on how to become a [**Member**](https://github.com/open-telemetry/community/blob/master/community-membership.md#member),
|
||||
[**Approver**](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)
|
||||
and [**Maintainer**](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).
|
||||
|
||||
## Find a Buddy and get Started Quickly!
|
||||
|
||||
If you are looking for someone to help you find a starting point and be a resource for your first contribution, join our
|
||||
Gitter and find a buddy!
|
||||
|
||||
1. Join [Gitter.im](https://gitter.im) and join our [chat room](https://gitter.im/open-telemetry/opentelemetry-python).
|
||||
2. 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.
|
||||
|
||||
## Development
|
||||
|
||||
To quickly get up and running, you can use the `scripts/eachdist.py` tool that
|
||||
ships with this project. First create a virtualenv and activate it.
|
||||
Then run `python scripts/eachdist.py develop` to install all required packages
|
||||
as well as the project's packages themselves (in `--editable` mode).
|
||||
You can then run `scripts/eachdist.py test` to test everything or
|
||||
`scripts/eachdist.py lint` to lint everything (fixing anything that is auto-fixable).
|
||||
|
||||
Additionally, this project uses [`tox`](https://tox.readthedocs.io) to automate some aspects
|
||||
of development, including testing against multiple Python versions.
|
||||
|
||||
You can run:
|
||||
|
||||
- `tox` to run all existing tox commands, including unit tests for all packages
|
||||
under multiple Python versions
|
||||
- `tox -e py37-test-flask` to e.g. run the Flask tests under a specific
|
||||
Python version
|
||||
- `tox -e lint` to run lint checks on all code
|
||||
|
||||
See
|
||||
[`tox.ini`](https://github.com/open-telemetry/opentelemetry-python/blob/master/tox.ini)
|
||||
for more detail on available tox commands.
|
||||
|
||||
## Pull Requests
|
||||
|
||||
### How to Send Pull Requests
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git
|
||||
```
|
||||
|
||||
Add your fork as an origin:
|
||||
|
||||
```sh
|
||||
$ git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-python-contrib.git
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```sh
|
||||
# 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:
|
||||
|
||||
```sh
|
||||
$ git checkout -b feature
|
||||
# edit files
|
||||
$ git commit
|
||||
$ git push fork feature
|
||||
```
|
||||
|
||||
Open a pull request against the main `opentelemetry-python-contrib` repo.
|
||||
|
||||
### How to Receive Comments
|
||||
|
||||
* If the PR is not ready for review, please put `[WIP]` in the title, tag it
|
||||
as `work-in-progress`, or mark it as [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
|
||||
* Make sure CLA is signed and CI is clear.
|
||||
|
||||
### How to Get PRs Merged
|
||||
|
||||
A PR is considered to be **ready to merge** when:
|
||||
* It has received two approvals from [Approvers](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)
|
||||
/ [Maintainers](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)
|
||||
(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.
|
||||
|
||||
Any Approver / Maintainer can merge the PR once it is **ready to merge**.
|
||||
|
||||
## Design Choices
|
||||
|
||||
As with other OpenTelemetry clients, opentelemetry-python follows the
|
||||
[opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification).
|
||||
|
||||
It's especially valuable to read through the [library guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md).
|
||||
|
||||
### Focus on Capabilities, Not Structure Compliance
|
||||
|
||||
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: https://github.com/open-telemetry/opentelemetry-specification/issues/165
|
||||
|
||||
## Style Guide
|
||||
|
||||
* docstrings should adhere to the [Google Python Style
|
||||
Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
|
||||
as specified with the [napolean
|
||||
extension](http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#google-vs-numpy)
|
||||
extension in [Sphinx](http://www.sphinx-doc.org/en/master/index.html).
|
||||
|
||||
## Porting reference/ddtrace/contrib to instrumentation
|
||||
|
||||
The steps below describe suggested steps to port integrations from the reference directory containing the originally donated code to OpenTelemetry.
|
||||
|
||||
1. Move the code into the instrumentation directory
|
||||
|
||||
```
|
||||
mkdir -p instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2
|
||||
git mv reference/ddtrace/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2
|
||||
```
|
||||
|
||||
2. Move the tests
|
||||
|
||||
```
|
||||
git mv reference/tests/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/tests
|
||||
```
|
||||
|
||||
3. Add `README.rst`, `setup.cfg` and `setup.py` files and update them accordingly
|
||||
|
||||
```bash
|
||||
cp _template/* instrumentation/opentelemetry-instrumentation-jinja2/
|
||||
```
|
||||
|
||||
4. Add `version.py` file and update it accordingly
|
||||
|
||||
```bash
|
||||
mv instrumentation/opentelemetry-instrumentation-jinja2/version.py instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2/version.py
|
||||
```
|
||||
|
||||
5. Fix relative import paths to using ddtrace package instead of using relative paths
|
||||
6. Update the code and tests to use the OpenTelemetry API
|
||||
64
README.md
64
README.md
@ -1,34 +1,56 @@
|
||||
# opentelemetry-auto-instr-python
|
||||
The auto-instrumentation for Python (per [OTEP 0001](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)) instruments each library in a separately installable package to ensure users only need to install the libraries that make sense for their use-case. This repository contains the code initially [donated by DataDog](https://www.datadoghq.com/blog/opentelemetry-instrumentation/) in the `reference` folder. All instrumentation that has been ported lives in the `instrumentation` directory.
|
||||
# opentelemetry-python-contrib
|
||||
[](https://gitter.im/open-telemetry/opentelemetry-python)[](https://travis-ci.org/open-telemetry/opentelemetry-python-contrib)
|
||||
|
||||
# porting ddtrace/contrib to instrumentation
|
||||
The Python auto-instrumentation libraries for [OpenTelemetry](https://opentelemetry.io/) (per [OTEP 0001](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md))
|
||||
|
||||
The steps below describe the process to port integrations from the reference directory containing the originally donated code to OpenTelemetry.
|
||||
### Installation
|
||||
|
||||
1. Move the code into the instrumentation directory
|
||||
This repository includes installable packages for each instrumented library. Libraries that produce telemetry data should only depend on `opentelemetry-api`,
|
||||
and defer the choice of the SDK to the application developer. Applications may
|
||||
depend on `opentelemetry-sdk` or another package that implements the API.
|
||||
|
||||
```
|
||||
mkdir -p instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2
|
||||
git mv reference/ddtrace/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2
|
||||
**Please note** that these libraries are currently in _beta_, and shouldn't
|
||||
generally be used in production environments.
|
||||
|
||||
The
|
||||
[`instrumentation/`](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/instrumentation)
|
||||
directory includes OpenTelemetry instrumentation packages, which can be installed
|
||||
separately as:
|
||||
|
||||
```sh
|
||||
pip install opentelemetry-instrumentation-{integration}
|
||||
```
|
||||
|
||||
2. Move the tests
|
||||
To install the development versions of these packages instead, clone or fork
|
||||
this repo and do an [editable
|
||||
install](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs):
|
||||
|
||||
```
|
||||
git mv reference/tests/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/tests
|
||||
```sh
|
||||
pip install -e ./ext/opentelemetry-ext-{integration}
|
||||
```
|
||||
|
||||
3. Add `README.rst`, `setup.cfg` and `setup.py` files and update them accordingly
|
||||
## Contributing
|
||||
|
||||
```bash
|
||||
cp _template/* instrumentation/opentelemetry-instrumentation-jinja2/
|
||||
```
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
4. Add `version.py` file and update it accordingly
|
||||
We meet weekly on Thursday, and the time of the meeting alternates between 9AM PT and 4PM PT. The meeting is subject to change depending on contributors' availability. Check the [OpenTelemetry community calendar](https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com) for specific dates.
|
||||
|
||||
```bash
|
||||
mv instrumentation/opentelemetry-instrumentation-jinja2/version.py instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2/version.py
|
||||
```
|
||||
Meetings take place via [Zoom video conference](https://zoom.us/j/6729396170).
|
||||
|
||||
Meeting notes are available as a public [Google doc](https://docs.google.com/document/d/1CIMGoIOZ-c3-igzbd6_Pnxx1SjAkjwqoYSUWxPY8XIs/edit). For edit access, get in touch on [Gitter](https://gitter.im/open-telemetry/opentelemetry-python).
|
||||
|
||||
Approvers ([@open-telemetry/python-approvers](https://github.com/orgs/open-telemetry/teams/opentelemetry-python-contrib-approvers)):
|
||||
|
||||
- [Chris Kleinknecht](https://github.com/c24t), Google
|
||||
- [Hector Hernandez](https://github.com/hectorhdzg), Microsoft
|
||||
- [Reiley Yang](https://github.com/reyang), Microsoft
|
||||
|
||||
*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).*
|
||||
|
||||
Maintainers ([@open-telemetry/python-maintainers](https://github.com/orgs/open-telemetry/teams/opentelemetry-python-contrib-maintainers)):
|
||||
|
||||
- [Alex Boten](https://github.com/codeboten), Lightstep
|
||||
- [Carlos Alberto Cortez](https://github.com/carlosalberto), Lightstep
|
||||
|
||||
*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).*
|
||||
|
||||
5. Fix relative import paths to using ddtrace package instead of using relative paths
|
||||
6. Update the code and tests to use the OpenTelemetry API
|
||||
|
||||
Reference in New Issue
Block a user