Datadog Nginx Module

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.

Usage

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 Configuration documentation.

Compatibility

[!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 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;
• ngx_http_datadog_module-appsec-<arch>-<version>.so.tgz for builds with appsec support.

[!IMPORTANT] The AppSec variants require Nginx to have been built with --threads (thread support).

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

While it may be possible to build the extension against an older version, this is not guaranteed; in particular, AppSec builds require a feature introduced in version 1.21.4.

Default Behavior

Unless otherwise configured, ngx_http_datadog_module adds the following default behavior to Nginx:

Tracing

• 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.

Enabling AppSec

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 on;.
• 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 Configuration documentation.

Building the Module

If the version of Nginx you’re using is no longer supported by this repository, you can build the module by following the steps below.

This repository uses git submodules for some of its dependencies. To ensure all dependencies are available or updated before building, run the following command:

git submodule update --init --recursive

Prerequisites

Before building the module, ensure your environment meets the following requirements:

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

Building Using Docker

We recommend using Docker which greatly simplify the build process for various environments. Below are specific commands and options for different build targets.

[!IMPORTANT] Be sure to match the version of Nginx, OpenResty, or Ingress Nginx with the version you are using in your environment to avoid compatibility issues.

Building for Nginx

[!NOTE] The build-musl target builds against musl to guarantee portability.

WAF=ON ARCH=x86_64 NGINX_VERSION=1.29.7 make build-musl

Options:

• WAF=<ON|OFF>: Enable (ON) or disable (OFF) AppSec.
• ARCH=<x86_64|aarch64>: Specify the CPU architecture.
• NGINX_VERSION=<version>: Specify the Nginx version to build.
• ASAN=<ON|OFF>: Whether to enable ASAN/UBSan

The Nginx module will be generated at .musl-build\ngx_http_datadog_module.so.

Building for OpenResty Using Docker

[!NOTE] The build-openresty target builds against musl to guarantee portability.

To build the module for OpenResty:

WAF=ON ARCH=x86_64 RESTY_VERSION=1.29.2.1 make build-openresty

Options:

• WAF=<ON|OFF>: Enable (ON) or disable (OFF) AppSec.
• ARCH=<x86_64|aarch64>: Specify the CPU architecture.
• RESTY_VERSION=<version>: Specify the OpenResty version to build.

The Nginx module will be generated at .musl-build\ngx_http_datadog_module.so.

Building for Ingress Nginx using Docker

[!NOTE] The build-ingress-nginx target builds against musl to guarantee portability.

To build the module for Ingress Nginx:

WAF=ON ARCH=x86_64 INGRESS_NGINX_VERSION=1.15.1 make build-ingress-nginx

Options:

• WAF=<ON|OFF>: Enable (ON) or disable (OFF) AppSec.
• ARCH=<x86_64|aarch64>: Specify the CPU architecture.
• INGRESS_NGINX_VERSION=<version>: Specify the version Ingress Nginx to build.

The Nginx module will be generated at .musl-build\ngx_http_datadog_module.so.

Running tests

Prerequisites:

• Docker and Docker Compose v2
• uv installed

Option A: one-shot build + test (use on a clean tree)

• NGINX_VERSION=1.31.1 TOOLCHAIN_DEPENDENCY= TEST_DEPENDENCY= make build-and-test
  • WAF=ON to include AppSec tests
  • To use a different base image (non-ASAN), set BASE_IMAGE, e.g. BASE_IMAGE=nginx:1.28.4-alpine
• ASAN mode:
  • ASAN=ON ARCH=x86_64 NGINX_VERSION=1.31.1 TOOLCHAIN_DEPENDENCY= TEST_DEPENDENCY= make build-and-test
  • BASE_IMAGE/--image are ignored in ASAN mode (runner builds its own ASAN base)

Option B: iterate quickly after the first build (avoid rebuilds)

• Build once:
  • NGINX_VERSION=1.31.1 TOOLCHAIN_DEPENDENCY= make build-musl
• Run all tests without rebuilding images:
  • TEST_DEPENDENCY= make test
• Run a specific test:
  • TEST_ARGS="cases.path.to.module.TestClass.test_method" TEST_DEPENDENCY= make test
  • Example: TEST_ARGS="--failfast cases.auth_requests.test_auth_requests.TestAuthRequests.test_auth_request_with_auth_token_is_successful" TEST_DEPENDENCY= make test
• ASAN iteration:
  • Build with ASAN: ASAN=ON ARCH=x86_64 NGINX_VERSION=1.31.1 TOOLCHAIN_DEPENDENCY= make build-musl
  • Test with ASAN flags: ASAN=ON ARCH=x86_64 TEST_DEPENDENCY= make test

See test/README.md and test/cases/README.md for details and advanced usage.

Security

If you discover a security vulnerablity in this softwa Datadog Nginx module, please refer to the Security Policy.

Acknowledgements

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