Datadog Python Library (datadogpy)

0.52.1 · active · verified Sat Mar 28

The `datadog` Python library (`datadogpy`) provides convenient interfaces for interacting with Datadog's HTTP API and sending metrics, events, and service checks via DogStatsD. It supports both UDP and Unix Domain Socket (UDS) transports for DogStatsD and includes a CLI tool ('dog') for API operations. As of version 0.52.1, it continues to be actively maintained, focusing on core API interactions and DogStatsD client functionality.

Warnings

gotcha Confusion between `datadog` and `datadog-api-client` libraries. `datadog` (this library) is the older, more general client. `datadog-api-client` is a newer, generated client providing comprehensive access to all Datadog API endpoints (including v2 and async capabilities). They have different installation paths (`pip install datadog` vs `pip install datadog-api-client`) and import patterns (`from datadog import ...` vs `from datadog_api_client import ...`). Ensure you install and import the correct library for your needs.
Fix: Always check which library you need. If you need v2 API access, async support, or access to all new endpoints, `datadog-api-client` is generally preferred. For simpler v1 API interactions or DogStatsD, `datadog` is sufficient.
gotcha API and Application Keys are critical for authentication. For API interactions (e.g., `api.Event.create`), both an API key and an Application key are almost always required.
Fix: Initialize the client using `datadog.initialize(api_key="YOUR_API_KEY", app_key="YOUR_APP_KEY")` or, preferably, set environment variables `DATADOG_API_KEY` and `DATADOG_APP_KEY`. Never hardcode keys directly in production code.
gotcha Regional endpoints must be configured for non-US Datadog accounts. If your Datadog instance is in the EU, for example, the default API host will be incorrect.
Fix: Pass `api_host='https://api.datadoghq.eu'` (or your specific region's host) to `datadog.initialize()` or set the `DATADOG_HOST` environment variable.
gotcha DogStatsD metrics require a running Datadog Agent. The `datadog.statsd` client sends UDP packets to a local DogStatsD server (usually part of the Datadog Agent). If the Agent is not running or not accessible on the configured host/port, metrics will be dropped silently or fail.
Fix: Ensure the Datadog Agent is installed, running, and configured to receive DogStatsD metrics (default port 8125). Verify network reachability from your application to the Agent.
gotcha This `datadog` library does not provide APM (Application Performance Monitoring) tracing and profiling functionality. That is handled by the separate `ddtrace` library.
Fix: For distributed tracing, continuous profiling, and auto-instrumentation of frameworks (e.g., Flask, Django), install and use the `ddtrace` library (`pip install ddtrace`).

Install

pip install datadog Install stable version

Imports

initialize
```
from datadog import initialize
```
Used to configure API/App keys and other client settings.
api
```
from datadog import api
```
Provides access to Datadog's HTTP API endpoints (e.g., Events, Metrics).
statsd
```
from datadog import statsd
```
Provides a client for sending metrics via DogStatsD to the Datadog Agent.
ThreadStats
```
from datadog import ThreadStats
```
An alternative client for collecting and flushing metrics via the Datadog REST API in a worker thread.
ApiClient
```
from datadog_api_client import ApiClient
```
This library (`datadog`) is distinct from `datadog-api-client`, which is a separately installed, generated client for all Datadog API endpoints (including v2, async support, etc.). Do not confuse their imports.

Quickstart

This quickstart demonstrates how to initialize the Datadog client using environment variables for API and Application keys and then send both an event via the HTTP API and custom metrics via DogStatsD. Remember to have the Datadog Agent running for DogStatsD metrics.

import os
from datadog import initialize, api, statsd

# Configure with API and App keys, preferably from environment variables
options = {
    'api_key': os.environ.get('DD_API_KEY', 'YOUR_DATADOG_API_KEY'),
    'app_key': os.environ.get('DD_APP_KEY', 'YOUR_DATADOG_APP_KEY'),
    # Uncomment and set api_host if your Datadog account is outside the US (e.g., EU)
    # 'api_host': 'https://api.datadoghq.eu'
}
initialize(**options)

# Send an event to the Datadog Event Stream
try:
    title = "Python Quickstart Event!"
    text = "This is a test event sent from the datadog Python library."
    tags = ["env:dev", "service:my-app", "source:python-script"]
    response = api.Event.create(title=title, text=text, tags=tags)
    print(f"Event sent successfully: {response.get('status')}. Event ID: {response.get('event', {}).get('id')}")
except Exception as e:
    print(f"Error sending event: {e}")

# Send a custom metric via DogStatsD (requires Datadog Agent running)
try:
    statsd.increment('my_app.page_views', tags=['page:home', 'version:1.0'])
    statsd.gauge('my_app.users_online', 150, tags=['region:us-east'])
    print("Metrics sent via DogStatsD.")
except Exception as e:
    print(f"Error sending metrics via DogStatsD: {e}")

view raw JSON →