Merge pull request #301 from palazzem/docs

[docs] update documentation after latest changes

Author: Emanuele Palazzetti

ddtrace/contrib/aiobotocore/__init__.py

@@ -1,9 +1,8 @@
 """
-The aiobotocore integration will trace all AWS calls made with the `aiobotocore`
-library.
+The aiobotocore integration will trace all AWS calls made with the ``aiobotocore``
+library. This integration isn't enabled when applying the default patching.
+To enable it, you must run ``patch_all(botocore=True)``
 
-This integration ignores autopatching, it can be enabled via
-`patch_all(botocore=True)`
 ::
 
     import aiobotocore.session
@@ -15,7 +14,8 @@
     # This will report spans with the default instrumentation
     aiobotocore.session.get_session()
     lambda_client = session.create_client('lambda', region_name='us-east-1')
-    # Example of instrumented query
+
+    # This query generates a trace
     lambda_client.list_functions()
 """
 from ..util import require_modules

ddtrace/contrib/aiohttp/__init__.py

@@ -17,27 +17,28 @@
     trace_app(app, tracer, service='async-api')
     web.run_app(app, port=8000)
 
-Tracer settings are available under the `datadog_trace` namespace:
-
-* `tracer` (default: `ddtrace.tracer`): set the default tracer instance that is used to
-trace `aiohttp` internals. By default the `ddtrace` tracer is used.
-* `service` (default: `aiohttp-web`): set the service name used by the tracer. Usually
-this configuration must be updated with a meaningful name.
-* `distributed_tracing_enabled` (default: `False): enable distributed tracing during
-the middleware execution, so that a new span is created with the given `trace_id` and
-`parent_id` passed via request headers.
-
-To update your settings, just:
+Integration settings are attached to your application under the ``datadog_trace``
+namespace. You can read or update them as follows::
 
     # activates distributed tracing for all received requests
     app['datadog_trace']['distributed_tracing_enabled'] = True
 
+Available settings are:
+
+* ``tracer`` (default: ``ddtrace.tracer``): set the default tracer instance that is used to
+  trace `aiohttp` internals. By default the `ddtrace` tracer is used.
+* ``service`` (default: ``aiohttp-web``): set the service name used by the tracer. Usually
+  this configuration must be updated with a meaningful name.
+* ``distributed_tracing_enabled`` (default: ``False``): enable distributed tracing during
+  the middleware execution, so that a new span is created with the given ``trace_id`` and
+  ``parent_id`` injected via request headers.
+
 Third-party modules that are currently supported by the ``patch()`` method are:
 
 * ``aiohttp_jinja2``
 
-When a request span is automatically created, the ``Context`` for this logical execution
-is attached to the ``request`` object, so that it can be used in the application code::
+When a request span is created, a new ``Context`` for this logical execution is attached
+to the ``request`` object, so that it can be used in the application code::
 
     async def home_handler(request):
         ctx = request['datadog_context']

ddtrace/contrib/aiopg/__init__.py

@@ -1,7 +1,5 @@
-"""Instrument aiopg to report Postgres queries.
-
-``patch`` will automatically patch your aiopg connection to make it work.
-::
+"""
+Instrument `aiopg` to report a span for each executed Postgres queries::
 
     from ddtrace import Pin, patch
     import aiopg
@@ -12,13 +10,14 @@
     # This will report a span with the default settings
     async with aiopg.connect(DSN) as db:
         with (await db.cursor()) as cursor:
-            await cursor.execute("select * from users where id = 1")
+            await cursor.execute("SELECT * FROM users WHERE id = 1")
 
     # Use a pin to specify metadata related to this connection
     Pin.override(db, service='postgres-users')
 """
 from ..util import require_modules
 
+
 required_modules = ['aiopg']
 
 with require_modules(required_modules) as missing_modules:

ddtrace/contrib/asyncio/__init__.py

@@ -31,6 +31,12 @@ async def some_work():
       ``loop.run_in_executor`` that attaches the current context to the
       new thread so that the trace can be resumed regardless when
       it's executed
+    * ``create_task(coro)``: creates a new asyncio ``Task`` that inherits
+      the current active ``Context`` so that generated traces in the new task
+      are attached to the main trace
+
+A ``patch(asyncio=True)`` is available if you want to automatically use above
+wrappers without changing your code.
 """
 from ..util import require_modules
 

ddtrace/contrib/asyncio/helpers.py

@@ -4,8 +4,8 @@
 Context and Spans in instrumented ``asyncio`` code.
 """
 import asyncio
-from asyncio.base_events import BaseEventLoop
 import ddtrace
+from asyncio.base_events import BaseEventLoop
 
 from .provider import CONTEXT_ATTR
 from ...context import Context
@@ -87,15 +87,18 @@ def create_task(*args, **kwargs):
 
 
 def _wrapped_create_task(wrapped, instance, args, kwargs):
-    # Note: we can't just link the task contexts due to the following scenario:
-    # begin task A
-    # task A starts task B1..B10
-    # finish task B1-B9 (B10 still on trace stack)
-    # task A starts task C
-    #
-    # now task C gets parented to task B10 since it's still on the stack, however
-    # was not actually triggered by B10
-
+    """Wrapper for ``create_task(coro)`` that propagates the current active
+    ``Context`` to the new ``Task``. This function is useful to connect traces
+    of detached executions.
+
+    Note: we can't just link the task contexts due to the following scenario:
+        * begin task A
+        * task A starts task B1..B10
+        * finish task B1-B9 (B10 still on trace stack)
+        * task A starts task C
+        * now task C gets parented to task B10 since it's still on the stack,
+          however was not actually triggered by B10
+    """
     new_task = wrapped(*args, **kwargs)
     current_task = asyncio.Task.current_task()
 

ddtrace/contrib/django/__init__.py

@@ -12,8 +12,8 @@
         'ddtrace.contrib.django',
     ]
 
-    # It might be MIDDLEWARE instead of MIDDLEWARE_CLASSES for Django 1.10+
-    MIDDLEWARE_CLASSES = (
+    # or MIDDLEWARE_CLASSES for Django pre 1.10
+    MIDDLEWARE = (
         # the tracer must be the first middleware
         'ddtrace.contrib.django.TraceMiddleware',
 
@@ -39,8 +39,10 @@
 
 The available settings are:
 
-* ``DEFAULT_SERVICE`` (default: ``django``): set the service name used by the
+* ``DEFAULT_SERVICE`` (default: ``'django'``): set the service name used by the
   tracer. Usually this configuration must be updated with a meaningful name.
+* ``DEFAULT_DATABASE_PREFIX`` (default: ``''``): set a prefix value to database services,
+  so that your service is listed such as `prefix-defaultdb`.
 * ``TAGS`` (default: ``{}``): set global tags that should be applied to all
   spans.
 * ``TRACER`` (default: ``ddtrace.tracer``): set the default tracer
@@ -58,7 +60,6 @@
   disabled even if present.
 * ``AGENT_HOSTNAME`` (default: ``localhost``): define the hostname of the trace agent.
 * ``AGENT_PORT`` (default: ``8126``): define the port of the trace agent.
-* ``DEFAULT_DATABASE_PREFIX`` (default: ``''``): set a prefix value to database services.
 """
 from ..util import require_modules