{"id":19054242,"url":"https://github.com/datadog/datadog-go","last_synced_at":"2025-05-13T18:10:56.565Z","repository":{"id":19604196,"uuid":"22855120","full_name":"DataDog/datadog-go","owner":"DataDog","description":"go dogstatsd client library for datadog","archived":false,"fork":false,"pushed_at":"2025-05-11T15:18:54.000Z","size":641,"stargazers_count":360,"open_issues_count":36,"forks_count":137,"subscribers_count":141,"default_branch":"master","last_synced_at":"2025-05-11T16:28:41.959Z","etag":null,"topics":["datadog","dogstatsd","go","statsd"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-08-11T21:13:59.000Z","updated_at":"2025-04-25T06:31:17.000Z","dependencies_parsed_at":"2023-10-16T18:45:11.857Z","dependency_job_id":"41c4b7fe-b1f3-4adc-89ae-56763930f6c3","html_url":"https://github.com/DataDog/datadog-go","commit_stats":{"total_commits":326,"total_committers":77,"mean_commits":4.233766233766234,"dds":0.7300613496932515,"last_synced_commit":"20af2dbfabbbe6bd0347780cd57ed931f903f223"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fdatadog-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fdatadog-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fdatadog-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fdatadog-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/datadog-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000854,"owners_count":21997442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datadog","dogstatsd","go","statsd"],"created_at":"2024-11-08T23:37:24.278Z","updated_at":"2025-05-13T18:10:56.537Z","avatar_url":"https://github.com/DataDog.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://circleci.com/gh/DataDog/datadog-go.svg?style=svg)](https://app.circleci.com/pipelines/github/DataDog/datadog-go)\n\n# Datadog Go\n\n[![Godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/DataDog/datadog-go/v5/statsd)\n[![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](http://opensource.org/licenses/MIT)\n\n`datadog-go` is a library that provides a [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go) client in Golang.\n\nGo 1.12+ is officially supported. Older versions might work but are not tested.\n\nThe following documentation is available:\n\n* [GoDoc documentation for Datadog Go](http://godoc.org/github.com/DataDog/datadog-go/v5/statsd)\n* [Official Datadog DogStatsD documentation](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go).\n\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [New major version](#new-major-version)\n* [Installation](#installation)\n    - [Supported environment variables](#supported-environment-variables)\n    - [Unix Domain Sockets Client](#unix-domain-sockets-client)\n* [Usage](#usage)\n    - [Metrics](#metrics)\n    - [Events](#events)\n    - [Service Checks](#service-checks)\n* [Client side aggregation](#client-side-aggregation)\n    - [\"Basic\" aggregation](#basic-aggregation)\n    - [\"Extended\" aggregation](#extended-aggregation)\n* [Performance / Metric drops](#performance--metric-drops)\n    - [Monitoring this client](#monitoring-this-client)\n    - [Tweaking kernel options](#tweaking-kernel-options)\n        + [Unix Domain Sockets](#unix-domain-sockets)\n    - [Maximum packets size in high-throughput scenarios](#maximum-packets-size-in-high-throughput-scenarios)\n* [Development](#development)\n* [License](#license)\n* [Credits](#credits)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n\n## New major version\n\nThe new major version `v5` is now the default. All new features will be added to this version and only bugfixes will be\nbackported to `v4` (see `v4` branch).\n\n`v5` introduce a number of breaking changes compare to `v4`, see the\n[CHANGELOG](https://github.com/DataDog/datadog-go/blob/master/CHANGELOG.md#500--2021-10-01) for more information.\n\nNote that the import paths for `v5` and `v4` are different:\n- `v5`: github.com/DataDog/datadog-go/v5/statsd\n- `v4`: github.com/DataDog/datadog-go/statsd\n\nWhen migrating to the `v5` you will need to upgrade your imports.\n\n## Installation\n\nGet the code with:\n\n```shell\n$ go get github.com/DataDog/datadog-go/v5/statsd\n```\n\nThen create a new DogStatsD client:\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"github.com/DataDog/datadog-go/v5/statsd\"\n)\n\nfunc main() {\n    statsd, err := statsd.New(\"127.0.0.1:8125\")\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\nFind a list of all the available options for your DogStatsD Client in the [Datadog-go godoc documentation](https://godoc.org/github.com/DataDog/datadog-go/v5/statsd#Option) or in [Datadog public DogStatsD documentation](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go#client-instantiation-parameters).\n\n### Supported environment variables\n\n* If the `addr` parameter is empty, the client will:\n  * First use the `DD_DOGSTATSD_URL` environment variables to build a target address. This must be a URL that start with either `udp://` (to connect using UDP) or with `unix://` (to use a Unix Domain Socket).\n    Example for UDP url: `DD_DOGSTATSD_URL=udp://localhost:8125`\n    Example for UDS: `DD_DOGSTATSD_URL=unix:///var/run/datadog/dsd.socket`\n    Example for Windows named pipe`DD_AGENT_HOST=\\\\.\\pipe\\my_windows_pipe`\n  * Fallback to the `DD_AGENT_HOST` environment variables to build a target address.\n    Example: `DD_AGENT_HOST=127.0.0.1:8125` for UDP, `DD_AGENT_HOST=unix:///path/to/socket` for UDS and `DD_AGENT_HOST=\\\\.\\pipe\\my_windows_pipe` for Windows named pipe.\n    * If `DD_AGENT_HOST` has no port it will default the port to `8125`\n    * You can use `DD_AGENT_PORT` to set the port if `DD_AGENT_HOST` does not have a port set for UDP\n      Example: `DD_AGENT_HOST=127.0.0.1` and `DD_AGENT_PORT=1234` will create a UDP connection to `127.0.0.1:1234`. \n* If the `DD_ENTITY_ID` environment variable is found, its value is injected as a global `dd.internal.entity_id` tag. The Datadog Agent uses this tag to insert container tags into the metrics.\n\nTo enable origin detection and set the `DD_ENTITY_ID` environment variable, add the following lines to your application manifest:\n\n```yaml\nenv:\n  - name: DD_ENTITY_ID\n    valueFrom:\n      fieldRef:\n        fieldPath: metadata.uid\n```\n\n* `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` can be used by the statsd client to set `{env, service, version}` as global tags for all data emitted.\n\n### Unix Domain Sockets Client\n\nAgent v6+ accepts packets through a Unix Socket datagram connection. Details about the advantages of using UDS over UDP are available in the [DogStatsD Unix Socket documentation](https://docs.datadoghq.com/developers/dogstatsd/unix_socket/). You can use this protocol by giving a `unix:///path/to/dsd.socket` address argument to the `New` constructor.\n\n## Usage\n\nIn order to use DogStatsD metrics, events, and Service Checks, the Agent must be [running and available](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go).\n\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=go) 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=go#count).\n* [Submit a GAUGE metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#gauge).\n* [Submit a SET metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#set)\n* [Submit a HISTOGRAM metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#histogram)\n* [Submit a DISTRIBUTION metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#distribution)\n\nMetric names must only contain ASCII alphanumerics, underscores, and periods. The client will not replace nor check for invalid characters.\n\nSome options are suppported when submitting metrics, like [applying a sample rate to your metrics](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#metric-submission-options) or [tagging your metrics with your custom tags](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#metric-tagging). Find all the available functions to report metrics [in the Datadog Go client GoDoc documentation](https://godoc.org/github.com/DataDog/datadog-go/v5/statsd#Client).\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/developers/events/dogstatsd/?code-lang=go) 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=go) to see how to submit a Service Check to Datadog.\n\n## Client side aggregation\n\nStarting with version `5.0.0` (and `3.6.0` in beta), the client offers aggregation or value packing on the client side.\n\nThis feature aims at reducing both the number of packets sent to the Agent and the packet drops in very high throughput\nscenarios.\n\nThe aggregation window is 2s by default and can be changed through `WithAggregationInterval()` option. Note that the\naggregation window on the Agent side is 10s for DogStatsD metrics. So for example, setting an aggregation window of 3s in\nthe client will produce a spike in your dashboard every 30 second for counts metrics (as the third 10s bucket on the\nAgent will receive 4 samples from the client).\n\nAggregation can be disabled using the `WithoutClientSideAggregation()` option.\n\nThe telemetry `datadog.dogstatsd.client.metrics` is unchanged and represents the number of metrics before aggregation.\nNew metrics `datadog.dogstatsd.client.aggregated_context` and `datadog.dogstatsd.client.aggregated_context_by_type` have\nbeen introduced. See the [Monitoring this client](#monitoring-this-client) section.\n\n### \"Basic\" aggregation\n\nEnabled by default, the client will aggregate `gauge`, `count` and `set`.\n\nThis can be disabled with the `WithoutClientSideAggregation()` option.\n\n### \"Extended\" aggregation\n\nThis feature is only compatible with Agent's version \u003e=6.25.0 \u0026\u0026 \u003c7.0.0 or Agent's versions \u003e=7.25.0.\n\nDisabled by default, the client can also pack multiple values for `histogram`, `distribution` and `timing` in one\nmessage. Real aggregation is not possible for those types since the Agent also aggregates and two aggregation levels\nwould change the final value sent to Datadog.\n\nWhen this option is enabled, the agent will buffer the metrics by combination of metric name and tags, and send them in the fewest number of messages.\n\nFor example, if we sample 3 times the same metric. Instead of sending on the network:\n\n```\nmy_distribution_metric:21|d|#all,my,tags\nmy_distribution_metric:43.2|d|#all,my,tags\nmy_distribution_metric:1657|d|#all,my,tags\n```\n\nThe client will send only one message:\n\n```\nmy_distribution_metric:21:43.2:1657|d|#all,my,tags\n```\n\nThis will greatly reduce network usage and packet drops but will slightly increase the memory and CPU usage of the\nclient. Looking at the telemetry metrics `datadog.dogstatsd.client.metrics_by_type` /\n`datadog.dogstatsd.client.aggregated_context_by_type` will show the aggregation ratio for each type. This is an\ninteresting data to know how useful extended aggregation is to your app.\n\nThis can be enabled with the `WithExtendedClientSideAggregation()` option.\n\n### Maximum samples per context\n\nThis feature is best coupled with the previous aggregation mechanism. It allows to limit the number of samples per\ncontext for `histogram`, `distribution` and `timing` metrics.\n\nThis can be enabled with the `WithMaxSamplesPerContext(n int)` option. When enabled up to `n` samples will be kept in\nper context. The default value is 0 which means no limit.\n\nThe selection of the samples is using an algorithm that tries to keep the distribution of kept sample over time uniform.\n\n## Performance / Metric drops\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 `WithoutTelemetry` option.\n\nSee [Telemetry documentation](https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?code-lang=go#client-side-telemetry) to learn more about it.\n\n### Tweaking kernel options\n\nIn very high throughput environments it is possible to improve performance by changing the values of some kernel options.\n\n#### Unix Domain Sockets\n\n- `sysctl -w net.unix.max_dgram_qlen=X` - Set datagram queue size to X (default value is usually 10).\n- `sysctl -w net.core.wmem_max=X` - Set the max size of the send buffer for all the host sockets.\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 to have the best\nusage 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 option `WithMaxBytesPerPayload`. Example:\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"github.com/DataDog/datadog-go/v5/statsd\"\n)\n\nfunc main() {\n    statsd, err := statsd.New(\"127.0.0.1:8125\", WithMaxBytesPerPayload(4096))\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n## Development\n\nRun the tests with:\n\n    $ go test\n\n## License\n\ndatadog-go is released under the [MIT license](http://www.opensource.org/licenses/mit-license.php).\n\n## Credits\n\nOriginal code by [ooyala](https://github.com/ooyala/go-dogstatsd).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fdatadog-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadog%2Fdatadog-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fdatadog-go/lists"}