From 543c41643e5fc8f913c9f39aaa870d580dab39b9 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Mon, 17 Aug 2026 16:40:28 +0200 Subject: [PATCH 1/8] Little reformating in Main, Security and Contributing documentations --- CONTRIBUTING.md | 17 ++++++++++------- README.md | 25 ++++++++++++++++++------- SECURITY.md | 21 +++++++++++---------- 3 files changed, 39 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63d4b270..c452745e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing +# Contributing to the Datadog Apache Httpd Module ## Fork, Clone, Branch and Create your PR @@ -8,14 +8,14 @@ When cloning the repo, initialize the submodules you need. For a standard build: git submodule update --init deps/dd-trace-cpp deps/nginx-datadog ``` -The `deps/inject-browser-sdk` submodule is a private repo and is only required when building with `-DHTTPD_DATADOG_ENABLE_RUM=ON`. If you have access, use `--recursive` instead to pull it as well. +The `deps/inject-browser-sdk` submodule is a private repo and is only required when building with +`-DHTTPD_DATADOG_ENABLE_RUM=ON`. If you have access, use `--recursive` instead to pull it as well. + +## Rules -### Rules - Follow the pattern of what you already see in the code. - Follow the coding style. -# Development - ## Prerequisites | Tool | Version | Notes | @@ -34,7 +34,9 @@ pip install -r requirements.txt ### Setup `httpd` -In order to build the module you have to configure `httpd` with the [scripts/setup-httpd.py](./scripts/setup-httpd.py) script. Check what is the latest available version on [Apache website](https://httpd.apache.org), then: +In order to build the module you have to configure `httpd` with the +[scripts/setup-httpd.py](./scripts/setup-httpd.py) script. Check what is the latest available +version on [Apache website](https://httpd.apache.org), then: ```sh export HTTPD_VERSION=2.4.66 @@ -55,7 +57,8 @@ Relaunch your terminal (or do `source ~/.cargo/env`). ### Build the Module -CMake is our build system. If you are not familiar with CMake, read [the tutorial.](https://cmake.org/cmake/help/latest/guide/tutorial/index.html) +CMake is our build system. If you are not familiar with CMake, read [the +tutorial.](https://cmake.org/cmake/help/latest/guide/tutorial/index.html) Configure and compile all targets in release: diff --git a/README.md b/README.md index c340202a..f7101f2f 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,21 @@ -# Datadog Apache HTTPD Module +# Datadog Apache Httpd Module -This module adds distributed tracing to [Apache HTTP Server](https://httpd.apache.org/). Leveraging [Datadog's tracing library](https://github.com/DataDog/dd-trace-cpp/), it provides access to Datadog-specific functionality. +This module adds distributed tracing to [Apache HTTP Server](https://httpd.apache.org/). Leveraging +[Datadog's tracing library](https://github.com/DataDog/dd-trace-cpp/), it provides access to +Datadog-specific functionality. ## Getting Started > [!IMPORTANT] > Only Apache HTTP Server 2.4.x is supported. > -> For a detail understanding of our release cycle and Apache HTTPD support, read our [Release documentation](./doc/release.md). +> For a detail understanding of our release cycle and Apache HTTPD support, read our [Release +> documentation](./doc/release.md). ### Installation -Download a gzipped tarball compatible with your version of Apache HTTPD, extract it to wherever `httpd` looks for modules and add the following line to the top of your configuration file: +Download a gzipped tarball compatible with your version of Apache HTTPD, extract it to wherever +`httpd` looks for modules and add the following line to the top of your configuration file: ```sh LoadModule datadog_module /mod_datadog.so @@ -21,8 +25,15 @@ Then run `httpd -t ` to test the new configuration. ## Configuration -Once the module is loaded, by default all requests are traced and sent to the Datadog Agent. To change the module default behaviour, check our [Configuration page.](./doc/configuration.md) +Once the module is loaded, by default all requests are traced and sent to the Datadog Agent. To +change the module default behaviour, check our [Configuration page.](./doc/configuration.md) -## Development / Contribution +## Contribution -We welcome contributions. Before doing so, please read our [CONTRIBUTING.md](./CONTRIBUTING.md). +See the [contributing guidelines](CONTRIBUTING.md) if you would like to contribute to the Datadog +Apache Httpd Module. + +## Security + +If you discover a security vulnerablity in this softwa Datadog Apache Httpd Module, please refer to +the [Security Policy](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md index 9e9aaf66..d4e44a8f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,17 +1,18 @@ -# Security Policy - -This document outlines the security policy for the Datadog HTTPD module and what to do if you discover a security vulnerability in the project. -Most notably, please do not share the details in a public forum (such as in a discussion, issue, or pull request) but instead reach out to us with the details. -This gives us an opportunity to release a fix for others to benefit from by the time details are made public. +# Datadog Apache Httpd Module Security Policy +This document outlines the security policy for the Datadog Httpd module and what to do if you +discover a security vulnerability in the project. Most notably, please do not share the details in a +public forum (such as in a discussion, issue, or pull request) but instead reach out to us with the +details. This gives us an opportunity to release a fix for others to benefit from by the time +details are made public. ## Supported Versions -We accept vulnerability submissions for any currently maintained versions of HTTPD. - +We accept vulnerability submissions for the [currently maintained +release](https://github.com/DataDog/httpd-datadog/releases). ## Reporting a Vulnerability -If you discover a vulnerability please submit details to the following email address: - -* [security@datadoghq.com](mailto:security@datadoghq.com) +If you discover a vulnerability in the Datadog Apache Httpd Module (or any Datadog product for that +matter) please submit details to the [security@datadoghq.com](mailto:security@datadoghq.com) email +address. From 9ec21b10ee646e1ec8a65955f62d7e8a810600b9 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Mon, 17 Aug 2026 17:08:00 +0200 Subject: [PATCH 2/8] Add Conventions documentation --- doc/conventions.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 doc/conventions.md diff --git a/doc/conventions.md b/doc/conventions.md new file mode 100644 index 00000000..9eb3b258 --- /dev/null +++ b/doc/conventions.md @@ -0,0 +1,38 @@ +# Datadog Apache Httpd Module Conventions + +This document defines repository-wide conventions for `httpd-datadog`. Apply these conventions to +all new and modified code. + +## C++ Version + +The project uses C++17. + +## Clean Code + +- Use meaningful variable and function names. +- Do not use single-letter variable names. +- Avoid abbreviations, unless very common and unambiguous. +- Avoid obvious comments. +- Prefer clearer variable and function names over explanatory comments. +- Keep functions small and focused (<~ 20 lines when practical). +- When practical, place caller functions before callees, so the code can be read from top to bottom. + +## C++ Code Style + +- Use modern C++ idioms. +- Prefer explicit types. Use `auto` only for very long type names (>~ 50 characters). +- Never use C-style casts. +- Use raw pointers only when absolutely necessary. +- Use C++17 nested namespace syntax. +- Minimize the number of `#include` lines. Do not enforce the include-what-you-use rule. + +## Naming Conventions + +- class: `class TypeName;` +- class member function: `.member_function();` +- class public member: `int public_member;` +- class private member: `int private_member_;` +- free function: `free_function();` +- function argument: `function(int func_arg);` +- local variable: `int local_var;` +- enumeration: `enum class Color { RED, GREEN, BLUE };` From 3428a459c8bdf2363bfc970ce1513f2808375ec8 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Mon, 17 Aug 2026 17:11:29 +0200 Subject: [PATCH 3/8] Add Agent Instructions --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..8ebc27a0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +# Agent Instructions + +## Conventions + +Follow [docs/conventions.md](doc/conventions.md). + +## Build & Test + +See [CONTRIBUTING.md](CONTRIBUTING.md) for build and test instructions. From 0b335b972ac0dcd334a5f18254a2e5ec8b9ddb69 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Mon, 17 Aug 2026 17:15:26 +0200 Subject: [PATCH 4/8] merge build and test instructions from CLAUDE.md in CONTRIBUTING.md --- CLAUDE.md | 42 ++----------------------- CONTRIBUTING.md | 84 ++++++++++++++++++++++++++++++++++--------------- 2 files changed, 60 insertions(+), 66 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 26d73dbf..39c1be1c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,41 +1,3 @@ -# CLAUDE.md +# Claude Instructions -## Building and Testing - -Initialize the project submodules before building. The private -`inject-browser-sdk` submodule is required for RUM builds. - -```bash -git submodule update --init --recursive -make ci-build # Non-RUM CI build -make test-integration # RUM-enabled build and integration tests -make dev-shell # Interactive devcontainer shell -``` - -The devcontainer image is selected for the host architecture and includes the -LLVM toolchain, httpd source, Rust, and uv. - -### Running specific tests inside Docker - -```bash -make dev-shell -# Inside container: -.devcontainer/run-integration-tests.sh \ - scenarios/test_rum.py::test_rum_selective_disabling -m requires_rum -``` - -### Key paths inside the CI image - -- `/httpd` — httpd source -- `/httpd/httpd-build/bin/apachectl` — pre-built apachectl binary -- `/sysroot/{arch}-none-linux-musl/Toolchain.cmake` — cross-compilation toolchain - -### Test markers - -- `requires_rum` — tests needing RUM-enabled build (`-DHTTPD_DATADOG_ENABLE_RUM=ON`) -- Tests without markers run against the standard build - -## CI/CD - -GitLab CI status can be checked via `glab ci` on the automated mirror: -https://gitlab.ddbuild.io/DataDog/httpd-datadog/ +Follow [AGENTS.md](AGENTS.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c452745e..cfeac344 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to the Datadog Apache Httpd Module -## Fork, Clone, Branch and Create your PR +## Clone When cloning the repo, initialize the submodules you need. For a standard build: @@ -8,21 +8,22 @@ When cloning the repo, initialize the submodules you need. For a standard build: git submodule update --init deps/dd-trace-cpp deps/nginx-datadog ``` -The `deps/inject-browser-sdk` submodule is a private repo and is only required when building with -`-DHTTPD_DATADOG_ENABLE_RUM=ON`. If you have access, use `--recursive` instead to pull it as well. +The `deps/inject-browser-sdk` submodule is a private repository and is only required for RUM builds +(with `-DHTTPD_DATADOG_ENABLE_RUM=ON`). If you have access, use `--recursive` instead to pull it as +well: -## Rules - -- Follow the pattern of what you already see in the code. -- Follow the coding style. +```sh +git submodule update --init --recursive +``` ## Prerequisites -| Tool | Version | Notes | -| ---- | ------- | ----- | -| `clang` or `gcc` | 14+ or 11.4+ | | -| `python` | 3.0+ | | -| `cmake` | 3.12+ | | +| Tool | Version | +| ---- | ------- | +| `clang` | 17+ | +| `cmake` | 3.12+ | +| `gcc` | 13.2+ | +| `python` | 3.11+ | Once you got a valid Python installation, install all the dependencies with: @@ -30,6 +31,16 @@ Once you got a valid Python installation, install all the dependencies with: pip install -r requirements.txt ``` +## Install Rust + +The RUM variant requires Rust to build: + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +Relaunch your terminal (or do `source ~/.cargo/env`). + ## Compiling ### Setup `httpd` @@ -45,20 +56,9 @@ cd httpd ./configure --with-included-apr --prefix=$(pwd)/httpd-build --enable-mpms-shared="all" ``` -### Install Rust - -The RUM variant requires Rust to build: - -```sh -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -Relaunch your terminal (or do `source ~/.cargo/env`). - ### Build the Module -CMake is our build system. If you are not familiar with CMake, read [the -tutorial.](https://cmake.org/cmake/help/latest/guide/tutorial/index.html) +CMake is our build system. Configure and compile all targets in release: @@ -71,6 +71,38 @@ cmake --build build -j For now there are only [integration tests](./test/integration-test/). -## How to Debug +### Build Devcontainer Image + +```bash +make ci-build # Non-RUM CI build +make test-integration # RUM-enabled build and integration tests +make dev-shell # Interactive devcontainer shell +``` + +The devcontainer image is selected for the host architecture and includes the +LLVM toolchain, httpd source, Rust, and uv. + +### Running Specific Tests Inside Docker + +```bash +make dev-shell +# Inside container: +.devcontainer/run-integration-tests.sh \ + scenarios/test_rum.py::test_rum_selective_disabling -m requires_rum +``` + +### Key Paths Inside the CI Image + +- `/httpd` — httpd source +- `/httpd/httpd-build/bin/apachectl` — pre-built apachectl binary +- `/sysroot/{arch}-none-linux-musl/Toolchain.cmake` — cross-compilation toolchain + +### Test Markers + +- `requires_rum` — tests needing RUM-enabled build (`-DHTTPD_DATADOG_ENABLE_RUM=ON`) +- Tests without markers run against the standard build + +## CI -Run with `-X`. +GitLab CI status can be checked via `glab ci` on the [automated +mirror](https://gitlab.ddbuild.io/DataDog/httpd-datadog). From 164ac0588cd30bd6ae482ae34a388fa3bdd9197d Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Tue, 18 Aug 2026 12:58:34 +0200 Subject: [PATCH 5/8] Add link to Conventions in Contributing --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfeac344..9e106c2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,9 @@ # Contributing to the Datadog Apache Httpd Module +## Conventions + +Follow [docs/conventions.md](doc/conventions.md). + ## Clone When cloning the repo, initialize the submodules you need. For a standard build: From 0a59b3c30e0feaa26874a09aaa95ea2ff368a3b1 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Tue, 18 Aug 2026 13:22:13 +0200 Subject: [PATCH 6/8] Fix format of Release documentation --- README.md | 3 +-- doc/release.md | 19 ++++++++++++------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f7101f2f..de03c281 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,7 @@ Datadog-specific functionality. ## Getting Started -> [!IMPORTANT] -> Only Apache HTTP Server 2.4.x is supported. +> [!IMPORTANT] Only Apache HTTP Server 2.4.x is supported. > > For a detail understanding of our release cycle and Apache HTTPD support, read our [Release > documentation](./doc/release.md). diff --git a/doc/release.md b/doc/release.md index 05b3c77e..3eea2611 100644 --- a/doc/release.md +++ b/doc/release.md @@ -1,16 +1,19 @@ +# Release + ## Versioning -This module adheres to the principles of [Semantic Versioning (SemVer)](https://semver.org/). The version number is expressed as MAJOR.MINOR.PATCH, with the following guidelines: + +This module adheres to the principles of [Semantic Versioning (SemVer)](https://semver.org/). The +version number is expressed as MAJOR.MINOR.PATCH, with the following guidelines: - MAJOR version: Increment for incompatible API changes. - MINOR version: Increment for backward-compatible feature additions. - PATCH version: Increment for backward-compatible bug fixes. -We release at least one version per quarter. Nonetheless, we allow ourselves to release more if necessary. - ## Compatibility Requirements -Since this module is extending [Apache HTTP Server]() capabilities using the C interface, each versions are tied to a specific version of the webserver. -Each module version will receive support for the specified HTTPD version range until the respective HTTPD versions reach their end-of-life. +Since this module is extending Apache HTTP Server capabilities using the C interface, each versions +are tied to a specific version of the webserver. Each module version will receive support for the +specified HTTPD version range until the respective HTTPD versions reach their end-of-life. The following table outlines the compatibility between module versions and HTTPD versions: @@ -19,5 +22,7 @@ The following table outlines the compatibility between module versions and HTTPD | 1.0.0 | 2.4.0 - 2.4.54 | Current | ## Artifacts -Release artifact are generated through a Continuous Integration pipeline. Our CI infrastructure ensures cross-platform compatibility by compiling shared libraries for both Linux `x86_64` and `arm64` architectures. -It generates shared libaries for each HTTPD version supported. + +Release artifact are generated through a Continuous Integration pipeline. Our CI infrastructure +ensures cross-platform compatibility by compiling shared libraries for both Linux `x86_64` and +`arm64` architectures. It generates shared libaries for each HTTPD version supported. From 9f116ffc4a7d7b05df4ae01b09eb684eef374c13 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Thu, 20 Aug 2026 11:11:19 +0200 Subject: [PATCH 7/8] Change CLAUDE.md to be a symbolic link to AGENTS.md --- CLAUDE.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) mode change 100644 => 120000 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 39c1be1c..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,3 +0,0 @@ -# Claude Instructions - -Follow [AGENTS.md](AGENTS.md). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 7deae762dd56d92efc58f9e43b3defbe744da40d Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Thu, 20 Aug 2026 11:20:17 +0200 Subject: [PATCH 8/8] Add Agent-Only Instructions --- AGENTS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 8ebc27a0..fd09ff02 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,8 +2,12 @@ ## Conventions -Follow [docs/conventions.md](doc/conventions.md). +Follow [doc/conventions.md](doc/conventions.md). ## Build & Test See [CONTRIBUTING.md](CONTRIBUTING.md) for build and test instructions. + +## Agent-Only Instructions + +Write short comments, with simple words and short sentences.