简介
OpenResty 是基于 Nginx 的高性能 Web 平台,它通过集成 Lua 脚本引擎和一系列模块,扩展了 Nginx 的功能,使开发者可以使用 Lua 编写复杂的应用逻辑。对 OpenResty 进行链路追踪,能在分布式系统中清晰呈现请求经 Nginx 转发后的完整路径,这不仅让问题定位更高效,可快速锁定延迟、错误等问题发生的具体环节,还能通过追踪其处理请求的耗时、转发延迟等数据,精准识别系统性能瓶颈,为优化资源分配和架构设计提供依据。
观测云
观测云采集器 DataKit 支持 ddtrace 采集插件,能够接收 nginx-datadog 模块的链路数据并在平台统一分析。
部署 DataKit
登录观测云控制台,点击「集成」-「DataKit」-「Linux」,复制安装命令在服务器执行即可。

开启 ddtrace 插件
按照以下步骤操作:
bash
# 进入 ddtrace 采集器配置文件目录
cd /usr/local/datakit/conf.d/ddtrace
# 开启配置文件
cp ddtrace.conf.sample ddtrace.conf
# 重启 Datakit
datakit service -R
配置 Openresty
按照以下步骤操作:
1、访问 github.com/DataDog/ngi... Assets 中寻找并下载与当前处理器架构和版本匹配的模块 openresty-ngx_http_datadog_module-<处理器架构>-<版本>.so.tgz
;
2、执行以下操作创建模块路径,假设 Openresty 安装在默认路径,配置 Openresty:
bash
cd /usr/local/openresty/nginx
mkdir modules && cd $_
3、上传第一步中下载的模块至 modules 目录,执行以下命令解压,解压后将获得 ngx_http_datadog_module.so
文件:
xml
tar xzvf openresty-ngx_http_datadog_module-<处理器架构>-<版本>.so.tgz
4、在配置文件 /usr/local/openresty/nginx/conf/nginx.conf
的最顶部加载模块,以在 HTTP 上下文(上下文概念请参考"配置上下文和配置项" 章节)中进行配置为例,注释中包含详细说明:
ini
# 加载模块
load_module modules/ngx_http_datadog_module.so;
worker_processes 1;
events {
worker_connections 1024;
}
http {
# 配置 Datakit URL
datadog_agent_url http://localhost:9529;
# 配置服务名称
datadog_service_name openresty-demo;
# 配置环境名称
datadog_environment test;
# 配置版本名称
datadog_version 1.0.0;
# 配置采样率 0-1.0
datadog_sample_rate 1.0;
# 配置标签
datadog_tag foo bar;
include mime.types;
default_type application/octet-stream;
# 通过 $datadog_trace_id 和 $datadog_span_id 为日志加入 trace_id 和 span_id,均为 16 进制
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"'
'"$datadog_trace_id" "$datadog_span_id"';
access_log logs/access.log main;
sendfile on;
keepalive_timeout 65;
server {
listen 80;
server_name localhost;
location / {
root html;
index index.html index.htm;
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
}
}
该模块默认开启从请求中提取追踪上下文,默认支持 tracecontext 和 datadog 两种协议,可通过如下配置增加对 b3 协议的支持:
ini
datadog_propagation_styles=tracecontext datadog b3
效果展示

配置上下文和配置项
nginx-datadog 模块将 Openresty 的配置文件划分为如下上下文区域:
bash
# "main" context
# ...
events {
# ...
}
http {
# "http" context
# ...
server {
# "server" context
# ...
listen 80;
location /ping {
# "location" context
# ...
}
location /auth {
if ($request_method = POST) {
# "if" context
# ...
}
# ...
}
}
}
相同配置项可在不同的上下文区域中配置,例如 datadog_service_name 配置支持 http、server、location 三个不同的上下文区域,如果需要为不同的 server 分别配置服务名称,则可以在 server 上下文中分别配置,完整配置列表参考:github.com/DataDog/ngi...
此外,该模块能够支持通过环境变量进行配置,例如为应用增加额外的数据标签,在配置环境变量后启动 Openresty:
ini
export DD_TAGS=layer:proxy,foo:bar
nginx
最终将在数据的 message.meta 中看到定义的标签,可用于配置的环境变量列表参考:docs.datadoghq.com/tracing/tra...
自行编译所需版本的模块
datadog-nginx 是一个较新的模块,Github 中官方预编译的版本支持范围有限,因此可使用容器化构建的方式编译所需版本。执行以下命令构建 Openresty 所需的模块:
bash
mkdir -p $HOME/workspace/nginx-datadog-build && cd $_
git clone https://github.com/DataDog/nginx-datadog.git
cd nginx-datadog/
# 拉取项目中引用的子模块
git submodule update --init --recursive
# 查看最新版本
git tag
# 检出到最新 tag
git checkout v1.6.2
# 确认当前检出的标签
git status
# 根据需求替换 platform、ARCH、RESTY_VERSION、NGINX_VERSION, RESTY_VERSION 中以 . 分隔的前三个值为 NGINX_VERSION
# 以 Openresty 版本 1.27.1.2 为例,构建 amd64 架构的模块
docker run --init --rm \
--platform linux/x86_64 \
--env ARCH=x86_64 \
--env BUILD_TYPE=RelWithDebInfo \
--env RESTY_VERSION=1.27.1.2 \
--env NGINX_VERSION=1.27.1 \
--env WAF=OFF \
--mount type=bind,source=$HOME/workspace/nginx-datadog-build/nginx-datadog,target=/mnt/repo \
public.ecr.aws/b1o7r7e0/nginx_musl_toolchain:latest \
bash -c "cd /mnt/repo && ./bin/openresty/build_openresty.sh && make build-openresty-aux"
# 打包制品
cd $HOME/workspace/nginx-datadog-build/nginx-datadog/.openresty-build
tar czvf openresty-ngx_http_datadog_module-amd64-1.27.1.2.so.tgz ngx_http_datadog_module.so
注意:
- 模块构建成功并不意味在最终集成时不存在兼容性问题,以在引入模块后执行
nginx -t
命令检查的结果为准; - 构建配置遵循 nginx-datadog 项目 Makefile 中的变更。