This is the source for an nginx module that adds Datadog distributed tracing to
nginx. The module is called ngx_http_datadog_module
.
- Download a gzipped tarball from a recent release, extract it to wherever nginx
looks for modules (e.g.
/usr/lib/nginx/modules/
). - 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.
Important
We provide support for NGINX versions up to their End Of Life, extended by one year. Aligned with the NGINX release cycle, this entails support for the four most recent NGINX versions.
If you plan to add tracing features to an older NGINX version using our module, please check out the build section for guidance.
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.
Each release contains one zipped tarball per supported image above.
The zipped tarball contains a single file, ngx_http_datadog_module.so
, which is the Datadog tracing nginx module.
The naming convention is <base image with underscores>-<arch>-ngx_http_datadog_module.so.tgz
.
Supported architectures (<arch>
) are amd64
and arm64
.
Examples:
nginx_1.23.1-alpine-amd64-ngx_http_datadog_module.so.tgz
corresponds to NGINX version 1.23.1 docker image, running on Alpine, and designed for the amd64 architecture.amazonlinux_2.0.20230119.1-arm64-ngx_http_datadog_module.so.tgz
refers to Amazon Linux version 2.0.20230119.1 docker image, designed for the arm64 architecture.
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_* family of directives in nginx's configuration file, or via environment variables.
Requirements:
- C and C++ toolchain (
clang
orgcc/g++
). - CMake
v3.7
or newer. - Architecture must be
x86_64
orarm64
.
For enhanced usability, we provide a GNU make compatible Makefile.
NGINX_VERSION=1.25.2 make build
The resulting nginx module is .build/ngx_http_datadog_module.so
The build
target does the following:
- Download a source release of nginx based on the
NGINX_VERSION
environment variable. - Initialize the source tree of
dd-trace-cpp
as a git submodule. - Build
dd-trace-cpp
and the Datadog nginx module together using CMake.
make clean
deletes CMake's build directory. make clobber
deletes
everything done by the build.
make build-in-docker
build-in-docker
target, 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/ngx_http_datadog_module.so
.
See test/README.md.
This project is based largely on previous work. See CREDITS.md.