diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..fd09ff02 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +# Agent Instructions + +## Conventions + +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. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 26d73dbf..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,41 +0,0 @@ -# CLAUDE.md - -## 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/ 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63d4b270..9e106c2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,10 @@ -# Contributing +# Contributing to the Datadog Apache Httpd Module -## Fork, Clone, Branch and Create your PR +## Conventions + +Follow [docs/conventions.md](doc/conventions.md). + +## Clone When cloning the repo, initialize the submodules you need. For a standard build: @@ -8,21 +12,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. - -### Rules -- Follow the pattern of what you already see in the code. -- Follow the coding style. +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: -# Development +```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,11 +35,23 @@ 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` -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 @@ -43,19 +60,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: @@ -68,6 +75,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). diff --git a/README.md b/README.md index c340202a..de03c281 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,20 @@ -# 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. +> [!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 +24,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. 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 };` 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.