This repository contains the source code for the ngx_http_datadog_module, an NGINX module that integrates Datadog APM and Application Security Management into NGINX.

1. Download a gzipped tarball from a recent release, extract it to wherever nginx looks for modules (e.g. /usr/lib/nginx/modules/).
2. 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 are two tarballs (the actual executable module and, separately, the debug symbols) per each combination of: 1) nginx version, 2) architecture, 3) whether AppSec is built in or not. The main tarball contains a single file, ngx_http_datadog_module.so, which is the Datadog nginx module.

The naming convention is:

• ngx_http_datadog_module-<arch>-<version>.so.tgz for builds without appsec support and
• ngx_http_datadog_module-appsec-<arch>-<version>.so.tgz for builds with appsec support.

Supported architectures (<arch>) are amd64 and arm64.

Unless otherwise configured, ngx_http_datadog_module adds the following default 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.

To enable AppSec, besides using the correct binary (the relase artifact with "-appsec") in the name, it's necessary to edit the nginx configuration:

• Set datadog_appsec_enabled yes;.
• Define one (or more thread pools).
• Choose which thread pool AppSec will use, either on a global or a per-location basis.

For more information, see the documentation.

Requirements:

• Recent C and C++ toolchain (clang or gcc/g++) (must support at least some C++20 features).
• CMake v3.24 or newer.
• Architecture must be x86_64 or arm64.

For enhanced usability, we provide a GNU make compatible Makefile.

NGINX_VERSION=1.25.2 make build

You can set the environment variable WAF to ON to build an AppSec-supporting module:

WAF=ON 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-musl

The build-musl target builds against musl and libc++ a glibc-compatible module. The Dockerfile for the docker image used in the process can be found in build_env/Dockerfile.

See test/README.md.

This project is based largely on previous work. See CREDITS.md.