This repository contains
ddtrace, Datadog's APM client Python package.
ddtrace contains APIs to automatically or
manually trace and
profile Python applications.
These features power Distributed Tracing, Continuous Profiling, Error Tracking, Continuous Integration Visibility, Deployment Tracking, Code Hotspots and more.
To get started, check out the setup documentation.
For advanced usage and configuration, check out the API documentation.
Confused about the terminology of APM? Take a look at the APM Glossary.
See the contributing docs first.
NOTE: Pre-commit hooks are optional and provided as a convenience for contributors. If pre-commit hooks fail to run in your development environment, you can uninstall them by deleting the symlink created by the installation script:
$ rm .git/hooks/pre-commit
The tracer library uses formatting/linting tools including black, flake8, and mypy.
While these are run in each CI pipeline for pull requests, they are automated to run
when you call
git commit as pre-commit hooks to catch any formatting errors before
you commit. To initialize the pre-commit hook script to run in your development
branch, run the following command:
$ hooks/autohook.sh install
Set up your environment
Set up docker
The test suite requires many backing services such as PostgreSQL, MySQL, Redis
and more. We use
docker-compose to run the services in our CI
and for development. To run the test matrix, please install docker and
docker-compose using the instructions provided by your platform. Then
launch them through:
$ docker-compose up -d
Set up Python
- Clone the repository locally:
git clone https://github.com/DataDog/dd-trace-py
- The tests for this project run on various versions of Python. We recommend using a Python version management tool, such as pyenv, to utilize multiple versions of Python. How to install Pyenv
- Install the relevant versions of Python in Pyenv:
pyenv install 2.7.18 3.5.10 3.6.15 3.7.13 3.8.13 3.9.13 3.10.5
- Make those versions available globally:
pyenv global 2.7.18 3.5.10 3.6.15 3.7.13 3.8.13 3.9.13 3.10.5
Running Tests in docker
The dd-trace-py testrunner docker image allows you to run tests in an environment that matches CI. This is especially useful if you are unable to install certain test dependencies on your dev machine's bare metal.
Once your docker-compose environment is running, you can use the shell script to execute tests within a Docker image. You can start the container with a bash shell:
You can now run tests as you would do in your local environment. We use riot, a new tool that we developed for addressing our specific needs with an ever growing matrix of tests. You can list the tests managed by each:
$ riot list
You can run multiple tests by using regular expressions:
$ riot run psycopg
Running Tests locally
- Install riot:
pip install riot.
- Create the base virtual environments:
riot -v generate.
- You can list the available test suites with
- Certain tests might require running service containers in order to emulate
the necessary testing environment. You can spin up individual containers with
docker-compose up -d <SERVICE_NAME>, where
<SERVICE_NAME>should match a service specified in the
- Run a test suite:
riot -v run <RUN_FLAGS> <TEST_SUITE_NAME>.
You can use the
-s prevents riot from reinstalling the dev package;
-x forces an exit after the first failed test suite. To limit the tests to a particular
version of Python, use the
riot -v run -p <PYTHON_VERSION>. You can also pass
command line arguments to the underlying test runner (like pytest) with the
For example, you can run a specific test under pytest with
riot -v run -s gunicorn -- -k test_no_known_errors_occur
run command uses regex syntax, which in some cases will cause multiple
test suites to run. Use the following syntax to ensure only an individual suite
^ signifies the start of a string and
signifies the end of a string. For example, use
riot -v run -s -x ^redis$ to
run only the redis suite.
Use the APM Test Agent
The APM test agent can emulate the APM endpoints of the Datadog agent. Spin up
testagent container along with any other service container:
$ docker-compose up -d testagent <SERVICE_CONTAINER>
Run the test agent as a proxy in your tests:
$ DD_TRACE_AGENT_URL=http://localhost:9126/ riot -v run <RUN_FLAGS> --pass-env <TEST_SUITE_NAME>
--pass-env injects the environment variables of the current shell session into
the command. Here's an example command for running the redis test suite along
with the test agent, limited to tests for Python 3.9:
$ DD_TRACE_AGENT_URL=http://localhost:9126/ riot -v run -p 3.9 -s -x --pass-env '^redis$'
Read more about the APM test agent: https://github.com/datadog/dd-apm-test-agent#readme
We use CircleCI 2.0 for our continuous integration.
The CI tests are configured through config.yml.
The CI tests can be run locally using the
circleci CLI. More information about
the CLI can be found at https://circleci.com/docs/2.0/local-cli/.
After installing the
circleci CLI, you can run jobs by name. For example:
$ circleci build --job django
This project follows semver and so bug fixes, breaking changes, new features, etc must be accompanied by a release note.
See the contributing docs for instructions on generating, writing, formatting, and styling release notes.