adding instructions to port instrumentation (#26)

Adding some instructions on how to port from the reference directory. More updates will be needed as tests are added. 

Co-Authored-By: Hector Hernandez <39923391+hectorhdzg@users.noreply.github.com>

Co-authored-by: Mauricio Vásquez <mauricio@kinvolk.io>
Co-authored-by: Hector Hernandez <39923391+hectorhdzg@users.noreply.github.com>
This commit is contained in:
alrex
2020-04-09 11:16:33 -07:00
committed by GitHub
parent fc4620c5b8
commit 1bc2440747
5 changed files with 173 additions and 1 deletions

View File

@ -1,2 +1,34 @@
# opentelemetry-auto-instr-python
Auto-Instrumentation for Python (per OTEP 0001)
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.
# porting ddtrace/contrib to instrumentation
The steps below describe the process 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

23
_template/README.rst Normal file
View File

@ -0,0 +1,23 @@
OpenTelemetry <REPLACE ME> Instrumentation
===========================
|pypi|
.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-<REPLACE ME>.svg
:target: https://pypi.org/project/opentelemetry-instrumentation-<REPLACE ME>/
This library allows tracing requests made by the <REPLACE ME> library.
Installation
------------
::
pip install opentelemetry-instrumentation-<REPLACE ME>
References
----------
* `OpenTelemetry <REPLACE ME>/ Tracing <https://opentelemetry-python.readthedocs.io/en/latest/instrumentation/<REPLACE ME>/<REPLACE ME>.html>`_
* `OpenTelemetry Project <https://opentelemetry.io/>`_

60
_template/setup.cfg Normal file
View File

@ -0,0 +1,60 @@
# Copyright The OpenTelemetry Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
[metadata]
# opentelemetry-instrumentation plus the name of the library being instrument e.g
# name = opentelemetry-instrumentation-sqlalchemy
name = "<REPLACE ME>"
# a description of the instrumentation e.g
# description = SQLAlchemy tracing for OpenTelemetry
description = "<REPLACE ME>"
long_description = file: README.rst
long_description_content_type = text/x-rst
author = OpenTelemetry Authors
author_email = cncf-opentelemetry-contributors@lists.cncf.io
# url of the instrumentation e.g
# url = https://github.com/open-telemetry/opentelemetry-python-contrib/instrumentation/opentelemetry-instrumentation-sqlalchemy
url = "<REPLACE ME>"
platforms = any
license = Apache-2.0
classifiers =
Development Status :: 4 - Beta
Intended Audience :: Developers
License :: OSI Approved :: Apache Software License
Programming Language :: Python
Programming Language :: Python :: 3
Programming Language :: Python :: 3.4
Programming Language :: Python :: 3.5
Programming Language :: Python :: 3.6
Programming Language :: Python :: 3.7
Programming Language :: Python :: 3.8
[options]
python_requires = >=3.4
package_dir=
=src
packages=find_namespace:
install_requires =
# add any package dependencies here
"<REPLACE ME>"
[options.extras_require]
test =
# add any test dependencies here
"<REPLACE ME>"
[options.packages.find]
where = src

42
_template/setup.py Normal file
View File

@ -0,0 +1,42 @@
# Copyright The OpenTelemetry Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import os
import setuptools
BASE_DIR = os.path.dirname(__file__)
VERSION_FILENAME = os.path.join(
# REPLACE ME: the path to the version file e.g
# BASE_DIR, "src", "opentelemetry", "instrumentation", "sqlalchemy", "version.py"
BASE_DIR,
"src",
"opentelemetry",
"instrumentation",
"<REPLACE ME>",
"version.py",
)
PACKAGE_INFO = {}
with open(VERSION_FILENAME) as f:
exec(f.read(), PACKAGE_INFO)
setuptools.setup(
version=PACKAGE_INFO["__version__"],
entry_points={
"opentelemetry_instrumentor": [
# REPLACE ME: the entrypoint for the instrumentor e.g
# "sqlalchemy = opentelemetry.instrumentation.sqlalchemy:SQLAlchemyInstrumentor"
"<REPLACE ME> = opentelemetry.instrumentation.<REPLACE>"
]
},
)

15
_template/version.py Normal file
View File

@ -0,0 +1,15 @@
# Copyright The OpenTelemetry Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
__version__ = "<REPLACE ME>"