Reorganize the documentation

CONTRIBUTING.md

@@ -1,16 +1,11 @@
-# Contributing to dd-trace-cpp
+# Contributing to the Datadog C++ Tracer
 
 Pull requests for bug fixes are welcome.
 
 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.

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 <datadog/span_config.h>
@@ -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).

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.

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)

doc/maintainers.md → 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<T>`. I wanted er
 be the same in the two cases, and so I specialized `Expected<void>`. `Expected<void>` is implemented
 in terms of `std::optional<Error>`, 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

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
+```