Package: datadog
The Datadog Python libraryThe 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.comSeeCHANGELOG.mdfor changes.InstallationTo install from pip:pip install datadogTo install from source:python setup.py installDatadog APITo support all Datadog HTTP APIs, a generated library is
available which will expose all the endpoints:datadog-api-client-python.Find below a working example for submitting an event to your Event Stream:fromdatadogimportinitialize,apioptions={"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 inthe Datadog API documentation.Note: The full list of available Datadog API endpoints is also available in theDatadog Python Library documentationEnvironment VariablesAs an alternate method to using theinitializefunction with theoptionsparameters, set the environment variablesDATADOG_API_KEYandDATADOG_APP_KEYwithin the context of your application.IfDATADOG_API_KEYorDATADOG_APP_KEYare not set, the library attempts to fall back to Datadog's APM environment variable prefixes:DD_API_KEYandDD_APP_KEY.fromdatadogimportinitialize,api# Assuming you've set `DD_API_KEY` and `DD_APP_KEY` in your env,# initialize() will pick it up automaticallyinitialize()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 anystatsdmetric collection usingDD_DOGSTATSD_DISABLE=True(or any not-empty value).DogStatsDIn order to use DogStatsD metrics, the Agent must berunning and available.Instantiate the DogStatsD client with UDPOnce the Datadog Python Library is installed, instantiate the StatsD client using UDP in your code:fromdatadogimportinitialize,statsdoptions={"statsd_host":"127.0.0.1","statsd_port":8125,}initialize(**options)See the full list of availableDogStatsD client instantiation parameters.Instantiate the DogStatsd client with UDSOnce the Datadog Python Library is installed, instantiate the StatsD client using UDS in your code:fromdatadogimportinitialize,statsdoptions={"statsd_socket_path":PATH_TO_SOCKET,}initialize(**options)Origin detection over UDP and UDSOrigin detection is a method to detect which podDogStatsDpackets are coming from in order to add the pod's tags to the tag list.
TheDogStatsDclient attaches an internal tag,entity_id. The value of this tag is the content of theDD_ENTITY_IDenvironment 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 onlyappendto theconstant_tagslist.To enable origin detection over UDP, add the following lines to your application manifestenv:-name:DD_ENTITY_IDvalueFrom:fieldRef:fieldPath:metadata.uidUsageMetricsAfter the client is created, you can start sending custom metrics to Datadog. See the dedicatedMetric Submission: DogStatsD documentationto 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 metricSubmit a HISTOGRAM metricSubmit a TIMER metricSubmit a DISTRIBUTION metricSome options are supported when submitting metrics, likeapplying a Sample Rate to your metricsortagging your metrics with your custom tags.EventsAfter the client is created, you can start sending events to your Datadog Event Stream. See the dedicatedEvent Submission: DogStatsD documentationto see how to submit an event to your Datadog Event Stream.Service ChecksAfter the client is created, you can start sending Service Checks to Datadog. See the dedicatedService Check Submission: DogStatsD documentationto see how to submit a Service Check to Datadog.Monitoring this clientThis 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 thestatsd.disable_telemetry()method.SeeTelemetry documentationto learn more about it.BenchmarksNote: You will need to installpsutilpackage before running the benchmarks.If you would like to get an approximate idea on the throughput that your DogStatsD library
can handle on your system, you can run the included local benchmark code:$ # Python 2 Example
$ python2 -m unittest -vvv tests.performance.test_statsd_throughput

$ # Python 3 Example
$ python3 -m unittest -vvv tests.performance.test_statsd_throughputYou can also add setBENCHMARK_*to customize the runs:$ # Example #1
$ BENCHMARK_NUM_RUNS=10 BENCHMARK_NUM_THREADS=1 BENCHMARK_NUM_DATAPOINTS=5000 BENCHMARK_TRANSPORT="UDP" python2 -m unittest -vvv tests.performance.test_statsd_throughput

$ # Example #2
$ BENCHMARK_NUM_THREADS=10 BENCHMARK_TRANSPORT="UDS" python3 -m unittest -vvv tests.performance.test_statsd_throughputMaximum packets size in high-throughput scenariosIn order to have the most efficient use of this library in high-throughput scenarios,
default values for the maximum packets size have already been set for both UDS (8192 bytes)
and UDP (1432 bytes) in order to have the best usage of the underlying network.
However, if you perfectly know your network and you know that a different value for the maximum packets
size should be used, you can set it with the parametermax_buffer_len. Example:fromdatadogimportinitializeoptions={"api_key":"<YOUR_API_KEY>","app_key":"<YOUR_APP_KEY>","max_buffer_len":4096,}initialize(**options)Thread SafetyDogStatsDandThreadStatsare thread-safe.