APISIX-Datadog 插件发布,助力用户提高系统的可观测性

Bisakh Mondal

更新时间 11/12/2021

APISIX-Datadog 插件封面图

随着应用开发的复杂度增加,监控成为了应用的一个重要组成部分。及时、准确的监控既能满足快速迭代的周期性需求,又能够确保应用的稳定性和流畅性。如何选择一个适合的监控,以提升应用的可观测性,成为了每个开发者都必须面临的一道难题。

Apache APISIX 将监控和可观测性从应用中解耦了出来,给开发人员带来了一个优势:在构建应用的时候,只需要关注业务逻辑,而 Apache APISIX 可以和开发人员选定的监控平台对接,处理可观测性的问题。

Apache APISIX 最近发布了一个新的插件:APISIX-Datadog,以提供与 Datadog 监控平台的集成。这篇文章介绍了 APISIX-Datadog 插件的实现原理及功能。

APISIX-Datadog plugin 工作原理

APISIX-Datadog 插件架构图

APISIX-Datadog 插件将其自定义指标推送到 DogStatsD server。而 DogStatsD server 通过 UDP 连接与 Datadog agent 捆绑在一起。DogStatsD 是 StatsD 协议的一个实现。它为 Apache APISIX agent 收集自定义指标,将其聚合成一个数据点,并将其发送到配置的 Datadog server。要了解更多关于 DogStatsD 的信息,请访问 DogStatsD 文档。

当你启用 APISIX-Datadog 插件时,Apache APISIX agent 会在每个请求响应周期向 DogStatsD server 输出以下指标:

参数名称StatsD 类型描述
Request CounterCounter收到的请求数量。
Request LatencyHistogram处理该请求所需的时间,以毫秒为单位。
Upstream latencyHistogram上游 server agent 请求到收到响应所需的时间,以毫秒为单位。
APISIX LatencyHistogramAPISIX agent 处理该请求的时间,以毫秒为单位。
Ingress SizeTimer请求体大小,以字节为单位。
Egress SizeTimer响应体大小,以字节为单位。

这些指标将被发送到 DogStatsD agent,并带有以下标签。如果任何特定的标签没有合适的值,该标签将被直接省略。

参数名称描述
route_name路由的名称,如果不存在,将显示路由 ID。
service_id如果一个路由是用服务的抽象概念创建的,那么特定的服务 ID 将被使用。
consumer如果路由有一个链接的消费者,消费者的用户名将被添加为一个标签。
balancer_ip处理了当前请求的上游复制均衡器的的 IP。
response_statusHTTP 响应状态代码。
scheme已用于提出请求的协议,如 HTTP、gRPC、gRPCs 等。

APISIX-Datadog 插件维护了一个带有 timer 的 buffer。当 timer 失效时,APISIX-Datadog 插件会将 buffer 的指标作为一个批量处理程序传送给本地运行的 DogStatsD server。这种方法通过重复使用相同的 UDP 套接字,对资源的占用较少,而且由于可以配置 timer,所以不会一直让网络过载。

启动 Datadog Agent

  1. 如果你已经在使用 Datadog,你必须在系统中安装一个 Datadog agent。它可以是一个 docker 容器,一个 pod 或二进制的包管理器。你只需要确保Apache APISIX agent 可以到达 Datadog agent 的 8125 端口。

    如果需要了解更多关于如何安装一个完整的 Datadog agent,请访问这里

  2. 如果你从没使用过 Datadog

    1. 首先访问 www.datadoghq.com ,创建一个账户。
    2. 然后按照下图标注的步骤生成 API 密钥。

    Generate an API Key

  3. APISIX-Datadog 插件只需要依赖 datadog/agent 的 dogstatsd 组件即可实现,因为该插件按照 statsd 协议通过标准的 UDP 套接字向 DogStatsD server 异步发送参数。我们推荐使用独立的 datadog/dogstatsd 镜像,而不是使用完整的datadog/agent ,因为 datadog/dogstatsd 的组件大小只有大约 11 MB,更加轻量化。而完整的 datadog/agent 镜像的大小为 2.8 GB。

