Datadog Python Library

Origin detection allows the Datadog Agent to identify which pod a DogStatsD packet originated from by using the entity_id tag (derived from the DD_ENTITY_ID environment variable).

To enable this in Kubernetes, add the following to your application manifest to map the pod's UID to DD_ENTITY_ID:

env:
  - name: DD_ENTITY_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.uid

Important: To avoid overwriting the global entity_id tag, only use append when adding to the constant_tags list.

You can run local benchmarks to estimate throughput. You must have the psutil package installed.

Python 3 Example:

python3 -m unittest -vvv tests.performance.test_statsd_throughput

Customizing runs: You can use BENCHMARK_* environment variables to customize the test:

• BENCHMARK_NUM_RUNS
• BENCHMARK_NUM_THREADS
• BENCHMARK_NUM_DATAPOINTS
• BENCHMARK_TRANSPORT (e.g., UDP or UDS)

Example with custom parameters:

BENCHMARK_NUM_THREADS=10 BENCHMARK_TRANSPORT="UDS" python3 -m unittest -vvv tests.performance.test_statsd_throughput

The project uses tox to manage test environments. You can pass pytest arguments through tox using a double dash --.

Common Test Commands

• Unit Tests (Python 3.7):

  tox -e py37

- **Style Checks (flake8)**:
  ```bash
tox -e flake8

Filtering Tests with Pytest Arguments

• Exclude a directory:

  tox -- --ignore-glob=tests/integration/*

- **Run tests matching a string (using `-k`)**:
  ```bash
tox -- -k dogstatsd

• Run a specific folder:

  tox -- tests/unit/dogstatsd

Integration tests run against a live Datadog account.

WARNING: Integration tests can perform destructive changes. Never use credentials for a production or important organization.

1. Configure Environment Variables

Export the following variables to provide credentials for a testing organization:

export DD_TEST_CLIENT_API_KEY=<api_key_for_a_testing_org>
export DD_TEST_CLIENT_APP_KEY=<app_key_for_a_testing_org>
export DD_TEST_CLIENT_USER=<user_handle_for_testing_comments_api>

2. Run Tests via Tox

• Regular Integration Tests: Tests that create/clean up resources (dashboards, monitors) and do not require admin privileges.

  tox -e integration

- **Admin Integration Tests**: Tests that require admin permissions or perform destructive changes (e.g., managing users, muting all monitors).
  ```bash
tox -e integration-admin

You can install the library via pip or from source.

Using pip:

pip install datadog

From source:

python setup.py install

The datadog module must be initialized using datadog.initialize.

An API key and an app key are required for HTTP API usage. You can provide them explicitly in the initialize call or set them as environment variables:

• DATADOG_API_KEY
• DATADOG_APP_KEY

If you are only using the DogStatsd client, keys are not required. You can also configure the StatsD host and port during initialization.

from datadog import initialize

initialize(
    api_key="<your api key>",
    app_key="<your app key>",
    statsd_host="127.0.0.1",
    statsd_port=8125
)

Install the Datadog Python library from PyPI using pip.

pip install datadog

To make changes to the codebase and run manual tests immediately, install the project locally in editable mode using pip:

pip install -e <path_to_cloned_project_dir>

For high-throughput scenarios, you can tune the maximum packet size using the max_buffer_len parameter in initialize(). Default values are optimized for UDS (8192 bytes) and UDP (1432 bytes).

from datadog import initialize

options = {
    "api_key": "<YOUR_API_KEY>",
    "app_key": "<YOUR_APP_KEY>",
    "max_buffer_len": 4096,
}

initialize(**options)

Instead of passing credentials to initialize(), you can set them as environment variables. The library looks for DATADOG_API_KEY and DATADOG_APP_KEY. If those are not found, it falls back to the APM prefixes DD_API_KEY and DD_APP_KEY.

To disable statsd metric collection in development, set DD_DOGSTATSD_DISABLE=True.

from datadog import initialize, api

# Assuming you've set `DD_API_KEY` and `DD_APP_KEY` in your env,
# initialize() will pick it up automatically
initialize()

title = "Something big happened!"
text = "And let me tell you all about it here!"
tags = ["version:1", "application:web"]

api.Event.create(title=title, text=text, tags=tags)

If statsd_host and statsd_port are not explicitly provided in initialize, and no statsd_socket_path is supplied, the library uses the DD_DOGSTATSD_URL environment variable to determine connection details. The URL must start with either udp:// or unix://.

Examples:

• UDP: DD_DOGSTATSD_URL=udp://localhost:8125
• Unix Domain Socket (UDS): DD_DOGSTATSD_URL=unix:///var/run/datadog/dsd.socket