diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef6af873..4cebc135 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to dd-trace-cpp +# Contributing to the Datadog C++ Tracer 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..9778eeaa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ -# Datadog C++ Tracing Library +# Datadog C++ Tracer + +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 ```c++ #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++ Tracer. -## 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 the Datadog C++ Tracer, please refer to the [Security +Policy](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md index bdd29933..4bdea8c3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,10 +1,10 @@ -# Security Policy +# Datadog C++ Tracer 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++ 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. ## Supported Versions @@ -13,7 +13,5 @@ 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++ 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/doc/README.md b/doc/README.md deleted file mode 100644 index a85736de..00000000 --- a/doc/README.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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. - -## 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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..41d91c18 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,6 @@ +# Datadog C++ Tracer Documentation + +This directory contains documentation of the Datadog C++ Tracer, including: + +- [Design](design.md) +- [Development Processes](development.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/design.md similarity index 93% rename from doc/maintainers.md rename to docs/design.md index 3247e561..8dfd8b80 100644 --- a/doc/maintainers.md +++ b/docs/design.md @@ -1,16 +1,14 @@ -# Care and Feeding of Your New Tracing Library +# Datadog C++ Tracer Design -Congratulations! You are now the proud owner of a distributed tracing library. - -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). 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 @@ -278,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 @@ -314,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 @@ -362,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). @@ -514,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 diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..17191469 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,24 @@ +# Datadog C++ Tracer 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 +```