DataDog/datadog-go
GitHub: DataDog/datadog-go
Datadog 官方的 Go 版 DogStatsD 客户端库，用于在 Go 应用中向 Datadog 平台发送自定义指标、事件和服务检查数据。
Stars: 375 | Forks: 142
[](https://app.circleci.com/pipelines/github/DataDog/datadog-go)
# Datadog Go
[](https://godoc.org/github.com/DataDog/datadog-go/v5/statsd)
[](http://opensource.org/licenses/MIT)
`datadog-go` 是一个提供 Golang 版 [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go) 客户端的库。
官方支持 Go 1.12+。旧版本可能可以使用，但未经过测试。
提供以下文档：
* [Datadog Go GoDoc 文档](http://godoc.org/github.com/DataDog/datadog-go/v5/statsd)
* [Datadog 官方 DogStatsD 文档](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go)。
* [新主要版本](#new-major-version)
* [安装](#installation)
- [支持的環境變數](#supported-environment-variables)
- [Unix Domain Sockets 客户端](#unix-domain-sockets-client)
* [用法](#usage)
- [指标](#metrics)
- [事件](#events)
- [服务检查](#service-checks)
* [客户端聚合](#client-side-aggregation)
- [“基本”聚合](#basic-aggregation)
- [“扩展”聚合](#extended-aggregation)
* [性能 / 指标丢弃](#performance--metric-drops)
- [监控此客户端](#monitoring-this-client)
- [调整内核选项](#tweaking-kernel-options)
+ [Unix Domain Sockets](#unix-domain-sockets)
- [高吞吐量场景下的最大数据包大小](#maximum-packets-size-in-high-throughput-scenarios)
* [开发](#development)
* [许可证](#license)
* [致谢](#credits)
## 新主要版本
新的主要版本 `v5` 现在是默认版本。所有新功能都将添加到此版本中，只有错误修复会被
移植回 `v4`（参见 `v4` 分支）。
与 `v4` 相比，`v5` 引入了一些破坏性更新，请查看
[CHANGELOG](https://github.com/DataDog/datadog-go/blob/master/CHANGELOG.md#500--2021-10-01) 了解更多信息。
请注意，`v5` 和 `v4` 的导入路径不同：
- `v5`: github.com/DataDog/datadog-go/v5/statsd
- `v4`: github.com/DataDog/datadog-go/statsd
迁移到 `v5` 时，您需要更新您的导入。
## 安装
使用以下命令获取代码：
```
$ go get github.com/DataDog/datadog-go/v5/statsd
```
然后创建一个新的 DogStatsD 客户端：
```
package main
import (
"log"
"github.com/DataDog/datadog-go/v5/statsd"
)
func main() {
statsd, err := statsd.New("127.0.0.1:8125")
if err != nil {
log.Fatal(err)
}
}
```
在 [Datadog-go godoc 文档](https://godoc.org/github.com/DataDog/datadog-go/v5/statsd#Option) 或 [Datadog 公共 DogStatsD 文档](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go#client-instantiation-parameters) 中查找您的 DogStatsD 客户端所有可用选项的列表。
### 支持的环境变量
* 如果 `addr` 参数为空，客户端将：
* 首先使用 `DD_DOGSTATSD_URL` 环境变量构建目标地址。这必须是一个以 `udp://`（使用 UDP 连接）或 `unix://`（使用 Unix Domain Socket）开头的 URL。
UDP url 示例：`DD_DOGSTATSD_URL=udp://localhost:8125`
UDS 示例：`DD_DOGSTATSD_URL=unix:///var/run/datadog/dsd.socket`
Windows named pipe 示例：`DD_AGENT_HOST=\\.\pipe\my_windows_pipe`
* 回退到 `DD_AGENT_HOST` 环境变量来构建目标地址。
示例：UDP 使用 `DD_AGENT_HOST=127.0.0.1:8125`，UDS 使用 `DD_AGENT_HOST=unix:///path/to/socket`，Windows named pipe 使用 `DD_AGENT_HOST=\\.\pipe\my_windows_pipe`。
* 如果 `DD_AGENT_HOST` 没有端口，它会将端口默认设置为 `8125`
* 如果 `DD_AGENT_HOST` 没有为 UDP 设置端口，您可以使用 `DD_AGENT_PORT` 来设置端口
示例：`DD_AGENT_HOST=127.0.0.1` 和 `DD_AGENT_PORT=1234` 将创建一个到 `127.0.0.1:1234` 的 UDP 连接。
* 如果找到了 `DD_ENTITY_ID` 环境变量，它的值将被作为全局 `dd.internal.entity_id` 标签注入。Datadog Agent 使用此标签将容器标签插入到指标中。
要启用源头检测并设置 `DD_ENTITY_ID` 环境变量，请将以下行添加到您的应用程序清单中：
```
env:
- name: DD_ENTITY_ID
valueFrom:
fieldRef:
fieldPath: metadata.uid
```
* statsd 客户端可以使用 `DD_ENV`、`DD_SERVICE` 和 `DD_VERSION` 将 `{env, service, version}` 设置为所有发送数据的全局标签。
### Unix Domain Sockets 客户端
Agent v6+ 通过 Unix Socket 数据报连接接受数据包。有关使用 UDS 相对于 UDP 的优势的详细信息，请参见 [DogStatsD Unix Socket 文档](https://docs.datadoghq.com/developers/dogstatsd/unix_socket/)。您可以通过向 `New` 构造函数提供 `unix:///path/to/dsd.socket` 地址参数来使用此协议。
## 用法
为了使用 DogStatsD 指标、事件和服务检查，Agent 必须[正在运行且可用](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=go)。
### 指标
创建客户端后，您可以开始向 Datadog 发送自定义指标。请参阅专门的[指标提交：DogStatsD 文档](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go)，了解如何通过有效的代码示例向 Datadog 提交所有支持的指标类型：
* [提交 COUNT 指标](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#count)。
* [提交 GAUGE 指标](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#gauge)。
* [提交 SET 指标](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#set)
* [提交 HISTOGRAM 指标](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#histogram)
* [提交 DISTRIBUTION 指标](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#distribution)
指标名称只能包含 ASCII 字母数字字符、下划线和句点。客户端不会替换或检查无效字符。
提交指标时支持一些选项，例如[将采样率应用于您的指标](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#metric-submission-options)或[使用您的自定义标签为指标打标签](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=go#metric-tagging)。在 [Datadog Go 客户端 GoDoc 文档](https://godoc.org/github.com/DataDog/datadog-go/v5/statsd#Client) 中查找报告指标的所有可用函数。
### 事件
创建客户端后，您可以开始向您的 Datadog 事件流发送事件。请参阅专门的[事件提交：DogStatsD 文档](https://docs.datadoghq.com/developers/events/dogstatsd/?code-lang=go)，了解如何向您的 Datadog 事件流提交事件。
### 服务检查
创建客户端后，您可以开始向 Datadog 发送服务检查。请参阅专门的[服务检查提交：DogStatsD 文档](https://docs.datadoghq.com/developers/service_checks/dogstatsd_service_checks_submission/?code-lang=go)，了解如何向 Datadog 提交服务检查。
## 客户端聚合
从版本 `5.0.0`（以及 `3.6.0` 测试版）开始，客户端提供客户端端的聚合或数值打包功能。
此功能旨在减少在极高吞吐量场景下发送到 Agent 的数据包数量和数据包丢弃。
聚合窗口默认为 2 秒，可以通过 `WithAggregationInterval()` 选项进行更改。请注意，
Agent 端 DogStatsD 指标的聚合窗口为 10 秒。因此，例如，在客户端设置 3 秒的聚合窗口将
导致您的仪表板每 30 秒在计数指标上出现一次峰值（因为 Agent 上的第三个 10 秒桶将接收到
来自客户端的 4 个样本）。
可以使用 `WithoutClientSideAggregation()` 选项禁用聚合。
telemetry `datadog.dogstatsd.client.metrics` 保持不变，表示聚合前的指标数量。
引入了新指标 `datadog.dogstatsd.client.aggregated_context` 和
`datadog.dogstatsd.client.aggregated_context_by_type`。请参见[监控此客户端](#monitoring-this-client)部分。
### “基本”聚合
默认情况下启用，客户端将聚合 `gauge`、`count` 和 `set`。
可以使用 `WithoutClientSideAggregation()` 选项禁用此功能。
### “扩展”聚合
此功能仅与 Agent 版本 >=6.25.0 && <7.0.0 或 Agent 版本 >=7.25.0 兼容。
默认情况下禁用，客户端也可以在一条消息中打包 `histogram`、`distribution` 和 `timing` 的多个
值。对于这些类型，无法进行真正的聚合，因为 Agent 也会进行聚合，而两个级别的聚合将改变发送到 Datadog 的最终值。
启用此选项后，Agent 将按指标名称和标签的组合缓冲指标，并以最少数量的消息发送它们。
例如，如果我们对同一指标进行 3 次采样。客户端将不再通过网络发送：
```
my_distribution_metric:21|d|#all,my,tags
my_distribution_metric:43.2|d|#all,my,tags
my_distribution_metric:1657|d|#all,my,tags
```
而是只发送一条消息：
```
my_distribution_metric:21:43.2:1657|d|#all,my,tags
```
这将大大减少网络使用量和数据包丢弃，但会略微增加客户端的内存和 CPU 使用率。查看 telemetry 指标
`datadog.dogstatsd.client.metrics_by_type` / `datadog.dogstatsd.client.aggregated_context_by_type`
将显示每种类型的聚合率。这是一个了解扩展聚合对您的应用程序有多大用处的有趣数据。
可以使用 `WithExtendedClientSideAggregation()` 选项启用此功能。
### 每个上下文的最大样本数
此功能最好与之前的聚合机制结合使用。它允许限制 `histogram`、`distribution` 和 `timing`
指标每个上下文的样本数量。
可以使用 `WithMaxSamplesPerContext(n int)` 选项启用此功能。启用后，每个上下文最多将保留 `n` 个
样本。默认值为 0，表示没有限制。
样本的选择使用了一种算法，该算法试图使保留样本随时间的分布保持均匀。
## 性能 / 指标丢弃
### 监控此客户端
此客户端会自动在 DogStatsD 流中注入有关自身的 telemetry。
这些指标不会被视为自定义指标，也不会被计费。可以使用 `WithoutTelemetry` 选项禁用此功能。
请参阅 [Telemetry 文档](https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?code-lang=go#client-side-telemetry) 以了解更多信息。
### 调整内核选项
在极高的吞吐量环境中，可以通过更改某些内核选项的值来提高性能。
#### Unix Domain Sockets
- `sysctl -w net.unix.max_dgram_qlen=X` - 将数据报队列大小设置为 X（默认值通常为 10）。
- `sysctl -w net.core.wmem_max=X` - 设置所有主机 socket 的发送缓冲区的最大值。
### 高吞吐量场景下的最大数据包大小
为了在高吞吐量场景下最有效地使用此库，
最大数据包大小的默认值已经过设置，以实现对底层网络的最佳
利用。
但是，如果您完全了解您的网络，并且知道应该使用不同的最大数据包
大小值，您可以使用 `WithMaxBytesPerPayload` 选项进行设置。示例：
```
package main
import (
"log"
"github.com/DataDog/datadog-go/v5/statsd"
)
func main() {
statsd, err := statsd.New("127.0.0.1:8125", WithMaxBytesPerPayload(4096))
if err != nil {
log.Fatal(err)
}
}
```
## ClientInterfaceEx
对库的[近期更新](https://github.com/DataDog/datadog-go/pull/327)更改了
接口，向指标函数添加了一个额外的可变参数。这是一个破坏性更新，
但我们认为它不足以成为发布该库新主要版本的理由。作为
一项临时措施，引入了一个名为 `ClientInterfaceEx` 的新接口，其中包含带
有额外参数的 telemetry 函数。
如果您需要在创建指标时指定 Cardinality 覆盖，您将需要通过
此接口来执行此操作。可以通过调用 `NewEx` 来访问它。
```
package main
import (
"log"
"github.com/DataDog/datadog-go/v5/statsd"
)
func main() {
statsd, err := statsd.NewEx("127.0.0.1:8125", WithCardinality(CardinalityHigh))
if err != nil {
log.Fatal(err)
}
statsd.Gauge("gauge", 32, []string{"environment:dev"}, CardinalityLow)
}
```
随着该库的下一个主要版本的发布，`ClientInterfaceEx` 将被弃用，
相关更改将被合并到 `ClientInterface` 接口中。
## 开发
使用以下命令运行测试：
```
$ go test
```
## 许可证
datadog-go 是在 [MIT license](http://www.opensource.org/licenses/mit-license.php) 下发布的。
## 致谢
原始代码由 [ooyala](https://github.com/ooyala/go-dogstatsd) 提供。
标签：API集成, Datadog, DogStatsD, EVTX分析, Go, Retryablehttp, Ruby工具, 可观测性, 客户端库, 日志审计, 监控