datadogpy

datadog (PyPI: datadog, GitHub: DataDog/datadogpy) is Datadog’s official Python library for interacting with the Datadog platform. It wraps Datadog’s HTTP REST API for metrics, events, monitors, dashboards, hosts, users, and more than a dozen other resource types, and it ships a DogStatsd client for reporting custom application metrics through the Datadog Agent over UDP or a Unix domain socket without blocking application code. It also bundles the threadstats module, an in-process alternative to DogStatsd for aggregating metrics before flushing, plus dogshell and dogwrap command-line tools that expose the same API operations for scripting and CI use.

Under the hood, requests handles all outbound HTTP calls to the REST API, and typed resource mixin classes cover everything from AWS/GCP/Azure integration endpoints to security monitoring signals and service level objectives. The library targets Python 2.7 and Python 3.7+, ships inline type stubs via a py.typed marker, and is maintained directly by Datadog with unit, integration, and performance test suites plus mypy and flake8 checks running in CI.

What You Get

• Full-coverage HTTP API client for metrics, events, monitors, dashboards, hosts, users, and 20+ other Datadog resource types
• DogStatsd client (datadog.statsd) for counters, gauges, histograms, distributions, sets, and timing metrics sent over UDP or a Unix domain socket
• threadstats module as an in-process alternative to DogStatsd for aggregating metrics before flushing
• dogshell and dogwrap command-line tools for scripting Datadog operations and wrapping arbitrary commands with timing/status metrics
• Type stubs shipped via a py.typed marker for editor and mypy support

Common Use Cases

• Reporting custom application metrics and events from Python services running on hosts, containers, or Lambda
• Managing Datadog monitors, dashboards, and downtimes as code from CI/CD or infrastructure scripts
• Wrapping cron jobs or build steps with dogwrap to automatically emit success/failure metrics and events
• Building internal tooling that queries Datadog’s API for hosts, tags, or service level objective status

Under The Hood

Architecture Mixin-based resource classes in datadog/api/resources.py (CreateableAPIResource, SendableAPIResource, ListableAPIResource, and similar) compose into per-endpoint resource classes in datadog/api/ (metrics.py, events.py, monitors.py, dashboards.py, and more), all delegating to a shared APIClient.submit dispatcher (datadog/api/api_client.py) that sits on top of a single HTTPClient built on requests. Configuration is held as module-level globals (api._api_key, api._api_host) set once via initialize() in datadog/init.py, acting as a lightweight singleton rather than an injected client instance, so supporting multiple concurrent configurations would mean touching shared module state. The DogStatsd client (datadog/dogstatsd/base.py) is a fully separate execution path with its own aggregator, buffering, and UDP/Unix-socket handling, and the threadstats package implements a similar aggregate-then-flush shape independently — the library is really three loosely coupled subsystems (REST API client, DogStatsd client, threadstats) sharing only version and utility modules.

Tech Stack A pure-Python library targeting Python 2.7 and 3.7+ per its classifiers, built with hatchling, with requests as effectively its only runtime dependency for the REST client (plus conditional typing/configparser backports for older interpreters). It ships console-script entry points (dog, dogwrap, dogshell, dogshellwrap) wired through the dogshell package, while DogStatsd talks over raw UDP or Unix domain sockets rather than through an HTTP library. Testing runs through tox across interpreter, lint, mypy, and integration environments, with vcrpy and pytest-vcr replaying recorded HTTP cassettes for integration coverage and freezegun for time mocking; CI runs on Azure Pipelines, style is enforced with flake8, and typing is checked with mypy, with the package shipping a py.typed marker.

Code Quality An extensive test suite spans tests/unit, tests/integration, and tests/performance, covering the API client, dogshell, dogstatsd, dogwrap, and threadstats independently. Integration tests replay recorded HTTP interactions via vcrpy cassettes rather than hitting the live API. Inline type comments are used pervasively for dual Python 2/3 compatible typing ahead of full annotation syntax, checked by mypy, and docstrings follow a dense Sphinx-style convention throughout the API surface. Error handling favors explicit typed exceptions over silent failures, with initialize() documenting a mute option that controls whether API errors propagate. No test files were found lacking coverage for any major subsystem.

What Makes It Unique The library packages three distinct metric-reporting paths behind one namespace: a full REST API client, a low-latency DogStatsd client with client-side aggregation/buffering for high-throughput code, and a Lambda-safe async metric helper (datadog_lambda_wrapper) so serverless handlers can emit custom metrics without adding latency to the response path. Bundling dogshell/dogwrap alongside the importable client is unusual among comparable SDKs, letting the same library back both application instrumentation and shell-level CI observability.