The Datadog Python library
The Datadog Python Library is a collection of tools suitable for inclusion in existing Python projects or for the development of standalone scripts. It provides an abstraction on top of Datadog's raw HTTP interface and the Agent's DogStatsD metrics aggregation server, to interact with Datadog and efficiently report events and metrics.
- Library Documentation: https://datadogpy.readthedocs.io/en/latest/
- HTTP API Documentation: https://docs.datadoghq.com/api/
- DatadogHQ: https://datadoghq.com
See CHANGELOG.md for changes.
Installation
To install from pip:
pip install datadog
To install from source:
python setup.py install
Datadog API
Find below a working example for submitting an event to your Event Stream:
from datadog import initialize, api
options = {
'api_key': '<YOUR_API_KEY>',
'app_key': '<YOUR_APP_KEY>'
}
initialize(**options)
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)
Consult the full list of supported Datadog API endpoints with working code examples in the Datadog API documentation.
Note: The full list of available Datadog API endpoints is also available in the Datadog Python Library documentation
Environment Variables
As an alternate method to using the initialize function with the options parameters, set the environment variables DATADOG_API_KEY and DATADOG_APP_KEY within the context of your application.
If DATADOG_API_KEY or DATADOG_APP_KEY are not set, the library attempts to fall back to Datadog's APM environmnent variable prefixes: DD_API_KEY and DD_APP_KEY.
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)
In development, you can disable any statsd metric collection using DD_DOGSTATSD_DISABLE=True (or any not-empty value).
DogStatsD
In order to use DogStatsD metrics, the Agent must be running and available.
Instantiate the DogStatsD client with UDP
Once the Datadog Python Library is installed, instantiate the StatsD client using UDP in your code:
from datadog import initialize, statsd
options = {
'statsd_host':'127.0.0.1',
'statsd_port':8125
}
initialize(**options)
See the full list of available DogStatsD client instantiation parameters.
Instantiate the DogStatsd client with UDS
Once the Datadog Python Library is installed, instantiate the StatsD client using UDS in your code:
from datadog import initialize, statsd
options = {
'statsd_socket_path' : PATH_TO_SOCKET
}
initialize(**options)
Origin detection over UDP and UDS
Origin detection is a method to detect which pod DogStatsD packets are coming from in order to add the pod's tags to the tag list.
The DogStatsD client attaches an internal tag, entity_id. The value of this tag is the content of the DD_ENTITY_ID environment variable if found, which is the pod's UID. The Datadog Agent uses this tag to add container tags to the metrics. To avoid overwriting this global tag, make sure to only append to the constant_tags list.
To enable origin detection over UDP, add the following lines to your application manifest
env:
- name: DD_ENTITY_ID
valueFrom:
fieldRef:
fieldPath: metadata.uid
Usage
Metrics
After the client is created, you can start sending custom metrics to Datadog. See the dedicated Metric Submission: DogStatsD documentation to see how to submit all supported metric types to Datadog with working code examples:
- Submit a COUNT metric.
- Submit a GAUGE metric.
- Submit a SET metric
- Submit a HISTOGRAM metric
- Submit a TIMER metric
- Submit a DISTRIBUTION metric
Some options are suppported when submitting metrics, like applying a Sample Rate to your metrics or tagging your metrics with your custom tags.
Events
After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated Event Submission: DogStatsD documentation to see how to submit an event to your Datadog Event Stream.
Service Checks
After the client is created, you can start sending Service Checks to Datadog. See the dedicated Service Check Submission: DogStatsD documentation to see how to submit a Service Check to Datadog.
Monitoring this client
This client automatically injects telemetry about itself in the DogStatsD stream.
Those metrics will not be counted as custom and will not be billed. This feature can be disabled using the statsd.disable_telemetry() method.
See Telemetry documentation to learn more about it.
Thread Safety
DogStatsD and ThreadStats are thread-safe.
Release files for datadog 0.39.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| datadog-0.39.0.tar.gz | 584.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| datadog-0.39.0-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 691.0 kB
Release files / datadog-0.39.0.tar.gz
| Download URL | datadog-0.39.0.tar.gz |
|---|---|
| Size | 584.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b0ef69a27aad0e4412c1ac3e6894fa1b5741db735515c34dfe1606d8cf30e4e5
|
|
BLAKE2b-256 checksum How to use checksums |
abe064a25bde9e605d99356ad92ef6f1fde4d769c51686efc2080b327e3009e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.2
|
Release files / datadog-0.39.0-py2.py3-none-any.whl
| Download URL | datadog-0.39.0-py2.py3-none-any.whl |
|---|---|
| Size | 106.6 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
b6a42e3e99f704f0a9065e5659e82f11a931c771fc2b119795e86c836f6c5e14
|
|
BLAKE2b-256 checksum How to use checksums |
52a799342ad4d9ee452a61a14f0501d2319cd274fcb45980c4b60b8ad3484c83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.2
|
