dd-trace-rb

Unlike other components in dd-trace-rb, the telemetry component allows events to be submitted before its background worker has actually started.

This capability is specifically designed to capture and report errors that occur during the Datadog.configure process. If errors occur during configuration, the telemetry component buffers these events and transmits them once the telemetry worker successfully starts.

Dynamic Instrumentation includes safeguards to minimize performance impact on your application.

Default Rate Limits

Probes have built-in rate limits that can be overridden in the probe definition:

• Non-capturing probes: 5,000 invocations per second.
• Capturing probes (with snapshots): 1 invocation per second.

Circuit Breaker

To protect application performance, an automatic circuit breaker is active:

• If a probe's execution overhead exceeds 0.5 seconds of CPU time, it is automatically disabled.
• Once disabled by the circuit breaker, the probe must be recreated in the Datadog UI to be used again.
• This CPU threshold can be configured globally.

When the Datadog APM integration is active alongside OpenTelemetry, certain OpenTelemetry features are unsupported or behave differently:

• Context propagation: Unsupported. Datadog distributed header format is used instead.
• Span processors: Unsupported.
• Span Exporters: Unsupported.
• OpenTelemetry.logger: Special behavior. It is set to the same object as Datadog.logger.
• Trace/span ID generators: Special behavior. ID generation is performed by datadog.

Profiling operates via two independent background threads:

1. The Scheduler: Wakes up every 1 minute to flush Exporter results via HttpTransport.
2. The CpuAndWallTimeWorker: The 'active' part of the profiler. It manages timers and tracepoints to trigger sampling.

When a sample is triggered, a synchronous pipeline is executed:

1. Collectors::CpuAndWallTimeWorker identifies the event (Timing, GC, or Allocations).
2. Collectors::ThreadContext gathers event details (cpu-time, thread id, span id, etc.).
3. Collectors::Stack gathers the stack trace.
4. StackRecorder records the sample into the native libdatadog data structure.

Control then returns up the stack through each component until it returns to the Ruby VM.

In 1.0, manual tracing via Datadog::Tracing.trace provides two objects to the block: a Datadog::Tracing::SpanOperation (as span) and a Datadog::Tracing::TraceOperation (as trace).

The span object is similar to the old 0.x span but with restricted access to certain fields like context. The trace object models the trace itself and provides access to trace-level state and functions.

### New 1.0 ###
Datadog::Tracing.trace('my.job') do |span, trace|
  # Do work...
  # span => #<Datadog::Tracing::SpanOperation>
  # trace => #<Datadog::Tracing::TraceOperation>
end

You can apply different tracing configurations to different MongoDB connections using the describes option. This option accepts a connection string or a regular expression. When a connection matches a rule, the latest matching rule is applied.

If a block is provided to instrument, it yields a settings object for that specific pattern.

Datadog.configure do |c|
  # Match by exact connection string
  c.tracing.instrument :mongo, describes: '127.0.0.1:27017', service_name: 'mongo-primary'

  # Match by regular expression
  c.tracing.instrument :mongo, describes: /localhost.*/, service_name: 'mongo-secondary'
end

Deprecated API objects in dd-trace-rb are scheduled for removal in the next major version release.

To manage migrations:

1. Identify warnings: Deprecated objects receive a deprecation tag in a minor version release. This allows you to surface warnings in your development environment before the breaking change occurs.
2. Safe usage: You can continue to use deprecated objects safely until the next major version is released.
3. Plan updates: When you see deprecation warnings, plan to migrate to the recommended replacement before upgrading to the next major version of the gem.

In version 1.0 and later, when using a trace processor in the processing pipeline via Datadog::Tracing.before_flush, the block now provides a Datadog::Tracing::TraceSegment object as the trace argument, rather than an Array[Datadog::Span]. This TraceSegment object can be directly mutated.

### New 1.0 ###
Datadog::Tracing.before_flush do |trace|
   # Processing logic...
   trace # => #<Datadog::Tracing::TraceSegment>
end

Propagation API

Datadog::Tracing::Propagation::HTTP has moved to Datadog::Tracing::Contrib::HTTP.

Environment Variables

DD_PROPAGATION_STYLE_INJECT and DD_PROPAGATION_STYLE_EXTRACT are now prefixed with DD_TRACE_.

B3 Strategy Constants

B3 strategy values are now case-insensitive. Use the following for constants:

• b3 for PROPAGATION_STYLE_B3_SINGLE_HEADER (single header)
• b3multi for PROPAGATION_STYLE_B3_MULTI_HEADER (multiple headers)