From 69b775abe45491de7c2ef0afc07f34f7aad2b066 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Fri, 3 Jul 2026 12:51:02 +0200 Subject: [PATCH 1/6] Rename doc folder in docs --- {doc => docs}/README.md | 0 {doc => docs}/decisions.md | 0 {doc => docs}/maintainers.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename {doc => docs}/README.md (100%) rename {doc => docs}/decisions.md (100%) rename {doc => docs}/maintainers.md (100%) diff --git a/doc/README.md b/docs/README.md similarity index 100% rename from doc/README.md rename to docs/README.md diff --git a/doc/decisions.md b/docs/decisions.md similarity index 100% rename from doc/decisions.md rename to docs/decisions.md diff --git a/doc/maintainers.md b/docs/maintainers.md similarity index 100% rename from doc/maintainers.md rename to docs/maintainers.md From 3e2d955c44a9cc688ed7eb1b130d11dc0bf78dec Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Fri, 3 Jul 2026 13:20:28 +0200 Subject: [PATCH 2/6] Little clean-up of the Contributing and Security documents and their references --- CONTRIBUTING.md | 13 ++++--------- README.md | 28 ++++++++++++---------------- SECURITY.md | 19 +++++++++---------- docs/development.md | 24 ++++++++++++++++++++++++ 4 files changed, 49 insertions(+), 35 deletions(-) create mode 100644 docs/development.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef6af873..5c2093a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to dd-trace-cpp +# Contributing to the Datadog C++ Tracing Library Pull requests for bug fixes are welcome. @@ -6,11 +6,6 @@ Before submitting new features or changes to current functionality, [open an issue](https://github.com/DataDog/dd-trace-cpp/issues/new) and discuss your ideas or propose the changes you wish to make. After a resolution is reached, a PR can be submitted for review. -## Code Style - -C++ code is formatted using `clang-format-14`. Before submitting code changes, run the following -command: - -```shell -bin/format -``` +Please refer to the [documentation](docs) to learn about the architecture of the Datadog of C++ Tracing +Library and the development processes, notably testing and code formatting, which are mandatory before +submitting code changes. diff --git a/README.md b/README.md index 66cb32e5..23d4264a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ # Datadog C++ Tracing Library +This repository contains the Datadog C++ Tracing Library, also known as the C++ Tracer or +`dd-trace-cpp`. + +## Usage Example + ```c++ #include #include @@ -37,7 +42,7 @@ int main() { } ``` -See the [examples](examples) directory for more extensive usage examples. +See the [examples](examples) for more extensive usage examples. ## Platform Support @@ -107,21 +112,12 @@ options is not needed. The `-ldd_trace_cpp` option is always needed. c++ -o my_app my_app.o -L/path/to/dd-trace-cpp/.install/lib -ldd_trace_cpp ``` -## Test - -Pass `-DDD_TRACE_BUILD_TESTING=1` to `cmake` to include the unit tests in the build. - -The resulting unit test executable is `test/tests` within the build directory. - -```shell -cmake -B build -DDD_TRACE_BUILD_TESTING=1 . -cmake --build build -j -./build/test/tests -``` +## Contributing -Alternatively, [bin/test](bin/test) is provided for convenience. +See the [contributing guidelines](CONTRIBUTING.md) if you would like to contribute to the Datadog +C++ Tracing Library. -## Contributing +## Security -See the [contributing guidelines](CONTRIBUTING.md) and the [maintainer docs](doc/maintainers.md) for -information on the overall structure of the repository. +If you discover a security vulnerablity in this sofware component, please refer to the [Security +Policy](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md index bdd29933..3728eaa4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,10 +1,10 @@ -# Security Policy +# Datadog C++ Tracing Library Security Policy -This document outlines the security policy for the Datadog C++ client library (a.k.a. C++ tracer) -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. +This document outlines the security policy for the Datadog C++ Tracing Library 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 @@ -13,7 +13,6 @@ release](https://github.com/DataDog/dd-trace-cpp/releases). ## Reporting a Vulnerability -If you discover a vulnerability in the Datadog C++ client library (or any Datadog product for that -matter) please submit details to the following email address: - -* [security@datadoghq.com](mailto:security@datadoghq.com) +If you discover a vulnerability in the Datadog C++ Tracing Library (or any Datadog product for that +matter) please submit details to the [security@datadoghq.com](mailto:security@datadoghq.com) email +address. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..dacb0d11 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,24 @@ +# Development Processes + +## Test + +Pass `-DDD_TRACE_BUILD_TESTING=1` to `cmake` to include the unit tests in the build. + +The resulting unit test executable is `test/tests` within the build directory. + +```shell +cmake -B build -DDD_TRACE_BUILD_TESTING=1 . +cmake --build build -j +./build/test/tests +``` + +Alternatively, [bin/test](bin/test) is provided for convenience. + +## Code Style + +C++ code is formatted using `clang-format-14`. Before submitting code changes, run the following +command: + +```shell +bin/format +``` From 12853cb1135b21c64f410cb0e06b1b31e9832015 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Fri, 3 Jul 2026 13:24:41 +0200 Subject: [PATCH 3/6] Rename Maintainers documentation in Design --- docs/{maintainers.md => design.md} | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) rename docs/{maintainers.md => design.md} (99%) diff --git a/docs/maintainers.md b/docs/design.md similarity index 99% rename from docs/maintainers.md rename to docs/design.md index 3247e561..d173e5b4 100644 --- a/docs/maintainers.md +++ b/docs/design.md @@ -1,6 +1,4 @@ -# Care and Feeding of Your New Tracing Library - -Congratulations! You are now the proud owner of a distributed tracing library. +# Datadog C++ Tracing Library Design The primary purpose of this guide is to describe salient features of the library's design. `dd-trace-cpp` differs considerably from its [older From 94c3760cddcab36df7655d994c95ec0773c5f5ab Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Fri, 3 Jul 2026 13:34:00 +0200 Subject: [PATCH 4/6] Move 'Logical Component Relationships' section in Design documentation --- docs/README.md | 51 ++++---------------------------------------- docs/design.md | 58 +++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 57 insertions(+), 52 deletions(-) diff --git a/docs/README.md b/docs/README.md index a85736de..b798fd37 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,49 +1,6 @@ -# Logical Component Relationships +# Datadog C++ Tracing Library Documentation -- Vertices are components. -- Edges are ownership relationships between components. Each edge is labeled by the kind of pointer - that is used to implement the relationship. -- Components with a padlock are protected by a mutex. +This directory contains documentation of the Datadog C++ Tracing Library, including: -```mermaid ---- -title: Components Relationships -config: - layout: elk ---- -graph LR; - Tracer(Tracer) & TraceSegment("TraceSegment 🔒")-- shared -->Collector("Collector 🔒") & SpanSampler("SpanSampler 🔒") & TraceSampler("TraceSampler 🔒") - TraceSegment-- "`**unique**`" -->SpanData(SpanData) - Span(Span)-- shared -->TraceSegment - Span-- "`**raw**`" -->SpanData -``` - -## Objects - -- `Span` has a beginning, end, and tags. It is associated with a `TraceSegment`. -- `TraceSegment` is part of a trace. It makes sampling decisions, detects when it is finished, and - sends itself to the `Collector`. -- `Collector` receives trace segments. It provides a callback to deliver sampler modifications, if - applicable. -- `Tracer` is responsible for creating trace segments. It contains the instances of, and - configuration for, the `Collector`, `TraceSampler`, and `SpanSampler`. A tracer is created from a - `TracerConfig`. -- `TraceSampler` is used by trace segments to decide when to keep or drop themselves. -- `SpanSampler` is used by trace segments to decide which spans to keep when the segment is dropped. -- `TracerConfig` contains all of the information needed to configure the collector, trace sampler, - and span sampler, as well as defaults for span properties. - -## Usage - -Intended usage is: - -1. Create a `TracerConfig`. -2. Use the `TracerConfig` to create a `Tracer`. -3. Use the `Tracer` to create and/or extract local root `Span`s. -4. Use `Span` to create children and/or inject context. -5. Use a `Span`'s `TraceSegment` to perform trace-wide operations. -6. When all `Span`s in `TraceSegment` are finished, the segment is sent to the - `Collector`. - -Different instances of `Tracer` are independent of each other. If an application wishes to -reconfigure tracing at runtime, it can create another `Tracer` using the new configuration. +- [Design](design) +- [Development Processes](development) diff --git a/docs/design.md b/docs/design.md index d173e5b4..93aebfc7 100644 --- a/docs/design.md +++ b/docs/design.md @@ -8,7 +8,7 @@ sibling](https://github.com/DataDog/dd-opentracing-cpp) and This guide will also cover operations performed by maintainers of the library, such as scooping the box, applying flea medication, and regular trips to the vet. -## Design +## Architecture ### Span @@ -276,7 +276,55 @@ uses a different implementation, [class AgentHTTPClient : public HTTPClient, ...](https://github.com/envoyproxy/envoy/blob/main/source/extensions/tracers/datadog/agent_http_client.h), which uses Envoy's built-in HTTP facilities. libcurl is not involved at all. -### EventScheduler +### Logical Component Relationships + +- Vertices are components. +- Edges are ownership relationships between components. Each edge is labeled by the kind of pointer + that is used to implement the relationship. +- Components with a padlock are protected by a mutex. + +```mermaid +--- +title: Components Relationships +config: + layout: elk +--- +graph LR; + Tracer(Tracer) & TraceSegment("TraceSegment 🔒")-- shared -->Collector("Collector 🔒") & SpanSampler("SpanSampler 🔒") & TraceSampler("TraceSampler 🔒") + TraceSegment-- "`**unique**`" -->SpanData(SpanData) + Span(Span)-- shared -->TraceSegment + Span-- "`**raw**`" -->SpanData +``` + +Objects: + +- `Span` has a beginning, end, and tags. It is associated with a `TraceSegment`. +- `TraceSegment` is part of a trace. It makes sampling decisions, detects when it is finished, and + sends itself to the `Collector`. +- `Collector` receives trace segments. It provides a callback to deliver sampler modifications, if + applicable. +- `Tracer` is responsible for creating trace segments. It contains the instances of, and + configuration for, the `Collector`, `TraceSampler`, and `SpanSampler`. A tracer is created from a + `TracerConfig`. +- `TraceSampler` is used by trace segments to decide when to keep or drop themselves. +- `SpanSampler` is used by trace segments to decide which spans to keep when the segment is dropped. +- `TracerConfig` contains all of the information needed to configure the collector, trace sampler, + and span sampler, as well as defaults for span properties. + +Intended usage is: + +1. Create a `TracerConfig`. +2. Use the `TracerConfig` to create a `Tracer`. +3. Use the `Tracer` to create and/or extract local root `Span`s. +4. Use `Span` to create children and/or inject context. +5. Use a `Span`'s `TraceSegment` to perform trace-wide operations. +6. When all `Span`s in `TraceSegment` are finished, the segment is sent to the + `Collector`. + +Different instances of `Tracer` are independent of each other. If an application wishes to +reconfigure tracing at runtime, it can create another `Tracer` using the new configuration. + +## EventScheduler As of this writing, `class DatadogAgent` flushes batches of finished trace segments to the Datadog Agent once every two second [by @@ -312,7 +360,7 @@ also uses a different implementation, [class EventScheduler : public EventScheduler](https://github.com/envoyproxy/envoy/blob/main/source/extensions/tracers/datadog/event_scheduler.h), which uses Envoy's built-in event dispatch facilities. -### Configuration +## Configuration There's a good [blog post](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) by [Alexis King](https://lexi-lambda.github.io/about.html) where she makes the case for encoding @@ -360,7 +408,7 @@ is to prevent eventual intermixing between the "configuration representation" an representation." In part, `finalize_config` already mitigates the problem. Abstaining from storing the finalized config as a data member is a step further. -### Error Handling +## Error Handling Most error scenarios within this library are individually enumerated by `enum Error::Code`, defined in [error.h](../include/datadog/error.h). @@ -512,7 +560,7 @@ operator bool` has the opposite meaning as it does in `Expected`. I wanted er be the same in the two cases, and so I specialized `Expected`. `Expected` is implemented in terms of `std::optional`, but inverts the value of `explicit operator bool`. -### Logging +## Logging Can we write a tracing library that does not do any logging by itself? The previous section describes how errors are reported by the library, and no logging is involved there. Why not leave it From b8d769ec6033af800991477a8c72e1d88ff4e6b6 Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Fri, 3 Jul 2026 13:48:39 +0200 Subject: [PATCH 5/6] fix relative links in documentation --- docs/README.md | 4 ++-- docs/development.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index b798fd37..7437f123 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,5 +2,5 @@ This directory contains documentation of the Datadog C++ Tracing Library, including: -- [Design](design) -- [Development Processes](development) +- [Design](design.md) +- [Development Processes](development.md) diff --git a/docs/development.md b/docs/development.md index dacb0d11..c54ee7ec 100644 --- a/docs/development.md +++ b/docs/development.md @@ -12,7 +12,7 @@ cmake --build build -j ./build/test/tests ``` -Alternatively, [bin/test](bin/test) is provided for convenience. +Alternatively, [bin/test](../bin/test) is provided for convenience. ## Code Style From fff3c499b4d5caeec1a54f2d5d4f96b47fef688f Mon Sep 17 00:00:00 2001 From: Xavier Lamorlette Date: Fri, 3 Jul 2026 15:12:07 +0200 Subject: [PATCH 6/6] In documentation, rename 'Datadog C++ Tracing Library' in 'Datadog C++ Tracer' --- CONTRIBUTING.md | 2 +- README.md | 10 +++++----- SECURITY.md | 13 ++++++------- docs/README.md | 4 ++-- docs/design.md | 6 +++--- docs/development.md | 2 +- 6 files changed, 18 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c2093a7..4cebc135 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to the Datadog C++ Tracing Library +# Contributing to the Datadog C++ Tracer Pull requests for bug fixes are welcome. diff --git a/README.md b/README.md index 23d4264a..9778eeaa 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# Datadog C++ Tracing Library +# Datadog C++ Tracer -This repository contains the Datadog C++ Tracing Library, also known as the C++ Tracer or -`dd-trace-cpp`. +This `dd-trace-cpp` repository contains the Datadog C++ Tracer, which is the [Datadog Application +Performance Monitoring (APM)](https://docs.datadoghq.com/tracing) C++ client library. ## Usage Example @@ -115,9 +115,9 @@ c++ -o my_app my_app.o -L/path/to/dd-trace-cpp/.install/lib -ldd_trace_cpp ## Contributing See the [contributing guidelines](CONTRIBUTING.md) if you would like to contribute to the Datadog -C++ Tracing Library. +C++ Tracer. ## Security -If you discover a security vulnerablity in this sofware component, please refer to the [Security +If you discover a security vulnerablity in the Datadog C++ Tracer, please refer to the [Security Policy](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md index 3728eaa4..4bdea8c3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,8 +1,8 @@ -# Datadog C++ Tracing Library Security Policy +# Datadog C++ Tracer Security Policy -This document outlines the security policy for the Datadog C++ Tracing Library 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 +This document outlines the security policy for the Datadog C++ Tracer 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. @@ -13,6 +13,5 @@ release](https://github.com/DataDog/dd-trace-cpp/releases). ## Reporting a Vulnerability -If you discover a vulnerability in the Datadog C++ Tracing Library (or any Datadog product for that -matter) please submit details to the [security@datadoghq.com](mailto:security@datadoghq.com) email -address. +If you discover a vulnerability in the Datadog C++ Tracer (or any Datadog product for that matter) +please submit details to the [security@datadoghq.com](mailto:security@datadoghq.com) email address. diff --git a/docs/README.md b/docs/README.md index 7437f123..41d91c18 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ -# Datadog C++ Tracing Library Documentation +# Datadog C++ Tracer Documentation -This directory contains documentation of the Datadog C++ Tracing Library, including: +This directory contains documentation of the Datadog C++ Tracer, including: - [Design](design.md) - [Development Processes](development.md) diff --git a/docs/design.md b/docs/design.md index 93aebfc7..8dfd8b80 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,7 +1,7 @@ -# Datadog C++ Tracing Library Design +# Datadog C++ Tracer Design -The primary purpose of this guide is to describe salient features of the library's design. -`dd-trace-cpp` differs considerably from its [older +The primary purpose of this guide is to describe salient features of the Datadog C++ Tracer's +design. It differs considerably from its [older sibling](https://github.com/DataDog/dd-opentracing-cpp) and [peers](https://github.com/open-telemetry/opentelemetry-cpp). diff --git a/docs/development.md b/docs/development.md index c54ee7ec..17191469 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,4 +1,4 @@ -# Development Processes +# Datadog C++ Tracer Development Processes ## Test