ddtrace 0.54.2 → 1.0.0

data/docs/ProfilingDevelopment.md

@@ -6,19 +6,18 @@ For a more practical view of getting started with development of `ddtrace`, see
 
 ## Profiling components high-level view
 
-Components below live inside <../lib/ddtrace/profiling>:
+Components below live inside <../lib/datadog/profiling>:
 
 * `Collectors::Stack`: Collects stack trace samples from Ruby threads for both CPU-time (if available) and wall-clock.
   Runs on its own background thread.
+* `Collectors::CodeProvenance`: Collects library metadata to power grouping and categorization of stack traces (e.g. to help distinguish user code, from libraries, from the standard library, etc).
 * `Encoding::Profile`: Encodes gathered data into the pprof format.
 * `Events::Stack`, `Events::StackSample`: Entity classes used to represent stacks.
-* `Ext::CPU`: Monkey patches Ruby's `Thread` with our `Ext::CThread` to enable CPU-time profiling.
-* `Ext::CThread`: Extension used to enable CPU-time profiling via use of Pthread's `getcpuclockid`.
 * `Ext::Forking`: Monkey patches `Kernel#fork`, adding a `Kernel#at_fork` callback mechanism which is used to restore
   profiling abilities after the VM forks (such as re-instrumenting the main thread, and restarting profiler threads).
-* `Pprof::*` (in <../lib/ddtrace/profiling/pprof>): Converts samples captured in the `Recorder` into the pprof format.
-* `Tasks::Setup`: Takes care of loading our extensions/monkey patches to handle fork() and CPU profiling.
-* `Transport::*` (in <../lib/ddtrace/profiling/transport>): Implements transmission of profiling payloads to the Datadog agent
+* `Pprof::*` (in <../lib/datadog/profiling/pprof>): Converts samples captured in the `Recorder` into the pprof format.
+* `Tasks::Setup`: Takes care of loading our extensions/monkey patches to handle fork().
+* `Transport::*` (in <../lib/datadog/profiling/transport>): Implements transmission of profiling payloads to the Datadog agent
   or backend.
 * `TraceIdentifiers::*`: Used to retrieve trace id and span id from tracers, to be used to connect traces to profiles.
 * `BacktraceLocation`: Entity class used to represent an entry in a stack trace.
@@ -35,13 +34,12 @@ Components below live inside <../lib/ddtrace/profiling>:
 When started via `ddtracerb exec` (together with `DD_PROFILING_ENABLED=true`), initialization goes through the following
 flow:
 
-1. <../lib/ddtrace/profiling/preload.rb> triggers the creation of the `Datadog.profiler` instance by calling the method
-2. `Datadog.profiler` is handled by `Datadog::Configuration`, which triggers the configuration of `ddtrace` components
+1. <../lib/datadog/profiling/preload.rb> triggers the creation of the profiler instance by calling the method `Datadog::Profiling.start_if_enabled`
+2. The profiler instance is handled by `Datadog::Configuration`, which triggers the configuration of `ddtrace` components
    in `#build_components`
 3. Inside `Datadog::Components`, the `build_profiler` method triggers the execution of the `Tasks::Setup`
 4. The `Setup` task activates our extensions
     * `Datadog::Profiling::Ext::Forking`
-    * `Datadog::Profiling::Ext::CPU`
 5. Still inside `Datadog::Components`, the `build_profiler` method then creates and wires up the Profiler as such:
     ```asciiflow
             +------------+
@@ -62,6 +60,11 @@ flow:
             +-+-------+-+
             | Recorder  |
             +-----------+
+              |
+              v
+        +-----------------+
+        | Code Provenance |
+        +-----------------+
     ```
 6. The profiler gets started when `startup!` is called by `Datadog::Configuration` after component creation.
 

data/docs/PublicApi.md

@@ -0,0 +1,14 @@
+# Public API
+
+`ddtrace` respects [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+Classes, modules, and methods marked as part of the public API will not introduce
+breaking changes outside of a major version release.
+
+Objects that belong to the public API are marked with the `@public_api` YARD documentation tag.
+When navigating [`ddtrace`'s YARD documentation](https://rubydoc.info/gems/ddtrace), public API
+objects will have an explicit banner informing the user that they are part of the public API contract.
+
+Objects not marked with the `@public_api` tag are not part of the public API contract, and thus
+considered internal to `ddtrace`. These objects can receive breaking changes in minor and patch
+releases.