{"id":477,"library":"datadog","title":"Datadog Python Library (datadogpy)","description":"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.","status":"active","version":"0.52.1","language":"python","source_language":"en","source_url":"https://github.com/DataDog/datadogpy","tags":["monitoring","metrics","observability","logs","events","statsd","APM-adjacent"],"install":[{"cmd":"pip install datadog","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 2.7 or >=3.6, but modern use strongly recommends Python 3.7+ for compatibility and features.","package":"python","optional":false}],"imports":[{"note":"Used to configure API/App keys and other client settings.","symbol":"initialize","correct":"from datadog import initialize"},{"note":"Provides access to Datadog's HTTP API endpoints (e.g., Events, Metrics).","symbol":"api","correct":"from datadog import api"},{"note":"Provides a client for sending metrics via DogStatsD to the Datadog Agent.","symbol":"statsd","correct":"from datadog import statsd"},{"note":"An alternative client for collecting and flushing metrics via the Datadog REST API in a worker thread.","symbol":"ThreadStats","correct":"from datadog import ThreadStats"},{"note":"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.","wrong":"from datadog import ApiClient","symbol":"ApiClient","correct":"from datadog_api_client import ApiClient"}],"quickstart":{"code":"import os\nfrom datadog import initialize, api, statsd\n\n# Configure with API and App keys, preferably from environment variables\noptions = {\n    'api_key': os.environ.get('DD_API_KEY', 'YOUR_DATADOG_API_KEY'),\n    'app_key': os.environ.get('DD_APP_KEY', 'YOUR_DATADOG_APP_KEY'),\n    # Uncomment and set api_host if your Datadog account is outside the US (e.g., EU)\n    # 'api_host': 'https://api.datadoghq.eu'\n}\ninitialize(**options)\n\n# Send an event to the Datadog Event Stream\ntry:\n    title = \"Python Quickstart Event!\"\n    text = \"This is a test event sent from the datadog Python library.\"\n    tags = [\"env:dev\", \"service:my-app\", \"source:python-script\"]\n    response = api.Event.create(title=title, text=text, tags=tags)\n    print(f\"Event sent successfully: {response.get('status')}. Event ID: {response.get('event', {}).get('id')}\")\nexcept Exception as e:\n    print(f\"Error sending event: {e}\")\n\n# Send a custom metric via DogStatsD (requires Datadog Agent running)\ntry:\n    statsd.increment('my_app.page_views', tags=['page:home', 'version:1.0'])\n    statsd.gauge('my_app.users_online', 150, tags=['region:us-east'])\n    print(\"Metrics sent via DogStatsD.\")\nexcept Exception as e:\n    print(f\"Error sending metrics via DogStatsD: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pass `api_host='https://api.datadoghq.eu'` (or your specific region's host) to `datadog.initialize()` or set the `DATADOG_HOST` environment variable.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For distributed tracing, continuous profiling, and auto-instrumentation of frameworks (e.g., Flask, Django), install and use the `ddtrace` library (`pip install ddtrace`).","message":"This `datadog` library does not provide APM (Application Performance Monitoring) tracing and profiling functionality. That is handled by the separate `ddtrace` library.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:08:46.762Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Run `pip install datadog` to install the library.","cause":"The `datadog` Python package is not installed in your current environment.","error":"ModuleNotFoundError: No module named 'datadog'"},{"fix":"Rename your local Python file (e.g., from `datadog.py` to `my_datadog_script.py`) to avoid the naming conflict.","cause":"A local Python file named `datadog.py` (or a similar name) is shadowing the installed `datadog` library, causing the Python interpreter to import your local file instead of the actual package.","error":"AttributeError: module 'datadog' has no attribute 'statsd'"},{"fix":"Initialize the library by calling `datadog.initialize(api_key='YOUR_API_KEY', app_key='YOUR_APP_KEY')` with valid keys, or set the `DATADOG_API_KEY` and `DATADOG_APP_KEY` environment variables.","cause":"The Datadog API and/or Application keys have not been properly provided to the `datadog.initialize()` function or set as environment variables.","error":"datadog.api.exceptions.ApiNotInitialized: No API key is set"},{"fix":"Ensure the Datadog Agent is running and its DogStatsD server is active (default UDP port 8125). Verify the `statsd_host` and `statsd_port` parameters in your `datadog.initialize()` call. If running your application on a different host than the Agent, ensure `dogstatsd_non_local_traffic: true` is set in your Datadog Agent configuration.","cause":"The Datadog Agent's DogStatsD server is either not running, not accessible at the specified host/port, or is configured to only accept local traffic from the agent itself.","error":"ConnectionRefusedError: [Errno 111] Connection refused (when sending DogStatsD metrics)"},{"fix":"datadog.initialize(api_key='YOUR_API_KEY', app_key='YOUR_APP_KEY') or set DATADOG_API_KEY and DATADOG_APP_KEY environment variables.","cause":"Datadog API methods were called without initializing the library with an API key, or without setting the DATADOG_API_KEY environment variable.","error":"AssertionError: Datadog API key is not set"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.72,"mem_mb":11.2,"disk_size":"22.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":11.2,"disk_size":"23M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.89,"mem_mb":12.7,"disk_size":"24.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.72,"mem_mb":12.7,"disk_size":"25M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":12.4,"disk_size":"16.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.78,"mem_mb":12.4,"disk_size":"17M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":12.8,"disk_size":"16.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":12.8,"disk_size":"16M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":10.9,"disk_size":"21.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":10.9,"disk_size":"22M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}