| Name | datadog JSON |
| Version |
0.49.1
JSON |
| download |
| home_page | |
| Summary | The Datadog Python library |
| upload_time | 2024-03-19 15:24:28 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7 |
| license | BSD-3-Clause |
| keywords |
datadog
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# The Datadog Python library
[](https://dev.azure.com/datadoghq/datadogpy/_build/latest?definitionId=10&branchName=master)
[](https://dev.azure.com/datadoghq/datadogpy/_build/latest?definitionId=13&branchName=master)
[](https://readthedocs.org/projects/datadogpy/?badge=latest)
[](https://pypi.org/project/datadog)
[](https://pepy.tech/project/datadog)
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](https://github.com/DataDog/datadogpy/blob/master/CHANGELOG.md) for changes.
## Installation
To install from pip:
pip install datadog
To install from source:
python setup.py install
## Datadog API
To support all Datadog HTTP APIs, a generated library is
available which will expose all the endpoints:
[datadog-api-client-python](https://github.com/DataDog/datadog-api-client-python).
Find below a working example for submitting an event to your Event Stream:
```python
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](https://docs.datadoghq.com/api/latest/?code-lang=python).**
**Note**: The full list of available Datadog API endpoints is also available in the [Datadog Python Library documentation](https://datadogpy.readthedocs.io/en/latest/)
#### 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 environment variable prefixes: `DD_API_KEY` and `DD_APP_KEY`.
```python
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](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=python).
### Instantiate the DogStatsD client with UDP
Once the Datadog Python Library is installed, instantiate the StatsD client using UDP in your code:
```python
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](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=python#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:
```python
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
```yaml
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](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python) to see how to submit all supported metric types to Datadog with working code examples:
* [Submit a COUNT metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#count).
* [Submit a GAUGE metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#gauge).
* [Submit a SET metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#set)
* [Submit a HISTOGRAM metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#histogram)
* [Submit a TIMER metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#timer)
* [Submit a DISTRIBUTION metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#distribution)
Some options are supported when submitting metrics, like [applying a Sample Rate to your metrics](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#metric-submission-options) or [tagging your metrics with your custom tags](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#metric-tagging).
#### Events
After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated [Event Submission: DogStatsD documentation](https://docs.datadoghq.com/events/guides/dogstatsd/?code-lang=python) 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](https://docs.datadoghq.com/developers/service_checks/dogstatsd_service_checks_submission/?code-lang=python) 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](https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?code-lang=python#client-side-telemetry) to learn more about it.
### Benchmarks
_Note: You will need to install `psutil` package 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:
```sh-session
$ # Python 2 Example
$ python2 -m unittest -vvv tests.performance.test_statsd_throughput
$ # Python 3 Example
$ python3 -m unittest -vvv tests.performance.test_statsd_throughput
```
You can also add set `BENCHMARK_*` to customize the runs:
```sh-session
$ # 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_throughput
```
## Maximum packets size in high-throughput scenarios
In 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 parameter `max_buffer_len`. Example:
```python
from datadog import initialize
options = {
"api_key": "<YOUR_API_KEY>",
"app_key": "<YOUR_APP_KEY>",
"max_buffer_len": 4096,
}
initialize(**options)
```
## Thread Safety
`DogStatsD` and `ThreadStats` are thread-safe.
Raw data
{
"_id": null,
"home_page": "",
"name": "datadog",
"maintainer": "",
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7",
"maintainer_email": "",
"keywords": "datadog",
"author": "",
"author_email": "\"Datadog, Inc.\" <dev@datadoghq.com>",
"download_url": "https://files.pythonhosted.org/packages/24/d4/fcf0894ebeac76698076f224e566b65f6be218d673ef4b5570728c5ce157/datadog-0.49.1.tar.gz",
"platform": null,
"description": "# The Datadog Python library\n\n[](https://dev.azure.com/datadoghq/datadogpy/_build/latest?definitionId=10&branchName=master)\n[](https://dev.azure.com/datadoghq/datadogpy/_build/latest?definitionId=13&branchName=master)\n[](https://readthedocs.org/projects/datadogpy/?badge=latest)\n[](https://pypi.org/project/datadog)\n[](https://pepy.tech/project/datadog)\n\nThe 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.\n\n- Library Documentation: https://datadogpy.readthedocs.io/en/latest/\n- HTTP API Documentation: https://docs.datadoghq.com/api/\n- DatadogHQ: https://datadoghq.com\n\nSee [CHANGELOG.md](https://github.com/DataDog/datadogpy/blob/master/CHANGELOG.md) for changes.\n\n## Installation\n\nTo install from pip:\n\n pip install datadog\n\nTo install from source:\n\n python setup.py install\n\n## Datadog API\n\nTo support all Datadog HTTP APIs, a generated library is\navailable which will expose all the endpoints:\n[datadog-api-client-python](https://github.com/DataDog/datadog-api-client-python).\n\nFind below a working example for submitting an event to your Event Stream:\n\n```python\nfrom datadog import initialize, api\n\noptions = {\n \"api_key\": \"<YOUR_API_KEY>\",\n \"app_key\": \"<YOUR_APP_KEY>\",\n}\n\ninitialize(**options)\n\ntitle = \"Something big happened!\"\ntext = \"And let me tell you all about it here!\"\ntags = [\"version:1\", \"application:web\"]\n\napi.Event.create(title=title, text=text, tags=tags)\n```\n\n**Consult the full list of supported Datadog API endpoints with working code examples in [the Datadog API documentation](https://docs.datadoghq.com/api/latest/?code-lang=python).**\n\n**Note**: The full list of available Datadog API endpoints is also available in the [Datadog Python Library documentation](https://datadogpy.readthedocs.io/en/latest/)\n\n#### Environment Variables\n\nAs 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.\n\nIf `DATADOG_API_KEY` or `DATADOG_APP_KEY` are not set, the library attempts to fall back to Datadog's APM environment variable prefixes: `DD_API_KEY` and `DD_APP_KEY`.\n\n```python\nfrom datadog import initialize, api\n\n# Assuming you've set `DD_API_KEY` and `DD_APP_KEY` in your env,\n# initialize() will pick it up automatically\ninitialize()\n\ntitle = \"Something big happened!\"\ntext = \"And let me tell you all about it here!\"\ntags = [\"version:1\", \"application:web\"]\n\napi.Event.create(title=title, text=text, tags=tags)\n```\n\nIn development, you can disable any `statsd` metric collection using `DD_DOGSTATSD_DISABLE=True` (or any not-empty value).\n\n## DogStatsD\n\nIn order to use DogStatsD metrics, the Agent must be [running and available](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=python).\n\n### Instantiate the DogStatsD client with UDP\n\nOnce the Datadog Python Library is installed, instantiate the StatsD client using UDP in your code:\n\n```python\nfrom datadog import initialize, statsd\n\noptions = {\n \"statsd_host\": \"127.0.0.1\",\n \"statsd_port\": 8125,\n}\n\ninitialize(**options)\n```\n\nSee the full list of available [DogStatsD client instantiation parameters](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=python#client-instantiation-parameters).\n\n#### Instantiate the DogStatsd client with UDS\n\nOnce the Datadog Python Library is installed, instantiate the StatsD client using UDS in your code:\n```python\n\nfrom datadog import initialize, statsd\n\noptions = {\n \"statsd_socket_path\": PATH_TO_SOCKET,\n}\n\ninitialize(**options)\n```\n\n#### Origin detection over UDP and UDS\n\nOrigin 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.\nThe `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.\n\nTo enable origin detection over UDP, add the following lines to your application manifest\n```yaml\nenv:\n - name: DD_ENTITY_ID\n valueFrom:\n fieldRef:\n fieldPath: metadata.uid\n```\n\n### Usage\n#### Metrics\n\nAfter the client is created, you can start sending custom metrics to Datadog. See the dedicated [Metric Submission: DogStatsD documentation](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python) to see how to submit all supported metric types to Datadog with working code examples:\n\n* [Submit a COUNT metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#count).\n* [Submit a GAUGE metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#gauge).\n* [Submit a SET metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#set)\n* [Submit a HISTOGRAM metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#histogram)\n* [Submit a TIMER metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#timer)\n* [Submit a DISTRIBUTION metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#distribution)\n\nSome options are supported when submitting metrics, like [applying a Sample Rate to your metrics](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#metric-submission-options) or [tagging your metrics with your custom tags](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=python#metric-tagging).\n\n#### Events\n\nAfter the client is created, you can start sending events to your Datadog Event Stream. See the dedicated [Event Submission: DogStatsD documentation](https://docs.datadoghq.com/events/guides/dogstatsd/?code-lang=python) to see how to submit an event to your Datadog Event Stream.\n\n#### Service Checks\n\nAfter the client is created, you can start sending Service Checks to Datadog. See the dedicated [Service Check Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/service_checks/dogstatsd_service_checks_submission/?code-lang=python) to see how to submit a Service Check to Datadog.\n\n### Monitoring this client\n\nThis client automatically injects telemetry about itself in the DogStatsD stream.\nThose metrics will not be counted as custom and will not be billed. This feature can be disabled using the `statsd.disable_telemetry()` method.\n\nSee [Telemetry documentation](https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?code-lang=python#client-side-telemetry) to learn more about it.\n\n### Benchmarks\n\n_Note: You will need to install `psutil` package before running the benchmarks._\n\nIf you would like to get an approximate idea on the throughput that your DogStatsD library\ncan handle on your system, you can run the included local benchmark code:\n\n```sh-session\n$ # Python 2 Example\n$ python2 -m unittest -vvv tests.performance.test_statsd_throughput\n\n$ # Python 3 Example\n$ python3 -m unittest -vvv tests.performance.test_statsd_throughput\n```\n\nYou can also add set `BENCHMARK_*` to customize the runs:\n```sh-session\n$ # Example #1\n$ BENCHMARK_NUM_RUNS=10 BENCHMARK_NUM_THREADS=1 BENCHMARK_NUM_DATAPOINTS=5000 BENCHMARK_TRANSPORT=\"UDP\" python2 -m unittest -vvv tests.performance.test_statsd_throughput\n\n$ # Example #2\n$ BENCHMARK_NUM_THREADS=10 BENCHMARK_TRANSPORT=\"UDS\" python3 -m unittest -vvv tests.performance.test_statsd_throughput\n```\n\n## Maximum packets size in high-throughput scenarios\n\nIn order to have the most efficient use of this library in high-throughput scenarios,\ndefault values for the maximum packets size have already been set for both UDS (8192 bytes)\nand UDP (1432 bytes) in order to have the best usage of the underlying network.\nHowever, if you perfectly know your network and you know that a different value for the maximum packets\nsize should be used, you can set it with the parameter `max_buffer_len`. Example:\n\n```python\nfrom datadog import initialize\n\noptions = {\n \"api_key\": \"<YOUR_API_KEY>\",\n \"app_key\": \"<YOUR_APP_KEY>\",\n \"max_buffer_len\": 4096,\n}\n\ninitialize(**options)\n```\n\n## Thread Safety\n\n`DogStatsD` and `ThreadStats` are thread-safe.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "The Datadog Python library",
"version": "0.49.1",
"project_urls": {
"Bug Tracker": "https://github.com/DataDog/datadogpy/issues",
"Documentation": "https://datadogpy.readthedocs.io/en/latest/",
"Source Code": "https://github.com/DataDog/datadogpy"
},
"split_keywords": [
"datadog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b9835e3588a74bde57a6ac0f581cca9536278abd38c081c8601b8183906dd7b",
"md5": "876601dd855fdea8f3909099e68bd48d",
"sha256": "4a56d57490ea699a0dfd9253547485a57b4120e93489defadcf95c66272374d6"
},
"downloads": -1,
"filename": "datadog-0.49.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "876601dd855fdea8f3909099e68bd48d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7",
"size": 116891,
"upload_time": "2024-03-19T15:24:26",
"upload_time_iso_8601": "2024-03-19T15:24:26.289905Z",
"url": "https://files.pythonhosted.org/packages/1b/98/35e3588a74bde57a6ac0f581cca9536278abd38c081c8601b8183906dd7b/datadog-0.49.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "24d4fcf0894ebeac76698076f224e566b65f6be218d673ef4b5570728c5ce157",
"md5": "1b5a5578fcd07bdb521049c6bb8e5172",
"sha256": "4cb7a7991af6cadb868fe450cd456473e65f11fc678b7d7cf61044ff1c6074d8"
},
"downloads": -1,
"filename": "datadog-0.49.1.tar.gz",
"has_sig": false,
"md5_digest": "1b5a5578fcd07bdb521049c6bb8e5172",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7",
"size": 345833,
"upload_time": "2024-03-19T15:24:28",
"upload_time_iso_8601": "2024-03-19T15:24:28.267620Z",
"url": "https://files.pythonhosted.org/packages/24/d4/fcf0894ebeac76698076f224e566b65f6be218d673ef4b5570728c5ce157/datadog-0.49.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-19 15:24:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DataDog",
"github_project": "datadogpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "datadog"
}
