.. include:: ./shared.rst
.. _Installation:
Installation + Quickstart
=========================
Before installing be sure to read through the `setup documentation`_ to ensure
your environment is ready to receive traces.
Installation
------------
Install with :code:`pip`::
pip install ddtrace
.. important::
pip version 18 and above is required to install the library.
It is strongly suggested to pin the version of the library you deploy.
Installation on Alpine
~~~~~~~~~~~~~~~~~~~~~~
Binary distributions are not available for Alpine so build dependencies must be installed first.
.. code-block:: bash
apk add gcc musl-dev linux-headers
pip install ddtrace
Quickstart
----------
.. important::
Using `gevent `__? Read our :ref:`gevent documentation`.
Using `Gunicorn `__? Read the :ref:`Gunicorn documentation`.
Using `uWSGI `__? Read our :ref:`uWSGI documentation`.
Tracing
~~~~~~~
Getting started for tracing is as easy as prefixing your python entry-point
command with ``ddtrace-run``.
For example if you start your application with ``python app.py`` then run (with
your desired settings in place of the example environment variables)::
DD_SERVICE=app DD_ENV=dev DD_VERSION=0.1 ddtrace-run python app.py
For more advanced usage of ``ddtrace-run`` refer to the documentation
:ref:`here`.
If ``ddtrace-run`` isn't suitable for your application then :ref:`patch_all`
can be used::
from ddtrace import config, patch_all
config.env = "dev" # the environment the application is in
config.service = "app" # name of your application
config.version = "0.1" # version of your application
patch_all()
Service names also need to be configured for libraries that query other
services (``requests``, ``grpc``, database libraries, etc). Check out the
:ref:`integration documentation` for each to set them up.
For additional configuration see the :ref:`configuration `
documentation.
To learn how to manually instrument check out the :ref:`basic usage ` documentation.
Profiling
~~~~~~~~~
Profiling can also be auto enabled with :ref:`ddtracerun` by providing the
``DD_PROFILING_ENABLED`` environment variable::
DD_PROFILING_ENABLED=true ddtrace-run python app.py
If ``ddtrace-run`` isn't suitable for your application then
``ddtrace.profiling.auto`` can be used::
import ddtrace.profiling.auto
Configuration
~~~~~~~~~~~~~
Almost all configuration of ``ddtrace`` can be done via environment
variable. See the full list in :ref:`Configuration`.
OpenTracing
-----------
``ddtrace`` also provides an OpenTracing API to the Datadog tracer so
that you can use the Datadog tracer in your OpenTracing-compatible
applications.
Installation
~~~~~~~~~~~~
Include OpenTracing with ``ddtrace``::
$ pip install ddtrace[opentracing]
To include the OpenTracing dependency in your project with ``ddtrace``, ensure
you have the following in ``setup.py``::
install_requires=[
"ddtrace[opentracing]",
],
Configuration
~~~~~~~~~~~~~
The OpenTracing convention for initializing a tracer is to define an
initialization method that will configure and instantiate a new tracer and
overwrite the global ``opentracing.tracer`` reference.
Typically this method looks something like::
from ddtrace.opentracer import Tracer, set_global_tracer
def init_tracer(service_name):
"""
Initialize a new Datadog opentracer and set it as the
global tracer.
This overwrites the opentracing.tracer reference.
"""
config = {
'agent_hostname': 'localhost',
'agent_port': 8126,
}
tracer = Tracer(service_name, config=config)
set_global_tracer(tracer)
return tracer
For more advanced usage of OpenTracing in ``ddtrace`` refer to the
documentation :ref:`here`.