Skip to content

Latest commit

 

History

History
161 lines (106 loc) · 4.38 KB

basic_usage.rst

File metadata and controls

161 lines (106 loc) · 4.38 KB

Basic Usage

Tracing

ddtrace.auto

To set up instrumentation within your application, call :ref:`import ddtrace.auto<ddtraceauto>` as early as possible in your application. This will only work if your application is not running under ddtrace-run.

patch_all

For fine-grained control over instrumentation setup, use patch_all as early as possible in the application:

from ddtrace import patch_all
patch_all()

To toggle instrumentation for a particular module:

from ddtrace import patch_all
patch_all(redis=False, cassandra=False)

By default all supported libraries will be instrumented when patch_all is used.

Note: To ensure that the supported libraries are instrumented properly in the application, they must be patched prior to being imported. So make sure to call patch_all before importing libraries that are to be instrumented.

More information about patch_all is available in the :py:func:`patch_all<ddtrace.patch_all>` API documentation.

Manual Instrumentation

To extend the functionality of the ddtrace library several APIs are provided.

Decorator

ddtrace provides a decorator that can be used to trace a particular method in your application:

@tracer.wrap()
def business_logic():
  """A method that would be of interest to trace."""
  # ...
  # ...

API documentation can be found here :py:meth:`ddtrace.Tracer.wrap`.

Context Manager

To trace an arbitrary block of code, you can use :py:meth:`ddtrace.Tracer.trace` that returns a :py:mod:`ddtrace.Span` which can be used as a context manager:

# trace some interesting operation
with tracer.trace('interesting.operations'):
  # do some interesting operation(s)
  # ...
  # ...

API documentation can be found here :py:meth:`ddtrace.Tracer`.

Using the API

If the above methods are still not enough to satisfy your tracing needs, a manual API to provide complete control over starting and stopping spans is available:

span = tracer.trace('operations.of.interest')  # span is started once created

# do some operation(s) of interest in between

# NOTE: be sure to call span.finish() or the trace will not be sent to
#       Datadog
span.finish()

API details for creating and finishing spans can be found here:

Profiling

Via module

To automatically profile your code, you can import the ddtrace.profiling.auto module. As soon as it is imported, it will start capturing CPU profiling information on your behalf:

import ddtrace.profiling.auto

Via API

If you want to control which part of your code should be profiled, you can use the ddtrace.profiling.Profiler object:

from ddtrace.profiling import Profiler

prof = Profiler()
prof.start()

# At shutdown
prof.stop()

Important

The profiler has been designed to be always-on. The start and stop methods are provided in case you need a fine-grained control over the profiler lifecycle. They are not provided for starting and stopping the profiler many times during your application lifecycle. Do not use them for e.g. building a context manager.

Asyncio Support

The profiler supports the asyncio library and retrieves the asyncio.Task names to tag along the profiled data.

For this to work, the profiler replaces the default event loop policy with a custom policy that tracks threads to loop mapping.

The custom asyncio loop policy is installed by default at profiler startup. You can disable this behavior by using the asyncio_loop_policy parameter and passing it None:

from ddtrace.profiling import Profiler

prof = Profiler(asyncio_loop_policy=None)

You can also pass a custom class that implements the interface from ddtrace.profiling.profiler.DdtraceProfilerEventLoopPolicy:

from ddtrace.profiling import Profiler

prof = Profiler(asyncio_loop_policy=MyLoopPolicy())

If the loop policy has been overridden after the profiler has started, you can always restore the profiler asyncio loop policy by calling the set_asyncio_event_loop_policy method:

from ddtrace.profiling import Profiler

prof = Profiler()
prof.set_asyncio_event_loop_policy()