From 877fca103a45a99932e7868862b27b5f6436797d Mon Sep 17 00:00:00 2001 From: Nathaniel Ruiz Nowell Date: Fri, 11 Dec 2020 12:55:54 -0800 Subject: [PATCH 1/6] Add docs to the contrib repo --- .readthedocs.yml | 14 ++++++++++++++ docs-requirements.txt | 0 tox.ini | 11 +++++++++++ 3 files changed, 25 insertions(+) create mode 100644 .readthedocs.yml create mode 100644 docs-requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..474f366d1b --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,14 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +version: 2 + +sphinx: + configuration: docs/conf.py + +build: + image: latest + +python: + version: 3.9 + install: + - requirements: docs-requirements.txt diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tox.ini b/tox.ini index e4958aa7f9..a43f4df236 100644 --- a/tox.ini +++ b/tox.ini @@ -140,6 +140,7 @@ envlist = lint docker-tests + docs [testenv] deps = @@ -281,6 +282,16 @@ commands = test: pytest {posargs} coverage: {toxinidir}/scripts/coverage.sh +[testenv:docs] +deps = + -c {toxinidir}/dev-requirements.txt + -r {toxinidir}/docs-requirements.txt + +changedir = docs + +commands = + sphinx-build -E -a -W -b html -T . _build/html + [testenv:lint] basepython: python3.8 recreate = False From aaf042603a1e043bb8ed1e475bd8c73df167ea91 Mon Sep 17 00:00:00 2001 From: Nathaniel Ruiz Nowell Date: Fri, 11 Dec 2020 15:51:26 -0800 Subject: [PATCH 2/6] Add docs build to Contrib repo --- .github/workflows/test.yml | 2 +- docs-requirements.txt | 35 ++++ docs/Makefile | 19 ++ docs/conf.py | 175 ++++++++++++++++++ docs/exporter/datadog/datadog.rst | 7 + docs/index.rst | 85 +++++++++ .../aiohttp_client/aiohttp_client.rst | 7 + docs/instrumentation/aiopg/aiopg.rst | 7 + docs/instrumentation/asgi/asgi.rst | 9 + docs/instrumentation/asyncpg/asyncpg.rst | 10 + docs/instrumentation/boto/boto.rst | 7 + docs/instrumentation/botocore/botocore.rst | 7 + docs/instrumentation/celery/celery.rst | 7 + docs/instrumentation/dbapi/dbapi.rst | 7 + docs/instrumentation/django/django.rst | 7 + docs/instrumentation/fastapi/fastapi.rst | 9 + docs/instrumentation/flask/flask.rst | 7 + docs/instrumentation/grpc/grpc.rst | 10 + docs/instrumentation/jinja2/jinja2.rst | 7 + docs/instrumentation/mysql/mysql.rst | 7 + docs/instrumentation/psycopg2/psycopg2.rst | 7 + .../instrumentation/pymemcache/pymemcache.rst | 7 + docs/instrumentation/pymongo/pymongo.rst | 7 + docs/instrumentation/pymysql/pymysql.rst | 7 + docs/instrumentation/pyramid/pyramid.rst | 7 + docs/instrumentation/redis/redis.rst | 7 + docs/instrumentation/requests/requests.rst | 7 + .../instrumentation/sqlalchemy/sqlalchemy.rst | 7 + docs/instrumentation/sqlite3/sqlite3.rst | 7 + docs/instrumentation/starlette/starlette.rst | 9 + .../system_metrics/system_metrics.rst | 7 + docs/instrumentation/wsgi/wsgi.rst | 7 + docs/make.bat | 35 ++++ docs/nitpick-exceptions.ini | 41 ++++ docs/sdk-extension/aws/aws.rst | 12 ++ .../aws/trace/aws_xray_ids_generator.py | 44 +++++ .../aws/trace/propagation/aws_xray_format.py | 36 ++++ tox.ini | 1 + 38 files changed, 685 insertions(+), 1 deletion(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/exporter/datadog/datadog.rst create mode 100644 docs/index.rst create mode 100644 docs/instrumentation/aiohttp_client/aiohttp_client.rst create mode 100644 docs/instrumentation/aiopg/aiopg.rst create mode 100644 docs/instrumentation/asgi/asgi.rst create mode 100644 docs/instrumentation/asyncpg/asyncpg.rst create mode 100644 docs/instrumentation/boto/boto.rst create mode 100644 docs/instrumentation/botocore/botocore.rst create mode 100644 docs/instrumentation/celery/celery.rst create mode 100644 docs/instrumentation/dbapi/dbapi.rst create mode 100644 docs/instrumentation/django/django.rst create mode 100644 docs/instrumentation/fastapi/fastapi.rst create mode 100644 docs/instrumentation/flask/flask.rst create mode 100644 docs/instrumentation/grpc/grpc.rst create mode 100644 docs/instrumentation/jinja2/jinja2.rst create mode 100644 docs/instrumentation/mysql/mysql.rst create mode 100644 docs/instrumentation/psycopg2/psycopg2.rst create mode 100644 docs/instrumentation/pymemcache/pymemcache.rst create mode 100644 docs/instrumentation/pymongo/pymongo.rst create mode 100644 docs/instrumentation/pymysql/pymysql.rst create mode 100644 docs/instrumentation/pyramid/pyramid.rst create mode 100644 docs/instrumentation/redis/redis.rst create mode 100644 docs/instrumentation/requests/requests.rst create mode 100644 docs/instrumentation/sqlalchemy/sqlalchemy.rst create mode 100644 docs/instrumentation/sqlite3/sqlite3.rst create mode 100644 docs/instrumentation/starlette/starlette.rst create mode 100644 docs/instrumentation/system_metrics/system_metrics.rst create mode 100644 docs/instrumentation/wsgi/wsgi.rst create mode 100644 docs/make.bat create mode 100644 docs/nitpick-exceptions.ini create mode 100644 docs/sdk-extension/aws/aws.rst diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c4dd9b5af4..52b103aa5b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -85,7 +85,7 @@ jobs: strategy: fail-fast: false matrix: - tox-environment: [ "docker-tests", "lint" ] + tox-environment: [ "docker-tests", "lint", "docs" ] name: ${{ matrix.tox-environment }} runs-on: ubuntu-latest steps: diff --git a/docs-requirements.txt b/docs-requirements.txt index e69de29bb2..dc1cbc7790 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -0,0 +1,35 @@ +sphinx~=2.4 +sphinx-rtd-theme~=0.4 +sphinx-autodoc-typehints~=1.10.2 + +# Need to install the api/sdk in the venv for autodoc. Modifying sys.path +# doesn't work for pkg_resources. +-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-api&subdirectory=opentelemetry-api" +-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-sdk&subdirectory=opentelemetry-sdk" + +# Required by opentelemetry-instrumentation +fastapi~=0.58.1 +psutil~=5.7.0 +pymemcache~=1.3 + +-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-instrumentation&subdirectory=opentelemetry-instrumentation" + +# Required by conf +django>=2.2 + +# Required by instrumentation packages +aiohttp~=3.0 +aiopg>=0.13.0 +asyncpg>=0.12.0 +boto~=2.0 +botocore~=1.0 +celery>=4.0 +flask~=1.0 +grpcio~=1.27 +mysql-connector-python~=8.0 +pymongo~=3.1 +PyMySQL~=0.9.3 +pyramid>=1.7 +redis>=2.6 +sqlalchemy>=1.0 +ddtrace>=0.34.0 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..51285967a7 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..86c90b7220 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,175 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys +from configparser import ConfigParser +from os import listdir +from os.path import isdir, join + +# configure django to avoid the following exception: +# django.core.exceptions.ImproperlyConfigured: Requested settings, but settings +# are not configured. You must either define the environment variable +# DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings. +from django.conf import settings + +settings.configure() + +exp = "../exporter" +exp_dirs = [ + os.path.abspath("/".join(["../exporter", f, "src"])) + for f in listdir(exp) + if isdir(join(exp, f)) +] + +instr = "../instrumentation" +instr_dirs = [ + os.path.abspath("/".join(["../instrumentation", f, "src"])) + for f in listdir(instr) + if isdir(join(instr, f)) +] + +sdk_ext = "../sdk-extension" +sdk_ext_dirs = [ + os.path.abspath("/".join(["../sdk-extension", f, "src"])) + for f in listdir(sdk_ext) + if isdir(join(sdk_ext, f)) +] + +sys.path[:0] = exp_dirs + instr_dirs + sdk_ext_dirs + +# -- Project information ----------------------------------------------------- + +project = "OpenTelemetry Python Contrib" +copyright = "OpenTelemetry Authors" # pylint: disable=redefined-builtin +author = "OpenTelemetry Authors" + + +# -- General configuration --------------------------------------------------- + +# Easy automatic cross-references for `code in backticks` +default_role = "any" + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + # API doc generation + "sphinx.ext.autodoc", + # Support for google-style docstrings + "sphinx.ext.napoleon", + # Infer types from hints instead of docstrings + "sphinx_autodoc_typehints", + # Add links to source from generated docs + "sphinx.ext.viewcode", + # Link to other sphinx docs + "sphinx.ext.intersphinx", + # Add a .nojekyll file to the generated HTML docs + # https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing + "sphinx.ext.githubpages", + # Support external links to different versions in the Github repo + "sphinx.ext.extlinks", +] + +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "opentracing": ( + "https://opentracing-python.readthedocs.io/en/latest/", + None, + ), + "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None), + "wrapt": ("https://wrapt.readthedocs.io/en/latest/", None), + "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None), +} + +# http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky +# Sphinx will warn about all references where the target cannot be found. +nitpicky = True +# Sphinx does not recognize generic type TypeVars +# Container supposedly were fixed, but does not work +# https://github.com/sphinx-doc/sphinx/pull/3744 +nitpick_ignore = [] + +cfg = ConfigParser() +cfg.read("./nitpick-exceptions.ini") +mcfg = cfg["default"] + + +def getlistcfg(strval): + return [ + val.strip() + for line in strval.split("\n") + for val in line.split(",") + if val.strip() + ] + + +if "class_references" in mcfg: + class_references = getlistcfg(mcfg["class_references"]) + for class_reference in class_references: + nitpick_ignore.append(("py:class", class_reference,)) + +if "anys" in mcfg: + anys = getlistcfg(mcfg["anys"]) + for any in anys: + nitpick_ignore.append(("any", any,)) + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, + "member-order": "bysource", +} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] + +# Support external links to specific versions of the files in the Github repo +branch = os.environ.get("READTHEDOCS_VERSION") +if branch is None or branch == "latest": + branch = "master" + +REPO = "open-telemetry/opentelemetry-python-contrib/" +scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch +scm_web = "https://github.com/" + REPO + "blob/" + branch + +# Store variables in the epilogue so they are globally available. +rst_epilog = """ +.. |SCM_WEB| replace:: {s} +.. |SCM_RAW_WEB| replace:: {sr} +.. |SCM_BRANCH| replace:: {b} +""".format( + s=scm_web, sr=scm_raw_web, b=branch +) + +# used to have links to repo files +extlinks = { + "scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"), + "scm_web": (scm_web + "/%s", "scm_web"), +} diff --git a/docs/exporter/datadog/datadog.rst b/docs/exporter/datadog/datadog.rst new file mode 100644 index 0000000000..3b43c2bdf7 --- /dev/null +++ b/docs/exporter/datadog/datadog.rst @@ -0,0 +1,7 @@ +OpenTelemetry Datadog Exporter +============================== + +.. automodule:: opentelemetry.exporter.datadog + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..ccf6d13dd1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,85 @@ +OpenTelemetry-Python-Contrib +============================ + +Complimentary instrumentation and vendor-specific packages for use with the +Python `OpenTelemetry `_ client. + +.. image:: https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python + :target: https://gitter.im/open-telemetry/opentelemetry-python + :alt: Gitter Chat + + +**Please note** that this library is currently in _beta_, and shouldn't +generally be used in production environments. + +Installation +------------ + +There are several complimentary packages available on PyPI which can be +installed separately via pip: + +.. code-block:: sh + + pip install opentelemetry-exporter-{exporter} + pip install opentelemetry-instrumentation-{instrumentation} + pip install opentelemetry-sdk-extension-{sdkextension} + +A complete list of packages can be found at the +`Contrib repo instrumentation `_ +and `Contrib repo exporter `_ directories. + +Extensions +---------- + +Visit `OpenTelemetry Registry `_ to +find a lit of related projects like exporters, instrumentation libraries, tracer +implementations, etc. + +Installing Cutting Edge Packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While the project is pre-1.0, there may be significant functionality that +has not yet been released to PyPI. In that situation, you may want to +install the packages directly from the repo. This can be done by cloning the +repository and doing an `editable +install `_: + +.. code-block:: sh + + git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git + cd opentelemetry-python-contrib + pip install -e ./instrumentation/opentelemetry-instrumentation-flask + pip install -e ./instrumentation/opentelemetry-instrumentation-botocore + pip install -e ./sdk-extension/opentelemetry-sdk-extension-aws + + +.. toctree:: + :maxdepth: 2 + :caption: OpenTelemetry Exporters + :name: exporters + :glob: + + exporter/** + +.. toctree:: + :maxdepth: 2 + :caption: OpenTelemetry Instrumentations + :name: Instrumentations + :glob: + + instrumentation/** + +.. toctree:: + :maxdepth: 2 + :caption: OpenTelemetry SDK Extensions + :name: SDK Extensions + :glob: + + sdk-extension/** + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/instrumentation/aiohttp_client/aiohttp_client.rst b/docs/instrumentation/aiohttp_client/aiohttp_client.rst new file mode 100644 index 0000000000..f8549f07fa --- /dev/null +++ b/docs/instrumentation/aiohttp_client/aiohttp_client.rst @@ -0,0 +1,7 @@ +OpenTelemetry aiohttp client Instrumentation +============================================ + +.. automodule:: opentelemetry.instrumentation.aiohttp_client + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/aiopg/aiopg.rst b/docs/instrumentation/aiopg/aiopg.rst new file mode 100644 index 0000000000..9da450c4e7 --- /dev/null +++ b/docs/instrumentation/aiopg/aiopg.rst @@ -0,0 +1,7 @@ +OpenTelemetry aiopg Instrumentation +=================================== + +.. automodule:: opentelemetry.instrumentation.aiopg + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/asgi/asgi.rst b/docs/instrumentation/asgi/asgi.rst new file mode 100644 index 0000000000..b988e4de43 --- /dev/null +++ b/docs/instrumentation/asgi/asgi.rst @@ -0,0 +1,9 @@ +.. include:: ../../../instrumentation/opentelemetry-instrumentation-asgi/README.rst + +API +--- + +.. automodule:: opentelemetry.instrumentation.asgi + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/asyncpg/asyncpg.rst b/docs/instrumentation/asyncpg/asyncpg.rst new file mode 100644 index 0000000000..745e83f51d --- /dev/null +++ b/docs/instrumentation/asyncpg/asyncpg.rst @@ -0,0 +1,10 @@ +Opentelemetry asyncpg Instrumentation +===================================== + +Module contents +--------------- + +.. automodule:: opentelemetry.instrumentation.asyncpg + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/boto/boto.rst b/docs/instrumentation/boto/boto.rst new file mode 100644 index 0000000000..c438c2466c --- /dev/null +++ b/docs/instrumentation/boto/boto.rst @@ -0,0 +1,7 @@ +OpenTelemetry Boto Instrumentation +================================== + +.. automodule:: opentelemetry.instrumentation.boto + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/botocore/botocore.rst b/docs/instrumentation/botocore/botocore.rst new file mode 100644 index 0000000000..eb8ea6bcf7 --- /dev/null +++ b/docs/instrumentation/botocore/botocore.rst @@ -0,0 +1,7 @@ +OpenTelemetry Botocore Instrumentation +====================================== + +.. automodule:: opentelemetry.instrumentation.botocore + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/celery/celery.rst b/docs/instrumentation/celery/celery.rst new file mode 100644 index 0000000000..c85f3adb59 --- /dev/null +++ b/docs/instrumentation/celery/celery.rst @@ -0,0 +1,7 @@ +OpenTelemetry Celery Instrumentation +==================================== + +.. automodule:: opentelemetry.instrumentation.celery + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/dbapi/dbapi.rst b/docs/instrumentation/dbapi/dbapi.rst new file mode 100644 index 0000000000..a20be63097 --- /dev/null +++ b/docs/instrumentation/dbapi/dbapi.rst @@ -0,0 +1,7 @@ +OpenTelemetry Database API Instrumentation +========================================== + +.. automodule:: opentelemetry.instrumentation.dbapi + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/django/django.rst b/docs/instrumentation/django/django.rst new file mode 100644 index 0000000000..8076730843 --- /dev/null +++ b/docs/instrumentation/django/django.rst @@ -0,0 +1,7 @@ +OpenTelemetry Django Instrumentation +==================================== + +.. automodule:: opentelemetry.instrumentation.django + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/fastapi/fastapi.rst b/docs/instrumentation/fastapi/fastapi.rst new file mode 100644 index 0000000000..09eb8a828b --- /dev/null +++ b/docs/instrumentation/fastapi/fastapi.rst @@ -0,0 +1,9 @@ +.. include:: ../../../instrumentation/opentelemetry-instrumentation-fastapi/README.rst + +API +--- + +.. automodule:: opentelemetry.instrumentation.fastapi + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/instrumentation/flask/flask.rst b/docs/instrumentation/flask/flask.rst new file mode 100644 index 0000000000..ac8932acd4 --- /dev/null +++ b/docs/instrumentation/flask/flask.rst @@ -0,0 +1,7 @@ +OpenTelemetry Flask Instrumentation +=================================== + +.. automodule:: opentelemetry.instrumentation.flask + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/grpc/grpc.rst b/docs/instrumentation/grpc/grpc.rst new file mode 100644 index 0000000000..243f696143 --- /dev/null +++ b/docs/instrumentation/grpc/grpc.rst @@ -0,0 +1,10 @@ +OpenTelemetry gRPC Instrumentation +================================== + +Module contents +--------------- + +.. automodule:: opentelemetry.instrumentation.grpc + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/jinja2/jinja2.rst b/docs/instrumentation/jinja2/jinja2.rst new file mode 100644 index 0000000000..5c7143724c --- /dev/null +++ b/docs/instrumentation/jinja2/jinja2.rst @@ -0,0 +1,7 @@ +OpenTelemetry Jinja2 Instrumentation +==================================== + +.. automodule:: opentelemetry.instrumentation.jinja2 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/mysql/mysql.rst b/docs/instrumentation/mysql/mysql.rst new file mode 100644 index 0000000000..3a4a41542a --- /dev/null +++ b/docs/instrumentation/mysql/mysql.rst @@ -0,0 +1,7 @@ +OpenTelemetry MySQL Instrumentation +=================================== + +.. automodule:: opentelemetry.instrumentation.mysql + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/psycopg2/psycopg2.rst b/docs/instrumentation/psycopg2/psycopg2.rst new file mode 100644 index 0000000000..69be31b2d1 --- /dev/null +++ b/docs/instrumentation/psycopg2/psycopg2.rst @@ -0,0 +1,7 @@ +OpenTelemetry Psycopg Instrumentation +===================================== + +.. automodule:: opentelemetry.instrumentation.psycopg2 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/pymemcache/pymemcache.rst b/docs/instrumentation/pymemcache/pymemcache.rst new file mode 100644 index 0000000000..2a77b829d9 --- /dev/null +++ b/docs/instrumentation/pymemcache/pymemcache.rst @@ -0,0 +1,7 @@ +OpenTelemetry pymemcache Instrumentation +======================================== + +.. automodule:: opentelemetry.instrumentation.pymemcache + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/pymongo/pymongo.rst b/docs/instrumentation/pymongo/pymongo.rst new file mode 100644 index 0000000000..4eb68be27b --- /dev/null +++ b/docs/instrumentation/pymongo/pymongo.rst @@ -0,0 +1,7 @@ +OpenTelemetry pymongo Instrumentation +===================================== + +.. automodule:: opentelemetry.instrumentation.pymongo + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/pymysql/pymysql.rst b/docs/instrumentation/pymysql/pymysql.rst new file mode 100644 index 0000000000..26482292fe --- /dev/null +++ b/docs/instrumentation/pymysql/pymysql.rst @@ -0,0 +1,7 @@ +OpenTelemetry PyMySQL Instrumentation +===================================== + +.. automodule:: opentelemetry.instrumentation.pymysql + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/pyramid/pyramid.rst b/docs/instrumentation/pyramid/pyramid.rst new file mode 100644 index 0000000000..56abd2800b --- /dev/null +++ b/docs/instrumentation/pyramid/pyramid.rst @@ -0,0 +1,7 @@ +OpenTelemetry Pyramid Instrumentation +===================================== + +.. automodule:: opentelemetry.instrumentation.pyramid + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/redis/redis.rst b/docs/instrumentation/redis/redis.rst new file mode 100644 index 0000000000..4e21bce24b --- /dev/null +++ b/docs/instrumentation/redis/redis.rst @@ -0,0 +1,7 @@ +OpenTelemetry Redis Instrumentation +=================================== + +.. automodule:: opentelemetry.instrumentation.redis + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/requests/requests.rst b/docs/instrumentation/requests/requests.rst new file mode 100644 index 0000000000..7a0665cd99 --- /dev/null +++ b/docs/instrumentation/requests/requests.rst @@ -0,0 +1,7 @@ +OpenTelemetry requests Instrumentation +====================================== + +.. automodule:: opentelemetry.instrumentation.requests + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/sqlalchemy/sqlalchemy.rst b/docs/instrumentation/sqlalchemy/sqlalchemy.rst new file mode 100644 index 0000000000..1a1895ea6b --- /dev/null +++ b/docs/instrumentation/sqlalchemy/sqlalchemy.rst @@ -0,0 +1,7 @@ +OpenTelemetry SQLAlchemy Instrumentation +======================================== + +.. automodule:: opentelemetry.instrumentation.sqlalchemy + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/sqlite3/sqlite3.rst b/docs/instrumentation/sqlite3/sqlite3.rst new file mode 100644 index 0000000000..36b541ccd1 --- /dev/null +++ b/docs/instrumentation/sqlite3/sqlite3.rst @@ -0,0 +1,7 @@ +OpenTelemetry SQLite3 Instrumentation +===================================== + +.. automodule:: opentelemetry.instrumentation.sqlite3 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/starlette/starlette.rst b/docs/instrumentation/starlette/starlette.rst new file mode 100644 index 0000000000..0efa8cce83 --- /dev/null +++ b/docs/instrumentation/starlette/starlette.rst @@ -0,0 +1,9 @@ +.. include:: ../../../instrumentation/opentelemetry-instrumentation-starlette/README.rst + +API +--- + +.. automodule:: opentelemetry.instrumentation.starlette + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/instrumentation/system_metrics/system_metrics.rst b/docs/instrumentation/system_metrics/system_metrics.rst new file mode 100644 index 0000000000..96b39d9267 --- /dev/null +++ b/docs/instrumentation/system_metrics/system_metrics.rst @@ -0,0 +1,7 @@ +OpenTelemetry System Metrics Instrumentation +============================================ + +.. automodule:: opentelemetry.instrumentation.system_metrics + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/instrumentation/wsgi/wsgi.rst b/docs/instrumentation/wsgi/wsgi.rst new file mode 100644 index 0000000000..39ad5ffd58 --- /dev/null +++ b/docs/instrumentation/wsgi/wsgi.rst @@ -0,0 +1,7 @@ +OpenTelemetry WSGI Instrumentation +================================== + +.. automodule:: opentelemetry.instrumentation.wsgi + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..27f573b87a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/nitpick-exceptions.ini b/docs/nitpick-exceptions.ini new file mode 100644 index 0000000000..4289001a2b --- /dev/null +++ b/docs/nitpick-exceptions.ini @@ -0,0 +1,41 @@ +[default] +class_references= + MetricT + ValueT + ; Even if wrapt is added to intersphinx_mapping, sphinx keeps failing + ; with "class reference target not found: ObjectProxy". + ObjectProxy + ; TODO: Understand why sphinx is not able to find this local class + opentelemetry.trace.propagation.textmap.TextMapPropagator + opentelemetry.trace.propagation.textmap.DictGetter + ; API + opentelemetry.context.context.Context + opentelemetry.trace.ids_generator.IdsGenerator + opentelemetry.trace.propagation.textmap.Getter + opentelemetry.trace.Span + opentelemetry.trace.Tracer + opentelemetry.trace.TracerProvider + TextMapPropagatorT + ; SDK + opentelemetry.sdk.trace.export.SpanExporter + opentelemetry.sdk.trace.export.SpanExportResult + opentelemetry.sdk.trace.SpanProcessor + opentelemetry.sdk.trace.Span + opentelemetry.sdk.trace.Tracer + ; Instrumentation + opentelemetry.instrumentation.metric.MetricMixin + opentelemetry.instrumentation.instrumentor.BaseInstrumentor + +anys= + ; API + opentelemetry.trace.propagation.textmap.TextMapPropagator.extract + opentelemetry.trace.propagation.textmap.TextMapPropagator.fields + opentelemetry.trace.propagation.textmap.TextMapPropagator.inject + opentelemetry.trace.Span + TraceId + TraceIdRatioBased + ; SDK + SpanProcessor + TracerProvider + ; Instrumentation + BaseInstrumentor diff --git a/docs/sdk-extension/aws/aws.rst b/docs/sdk-extension/aws/aws.rst new file mode 100644 index 0000000000..1306e45665 --- /dev/null +++ b/docs/sdk-extension/aws/aws.rst @@ -0,0 +1,12 @@ +OpenTelemetry Python - AWS SDK Extension +======================================== + +.. automodule:: opentelemetry.sdk.extension.aws.trace.aws_xray_ids_generator + :members: + :undoc-members: + :show-inheritance: + +.. automodule:: opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format + :members: + :undoc-members: + :show-inheritance: diff --git a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py b/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py index aa7d51bc7d..9f8418b10b 100644 --- a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py +++ b/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py @@ -12,6 +12,50 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Installation +------------ + +:: + + pip install opentelemetry-sdk-extension-aws + +AWS X-Ray IDs Generator +----------------------- + +The **AWS X-Ray IDs Generator** provides a custom IDs Generator to make +traces generated using the OpenTelemetry SDKs `TracerProvider` compatible +with the AWS X-Ray backend service `trace ID format`_. + +Usage +----- + +Configure the OTel SDK TracerProvider with the provided custom IDs Generator to +make spans compatible with the AWS X-Ray backend tracing service. + +Install the OpenTelemetry SDK package. + +:: + + pip install opentelemetry-sdk + +Next, use the provided `AwsXRayIdsGenerator` to initialize the `TracerProvider`. + +.. code-block:: python + + import opentelemetry.trace as trace + from opentelemetry.sdk.extension.aws.trace import AwsXRayIdsGenerator + from opentelemetry.sdk.trace import TracerProvider + + trace.set_tracer_provider( + TracerProvider(ids_generator=AwsXRayIdsGenerator()) + ) + +API +--- +.. _trace ID format: https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids +""" + import random import time diff --git a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py b/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py index 54b98e0ba5..63ccb00206 100644 --- a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py +++ b/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py @@ -12,6 +12,42 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +AWS X-Ray Propagator +-------------------- + +The **AWS X-Ray Propagator** provides a propagator that when used, adds a `trace +header`_ to outgoing traces that is compatible with the AWS X-Ray backend service. +This allows the trace context to be propagated when a trace span multiple AWS +services. + +Usage +----- + +Use the provided AWS X-Ray Propagator to inject the necessary context into +traces sent to external systems. + +This can be done by either setting this environment variable: + +:: + + export OTEL_PROPAGATORS = aws_xray + + +Or by setting this propagator in your instrumented application: + +.. code-block:: python + + from opentelemetry import propagators + from opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format import AwsXRayFormat + + propagators.set_global_textmap(AwsXRayFormat()) + +API +--- +.. _trace header: https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader +""" + import logging import typing diff --git a/tox.ini b/tox.ini index a43f4df236..87462e4c87 100644 --- a/tox.ini +++ b/tox.ini @@ -286,6 +286,7 @@ commands = deps = -c {toxinidir}/dev-requirements.txt -r {toxinidir}/docs-requirements.txt + pytest changedir = docs From 7ca3129d95f1e41f1596dfb48c4ea08db38cfdd3 Mon Sep 17 00:00:00 2001 From: "(Eliseo) Nathaniel Ruiz Nowell" Date: Thu, 17 Dec 2020 10:06:30 -0800 Subject: [PATCH 3/6] Using intersphinx mapping to reference OTel Python Core docs Co-authored-by: Aaron Abbott --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 86c90b7220..e0dbffaeb8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -89,6 +89,10 @@ "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None), "wrapt": ("https://wrapt.readthedocs.io/en/latest/", None), "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None), + "opentelemetry": ( + "https://opentelemetry-python.readthedocs.io/en/latest/", + None, + ), } # http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky From 56c626a285378bd4c3534f086352239f5f609c25 Mon Sep 17 00:00:00 2001 From: Nathaniel Ruiz Nowell Date: Thu, 17 Dec 2020 10:31:30 -0800 Subject: [PATCH 4/6] Update nitpick exceptions to only bare necessities --- docs/nitpick-exceptions.ini | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/docs/nitpick-exceptions.ini b/docs/nitpick-exceptions.ini index 4289001a2b..3143b9cd75 100644 --- a/docs/nitpick-exceptions.ini +++ b/docs/nitpick-exceptions.ini @@ -1,41 +1,30 @@ [default] class_references= - MetricT - ValueT - ; Even if wrapt is added to intersphinx_mapping, sphinx keeps failing - ; with "class reference target not found: ObjectProxy". - ObjectProxy ; TODO: Understand why sphinx is not able to find this local class opentelemetry.trace.propagation.textmap.TextMapPropagator + ; - AwsXRayFormat opentelemetry.trace.propagation.textmap.DictGetter + ; - instrumentation.asgi.CarrierGetter ; API - opentelemetry.context.context.Context - opentelemetry.trace.ids_generator.IdsGenerator opentelemetry.trace.propagation.textmap.Getter - opentelemetry.trace.Span - opentelemetry.trace.Tracer - opentelemetry.trace.TracerProvider + ; - DatadogFormat + ; - AWSXRayFormat TextMapPropagatorT - ; SDK - opentelemetry.sdk.trace.export.SpanExporter - opentelemetry.sdk.trace.export.SpanExportResult - opentelemetry.sdk.trace.SpanProcessor - opentelemetry.sdk.trace.Span - opentelemetry.sdk.trace.Tracer - ; Instrumentation - opentelemetry.instrumentation.metric.MetricMixin - opentelemetry.instrumentation.instrumentor.BaseInstrumentor + ; - AwsXRayFormat.extract anys= ; API - opentelemetry.trace.propagation.textmap.TextMapPropagator.extract opentelemetry.trace.propagation.textmap.TextMapPropagator.fields - opentelemetry.trace.propagation.textmap.TextMapPropagator.inject - opentelemetry.trace.Span + ; - AWSXRayFormat TraceId + ; - AwsXRayIdsGenerator TraceIdRatioBased + ; - AwsXRayIdsGenerator ; SDK SpanProcessor + ; - DatadogExportSpanProcessor TracerProvider + ; - AwsXRayIdsGenerator ; Instrumentation BaseInstrumentor + ; - instrumentation.* From a84140771bba0a17eb85feb9ebe38016a014007c Mon Sep 17 00:00:00 2001 From: Nathaniel Ruiz Nowell Date: Sun, 10 Jan 2021 21:20:25 -0800 Subject: [PATCH 5/6] Add benchmarks file to toc tree --- docs/index.rst | 8 ++++++++ docs/performance/benchmarks.rst | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index ccf6d13dd1..683d1c6397 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -69,6 +69,14 @@ install instrumentation/** +.. toctree:: + :maxdepth: 2 + :caption: OpenTelemetry Performance + :name: Performance + :glob: + + performance/** + .. toctree:: :maxdepth: 2 :caption: OpenTelemetry SDK Extensions diff --git a/docs/performance/benchmarks.rst b/docs/performance/benchmarks.rst index 428d5acbbb..99859a27d8 100644 --- a/docs/performance/benchmarks.rst +++ b/docs/performance/benchmarks.rst @@ -1,4 +1,4 @@ Performance Tests - Benchmarks ============================== -Click `here _` to view the latest performance benchmarks for packages in this repo. +Click `here `_ to view the latest performance benchmarks for packages in this repo. From 5c2c1325bfae1e470b4869236784f998bb62f1c1 Mon Sep 17 00:00:00 2001 From: alrex Date: Tue, 26 Jan 2021 08:46:56 -0800 Subject: [PATCH 6/6] Update docs/instrumentation/asyncpg/asyncpg.rst --- docs/instrumentation/asyncpg/asyncpg.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/instrumentation/asyncpg/asyncpg.rst b/docs/instrumentation/asyncpg/asyncpg.rst index 745e83f51d..d4ee9b4abb 100644 --- a/docs/instrumentation/asyncpg/asyncpg.rst +++ b/docs/instrumentation/asyncpg/asyncpg.rst @@ -1,4 +1,4 @@ -Opentelemetry asyncpg Instrumentation +OpenTelemetry asyncpg Instrumentation ===================================== Module contents