运行以下命令,将它作为一个容器来运行:

1# pull the latest image
2docker pull datadog/dogstatsd:latest
3# run a detached container
4docker run -d --name dogstatsd-agent -e DD_API_KEY=<Your API Key from step 2> -p 8125:8125/udp datadog/dogstatsd

如果你在生产环境中使用 Kubernetes,你可以将 dogstatsd 作为一个 DaemonsetMulti-Container Pod 与 Apache APISIX agent 一起部署。

如何在 Apache APISIX 中使用 Datadog

启用 APISIX-Datadog 插件

如果你已经启动了 dogstatsd agent,只需执行一条命令,就可以为指定路由启用 APISIX-Datadog 插件。

1# enable plugin for a specific route
2curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
3{
4    "plugins": {
5        "datadog": {}
6    },
7    "upstream": {
8        "type": "roundrobin",
9        "nodes": {
10            "127.0.0.1:1980": 1
11        }
12    },
13    "uri": "/hello"
14}'

启用 APISIX-Datadog 插件后,任何对端点 URI /hello 的请求都会产生上述指标,并推送到 Datadog agent的本地 DogStatsD server。

自定义配置

如果启用 APISIX-Datadog 插件时,使用的是默认配置,dogstatsd 服务在 127.0.0.1:8125 可用。如果你想更新配置,请更新插件的元数据。

元数据参数解释

参数名称类型是否必须修改默认值描述
hostsstring"127.0.0.1"DogStatsD server 的主机地址
portinteger8125DogStatsD server的主机端口
namespacestring"apisix"由 APISIX agent发送的所有自定义参数的前缀。对寻找指标图的实体很有帮助,例如:(apisix.request.counter)。
constant_tagsarray["source:apisix"]静态标签嵌入到生成的指标中。对某些信号的 metrics 进行分组很有用。

要了解更多关于如何有效地编写标签,请访问这里

向 /apisix/admin/plugin_metadata 端点发出请求,更新元数据,如下所示。

1curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/datadog -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
2{
3    "host": "127.0.0.1",
4    "port": 8125,
5    "constant_tags": [
6        "source:apisix",
7        "service:custom"
8    ],
9    "namespace": "apisix"
10}'

插件参数解释

与元数据类似,在启用 APISIX-Datadog 插件时,你也可以调整其他参数。

|参数名称|类型|是否必须修改|默认值|取值范围||描述| |----|----|--------|-------|-----|-----------| |batch_max_size|integer|否|5000|[1,...]|每个批次的 buffer 最大值| |inactive_timeout|integer|否|5|[1,...]|如果不活跃,buffer 将被刷新的最长时间(秒)。| |buffer_duration|integer|否|60|[1,...]|在必须处理一个批次之前,该批次中最老的条目的最长存活时间(秒)。| |max_retry_count|integer|否|1|[1,...]|如果一个条目未能到达 dogstatsd server,重试的次数。|

由于所有的字段都是可选的,如果你没有手动设置任何参数,APISIX-Datadog 插件将使用默认值设置这些参数。如果你需要更新任何参数,只需用更新的参数值更新所需的路由、服务或消费者。例如,下面的代码将 batch_max_size 修改为 10。

1'{
2...
3"plugins": {
4    "datadog": {
5        "batch_max_size": 10
6    }
7}
8... }'

停用 APISIX-Datadog 插件

你只需在插件配置中删除相应的 json 配置即可停用 APISIX-Datadog 插件。得益于 Apache APISIX 插件的热加载机制,删除 json 配置后,会立即停用APISIX-Datadog 插件,不需要重新加载。

1# disable plugin for a route
2curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
3{
4    "uri": "/hello",
5    "plugins": {},
6    "upstream": {
7        "type": "roundrobin",
8        "nodes": {
9            "127.0.0.1:1980": 1
10        }
11    }
12}'