This is the source for an nginx module that adds Datadog distributed tracing to
nginx. The module is called ngx_http_datadog_module
.
This module is not yet considered "generally available" and is being piloted by a small group of users.
It will be expanded to wider use when major version 1
is released sometime
this year.
Download a gzipped tarball from a recent release, extract it to wherever nginx
looks for modules (e.g. /usr/lib/nginx/modules/
) and add the following line
to the top of the main nginx configuration (e.g. /etc/nginx/nginx.conf
):
load_module modules/ngx_http_datadog_module.so;
Tracing is automatically added to all endpoints by default. For more information, see the API documentation.
There is one version of the module for each docker image we follow, which include the following:
- Debian variants of nginx's DockerHub images,
- Alpine variants of nginx's DockerHub images,
- Amazon Linux 2.
Each release contains one zipped tarball per supported image above. The
naming convention is
<base image with underscores><hyphen>ngx_http_datadog_module.so.tgz
,
e.g. nginx_1.23.1-alpine-ngx_http_datadog_module.so.tgz
or
amazonlinux_2.0.20230119.1-ngx_http_datadog_module.so.tgz
.
The zipped tarball contains a single file, ngx_http_datadog_module.so
, which
is the Datadog tracing nginx module.
Unless otherwise configured, ngx_http_datadog_module
adds the following
default tracing behavior to nginx:
- Connect to the Datadog agent at
http://localhost:8126
. - Create one span per request:
- Service name is "nginx".
- Operation name is "nginx.request".
- Resource name is
"$request_method $uri"
, e.g. "GET /api/book/0-345-24223-8/title". - Includes multiple
http.*
tags.
Custom configuration can be specified via the datadog directive in nginx's configuration file, or via environment variables.
Makefile is a GNU make compatible makefile.
Its default target, build
, builds the Datadog nginx module and its
dependencies. The resulting nginx module is
.build/libngx_http_datadog_module.so
.
Another target, build-in-docker
, builds the Datadog nginx module and its
dependencies in a Docker container compatible with the DockerHub image
specified as BASE_IMAGE
in the ./nginx-version-info
file, (e.g.
nginx:1.19.1-alpine
) and with the nginx source version specified as
NGINX_VERSION
in the ./nginx-version-info
file (e.g. 1.19.1
). The
appropriate build image must be created first using the
bin/docker_build.sh script if it does not exist already.
Once the image is built, make build-in-docker
produces the nginx module as
.docker-build/libngx_http_datadog_module.so
.
The C and C++ sources are built using CMake.
The build does the following:
- Download a source release of nginx based on the
NGINX_VERSION
value specified in./nginx-version-info
. - Configure nginx's sources for build (e.g. generates platform-specific headers).
- Initialize the source trees of
opentracing-cpp
anddd-opentracing-cpp
as git submodules. - Install
dd-opentracing-cpp
's dependencies (e.g.libcurl
). - Build
opentracing-cpp
,dd-opentracing-cpp
, and the Datadog nginx module together using CMake.
make clean
deletes CMake's build directory. make clobber
deletes
everything done by the build.
See test/README.md.
This project is based largely on previous work. See CREDITS.md.