Skip to content

Commit

Permalink
Consolidate instrumentation documentation in docstrings (#754)
Browse files Browse the repository at this point in the history
  • Loading branch information
lzchen authored Oct 21, 2021
1 parent 3049b4b commit ae7a415
Show file tree
Hide file tree
Showing 33 changed files with 602 additions and 363 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased](https://github.com/open-telemetry/opentelemetry-python/compare/v1.6.2-0.25b2...HEAD)

### Fixed

- `opentelemetry-instrumentation-asgi` now explicitly depends on asgiref as it uses the package instead of instrumenting it.
Expand All @@ -19,6 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
([#753](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/753))
- `opentelemetry-instrumentation-pika` Add `_decorate_basic_consume` to ensure post instrumentation `basic_consume` calls are also instrumented.
([#759](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/759))
- Consolidate instrumentation documentation in docstrings
([#754](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/754))

### Fixed

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,45 +16,6 @@ Installation

pip install opentelemetry-instrumentation-aiohttp-client


Example
-------

.. code:: python
import asyncio
import aiohttp
from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor
from opentelemetry import trace
from opentelemetry.exporter.jaeger.thrift import JaegerExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
_JAEGER_EXPORTER = JaegerExporter(
service_name="example-xxx",
agent_host_name="localhost",
agent_port=6831,
)
_TRACE_PROVIDER = TracerProvider()
_TRACE_PROVIDER.add_span_processor(BatchSpanProcessor(_JAEGER_EXPORTER))
trace.set_tracer_provider(_TRACE_PROVIDER)
AioHttpClientInstrumentor().instrument()
async def span_emitter():
async with aiohttp.ClientSession() as session:
async with session.get("https://example.com") as resp:
print(resp.status)
asyncio.run(span_emitter())
References
----------

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,29 @@ def strip_query_params(url: yarl.URL) -> str:
async with session.get(url) as response:
await response.text()
Configuration
-------------
Request/Response hooks
**********************
Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request.
.. code-block:: python
def request_hook(span: Span, params: aiohttp.TraceRequestStartParams):
if span and span.is_recording():
span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
def response_hook(span: Span, params: typing.Union[
aiohttp.TraceRequestEndParams,
aiohttp.TraceRequestExceptionParams,
]):
if span and span.is_recording():
span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
AioHttpClientInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)
API
---
"""
Expand Down
48 changes: 0 additions & 48 deletions instrumentation/opentelemetry-instrumentation-asgi/README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -17,54 +17,6 @@ Installation

pip install opentelemetry-instrumentation-asgi


Usage (Quart)
-------------

.. code-block:: python
from quart import Quart
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
app = Quart(__name__)
app.asgi_app = OpenTelemetryMiddleware(app.asgi_app)
@app.route("/")
async def hello():
return "Hello!"
if __name__ == "__main__":
app.run(debug=True)
Usage (Django 3.0)
------------------

Modify the application's ``asgi.py`` file as shown below.

.. code-block:: python
import os
from django.core.asgi import get_asgi_application
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'asgi_example.settings')
application = get_asgi_application()
application = OpenTelemetryMiddleware(application)
Usage (Raw ASGI)
----------------

.. code-block:: python
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
app = ... # An ASGI application.
app = OpenTelemetryMiddleware(app)
References
----------

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,82 @@
The opentelemetry-instrumentation-asgi package provides an ASGI middleware that can be used
on any ASGI framework (such as Django-channels / Quart) to track requests
timing through OpenTelemetry.
Usage (Quart)
-------------
.. code-block:: python
from quart import Quart
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
app = Quart(__name__)
app.asgi_app = OpenTelemetryMiddleware(app.asgi_app)
@app.route("/")
async def hello():
return "Hello!"
if __name__ == "__main__":
app.run(debug=True)
Usage (Django 3.0)
------------------
Modify the application's ``asgi.py`` file as shown below.
.. code-block:: python
import os
from django.core.asgi import get_asgi_application
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'asgi_example.settings')
application = get_asgi_application()
application = OpenTelemetryMiddleware(application)
Usage (Raw ASGI)
----------------
.. code-block:: python
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
app = ... # An ASGI application.
app = OpenTelemetryMiddleware(app)
Configuration
-------------
Request/Response hooks
**********************
Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request. The server request hook takes in a server span and ASGI
scope object for every incoming request. The client request hook is called with the internal span and an ASGI scope which is sent as a dictionary for when the method recieve is called.
The client response hook is called with the internal span and an ASGI event which is sent as a dictionary for when the method send is called.
.. code-block:: python
def server_request_hook(span: Span, scope: dict):
if span and span.is_recording():
span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
def client_request_hook(span: Span, scope: dict):
if span and span.is_recording():
span.set_attribute("custom_user_attribute_from_client_request_hook", "some-value")
def client_response_hook(span: Span, message: dict):
if span and span.is_recording():
span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
OpenTelemetryMiddleware().(application, server_request_hook=server_request_hook, client_request_hook=client_request_hook, client_response_hook=client_response_hook)
API
---
"""

import typing
Expand Down
45 changes: 0 additions & 45 deletions instrumentation/opentelemetry-instrumentation-celery/README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,51 +16,6 @@ Installation

pip install opentelemetry-instrumentation-celery

Usage
-----

* Start broker backend

::
docker run -p 5672:5672 rabbitmq


* Run instrumented task

.. code-block:: python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.instrumentation.celery import CeleryInstrumentor
from celery import Celery
from celery.signals import worker_process_init
@worker_process_init.connect(weak=False)
def init_celery_tracing(*args, **kwargs):
trace.set_tracer_provider(TracerProvider())
span_processor = BatchSpanProcessor(ConsoleSpanExporter())
trace.get_tracer_provider().add_span_processor(span_processor)
CeleryInstrumentor().instrument()
app = Celery("tasks", broker="amqp://localhost")
@app.task
def add(x, y):
return x + y
add.delay(42, 50)
Setting up tracing
--------------------

When tracing a celery worker process, tracing and instrumention both must be initialized after the celery worker
process is initialized. This is required for any tracing components that might use threading to work correctly
such as the BatchSpanProcessor. Celery provides a signal called ``worker_process_init`` that can be used to
accomplish this as shown in the example above.

References
----------
* `OpenTelemetry Celery Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/celery/celery.html>`_
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,14 @@ def add(x, y):
add.delay(42, 50)
Setting up tracing
------------------
When tracing a celery worker process, tracing and instrumention both must be initialized after the celery worker
process is initialized. This is required for any tracing components that might use threading to work correctly
such as the BatchSpanProcessor. Celery provides a signal called ``worker_process_init`` that can be used to
accomplish this as shown in the example above.
API
---
"""
Expand Down
46 changes: 0 additions & 46 deletions instrumentation/opentelemetry-instrumentation-django/README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,52 +15,6 @@ Installation

pip install opentelemetry-instrumentation-django

Configuration
-------------

Exclude lists
*************
To exclude certain URLs from being tracked, set the environment variable ``OTEL_PYTHON_DJANGO_EXCLUDED_URLS`` with comma delimited regexes representing which URLs to exclude.

For example,

::

export OTEL_PYTHON_DJANGO_EXCLUDED_URLS="client/.*/info,healthcheck"

will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.

Request attributes
********************
To extract certain attributes from Django's request object and use them as span attributes, set the environment variable ``OTEL_PYTHON_DJANGO_TRACED_REQUEST_ATTRS`` to a comma
delimited list of request attribute names.

For example,

::

export OTEL_PYTHON_DJANGO_TRACED_REQUEST_ATTRS='path_info,content_type'

will extract path_info and content_type attributes from every traced request and add them as span attritbues.

Django Request object reference: https://docs.djangoproject.com/en/3.1/ref/request-response/#attributes

Request and Response hooks
***************************
The instrumentation supports specifying request and response hooks. These are functions that get called back by the instrumentation right after a Span is created for a request
and right before the span is finished while processing a response. The hooks can be configured as follows:

::

def request_hook(span, request):
pass

def response_hook(span, request, response):
pass

DjangoInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)


References
----------

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,12 @@ def response_hook(span, request, response):
pass
DjangoInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
Django Request object: https://docs.djangoproject.com/en/3.1/ref/request-response/#httprequest-objects
Django Response object: https://docs.djangoproject.com/en/3.1/ref/request-response/#httpresponse-objects
API
---
"""

from logging import getLogger
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,6 @@
es.index(index='my-index', doc_type='my-type', id=1, body={'my': 'data', 'timestamp': datetime.now()})
es.get(index='my-index', doc_type='my-type', id=1)
API
---
Elasticsearch instrumentation prefixes operation names with the string "Elasticsearch". This
can be changed to a different string by either setting the `OTEL_PYTHON_ELASTICSEARCH_NAME_PREFIX`
environment variable or by passing the prefix as an argument to the instrumentor. For example,
Expand Down Expand Up @@ -79,6 +76,9 @@ def response_hook(span, response):
es = elasticsearch.Elasticsearch()
es.index(index='my-index', doc_type='my-type', id=1, body={'my': 'data', 'timestamp': datetime.now()})
es.get(index='my-index', doc_type='my-type', id=1)
API
---
"""

import re
Expand Down
Loading

0 comments on commit ae7a415

Please sign in to comment.