{"id":19054272,"url":"https://github.com/datadog/nginx-datadog","last_synced_at":"2026-02-06T20:08:11.496Z","repository":{"id":41040771,"uuid":"388222833","full_name":"DataDog/nginx-datadog","owner":"DataDog","description":"Enhance NGINX Observability and Security with Datadog's Module","archived":false,"fork":false,"pushed_at":"2025-07-08T11:26:48.000Z","size":5477,"stargazers_count":29,"open_issues_count":14,"forks_count":10,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-07-08T12:40:10.260Z","etag":null,"topics":["apm","appsec","datadog","nginx","observability","security","tracing"],"latest_commit_sha":null,"homepage":"https://www.datadoghq.com","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-3rdparty.csv","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-21T19:20:21.000Z","updated_at":"2025-06-18T15:35:34.000Z","dependencies_parsed_at":"2023-10-26T22:32:04.979Z","dependency_job_id":"663ae126-f1bb-4da2-a7c9-b38a4a20a173","html_url":"https://github.com/DataDog/nginx-datadog","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/DataDog/nginx-datadog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fnginx-datadog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fnginx-datadog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fnginx-datadog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fnginx-datadog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/nginx-datadog/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fnginx-datadog/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265485394,"owners_count":23774482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apm","appsec","datadog","nginx","observability","security","tracing"],"created_at":"2024-11-08T23:37:35.868Z","updated_at":"2026-02-06T20:08:11.436Z","avatar_url":"https://github.com/DataDog.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg alt=\"Datadog Tracing Nginx\" src=\"mascot.svg\" height=\"200\"/\u003e\n\n[![codecov](https://codecov.io/gh/DataDog/nginx-datadog/graph/badge.svg?token=SZCZI1FAYU)](https://codecov.io/gh/DataDog/nginx-datadog)\n# Datadog Nginx Module\nThis repository contains the source code for the `ngx_http_datadog_module`, an Nginx module\nthat integrates Datadog [APM](https://docs.datadoghq.com/tracing) and\n[Application Security Management](https://docs.datadoghq.com/security/application_security) into Nginx.\n\n## Usage\n1. Download a gzipped tarball from a [recent release](https://github.com/DataDog/nginx-datadog/releases),\n   extract it to wherever Nginx looks for modules (e.g. `/usr/lib/nginx/modules/`).\n2. Add the following line to the top of the main Nginx configuration (e.g.\n   `/etc/nginx/nginx.conf`):\n\n```nginx\nload_module modules/ngx_http_datadog_module.so;\n```\n\nTracing is automatically added to all endpoints by default. For more\ninformation, see [the API documentation](doc/API.md).\n\n## Compatibility\n\u003e [!IMPORTANT]\n\u003e We provide support for Nginx versions up to their End Of Life, extended by one\n\u003e year. [Aligned with the Nginx release cycle](https://docs.nginx.com/nginx/releases),\n\u003e this entails support for the four most recent Nginx versions.\n\u003e\n\u003e If you plan to add tracing features to an older Nginx version using our\n\u003e module, please check out [the build section](#build) for guidance.\n\nThere are two tarballs (the actual executable module and, separately, the debug\nsymbols) per each combination of: 1) Nginx version, 2) architecture, 3) whether\nAppSec is built in or not. The main tarball contains a single file,\n`ngx_http_datadog_module.so`, which is the Datadog Nginx module.\n\nThe naming convention is:\n\n* `ngx_http_datadog_module-\u003carch\u003e-\u003cversion\u003e.so.tgz` for builds without appsec\n  support and\n* `ngx_http_datadog_module-appsec-\u003carch\u003e-\u003cversion\u003e.so.tgz` for builds with\n  appsec support.\n\n\u003e [!IMPORTANT]\n\u003e The AppSec variants require Nginx to have been built with `--threads` (thread\n\u003e support).\n\nSupported architectures (`\u003carch\u003e`) are `amd64` and `arm64`.\n\nWhile it _may_ be possible to build the extension against an older version, this\nis not guaranteed; in particular, AppSec builds require a feature introduced in\nversion 1.21.4.\n\n## Default Behavior\nUnless otherwise configured, `ngx_http_datadog_module` adds the following\ndefault behavior to Nginx:\n\n### Tracing\n- Connect to the Datadog agent at `http://localhost:8126`.\n- Create one span per request:\n    - Service name is \"nginx\".\n    - Operation name is \"nginx.request\".\n    - Resource name is `\"$request_method $uri\"`, e.g. \"GET /api/book/0-345-24223-8/title\".\n    - Includes multiple `http.*` [tags](https://github.com/DataDog/nginx-datadog/blob/535a291ce96d8ca80cb12b22febac1e138e45847/src/tracing_library.cpp#L187-L203).\n\nCustom configuration can be specified via the [datadog\\_*](doc/API.md) family of\ndirectives in Nginx's configuration file, or via [environment variables](https://github.com/DataDog/dd-trace-cpp/blob/main/include/datadog/environment.h).\n\n## Enabling AppSec\n\nTo enable AppSec, besides using the correct binary (the relase artifact with\n\"-appsec\") in the name, it's necessary to edit the Nginx configuration:\n\n* Set `datadog_appsec_enabled on;`.\n* Define one (or more thread pools).\n* Choose which thread pool AppSec will use, either on a global or a per-location\n  basis.\n\nFor more information, see [the documentation](doc/API.md).\n\n## Building the Module\nIf the version of Nginx you’re using is no longer supported by this repository,\nyou can build the module by following the steps below.\n\nThis repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for some of its dependencies.\nTo ensure all dependencies are available or updated before building, run the\nfollowing command:\n\n```shell\ngit submodule update --init --recursive\n```\n\n### Prerequisites\nBefore building the module, ensure your environment meets the following requirements:\n\n- Recent C and C++ toolchain (`clang` or `gcc/g++`) (must support at least some\n  C++20 features).\n- make.\n- CMake `v3.24` or newer.\n- Architecture is either `x86_64` or `arm64`.\n\n### Building Using Docker\nWe recommend using Docker which greatly simplify the build process for various environments.\nBelow are specific commands and options for different build targets.\n\n\u003e [!IMPORTANT]\n\u003e Be sure to match the version of Nginx, OpenResty, or Ingress Nginx with the version you\n\u003e are using in your environment to avoid compatibility issues.\n\n#### Building for Nginx\n\u003e [!NOTE]\n\u003e The `build-musl` target builds against [musl](https://www.musl-libc.org/) to guarantee portability.\n\n```shell\nWAF=ON ARCH=x86_64 NGINX_VERSION=1.27.1 make build-musl\n```\n\nOptions:\n  - `WAF=\u003cON|OFF\u003e`: Enable (`ON`) or disable (`OFF`) AppSec.\n  - `ARCH=\u003cx86_64|aarch64\u003e`: Specify the CPU architecture.\n  - `NGINX_VERSION=\u003cversion\u003e`: Specify the Nginx version to build.\n\nThe Nginx module will be generated at `.musl-build\\ngx_http_datadog_module.so`.\n\n### Building for OpenResty Using Docker\n\u003e [!NOTE]\n\u003e The `build-openresty` target builds against [musl](https://www.musl-libc.org/) to guarantee portability.\n\nTo build the module for OpenResty:\n\n```shell\nWAF=ON ARCH=x86_64 RESTY_VERSION=1.27.1.1 make build-openresty\n```\n\nOptions:\n  - `WAF=\u003cON|OFF\u003e`: Enable (`ON`) or disable (`OFF`) AppSec.\n  - `ARCH=\u003cx86_64|aarch64\u003e`: Specify the CPU architecture.\n  - `RESTY_VERSION=\u003cversion\u003e`: Specify the OpenResty version to build.\n\nThe Nginx module will be generated at `.musl-build\\ngx_http_datadog_module.so`.\n\n### Building for Ingress Nginx using Docker\n\u003e [!NOTE]\n\u003e The `build-ingress-nginx` target builds against [musl](https://www.musl-libc.org/) to guarantee portability.\n\nTo build the module for [Ingress Nginx](https://github.com/kubernetes/ingress-nginx):\n\n```shell\nWAF=ON ARCH=x86_64 INGRESS_NGINX_VERSION=1.11.2 make build-ingress-nginx\n```\n\nOptions:\n  - `WAF=\u003cON|OFF\u003e`: Enable (`ON`) or disable (`OFF`) AppSec.\n  - `ARCH=\u003cx86_64|aarch64\u003e`: Specify the CPU architecture.\n  - `INGRESS_NGINX_VERSION=\u003cversion\u003e`: Specify the version Ingress Nginx to build.\n\nThe Nginx module will be generated at `.musl-build\\ngx_http_datadog_module.so`.\n\n## Acknowledgements\nThis project is based largely on previous work. See [CREDITS.md](CREDITS.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fnginx-datadog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadog%2Fnginx-datadog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fnginx-datadog/lists"}