Skip to content

Add option to override span events serialization #4507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcotc merged 5 commits into from
Mar 19, 2025
Merged

Add option to override span events serialization #4507

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2a04a1d
Add option to override span events serialization
marcotc Mar 18, 2025
79d4db5
Update docs/GettingStarted.md
marcotc Mar 18, 2025
c7fd5a5
Update docs/GettingStarted.md
marcotc Mar 19, 2025
78de1f6
Update setting doc and refacot test
marcotc Mar 19, 2025
43805f5
Merge branch 'master' into ruby-option-span-events
marcotc Mar 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/GettingStarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2072,6 +2072,7 @@ For example, if `tracing.sampling.default_rate` is configured by [Remote Configu
| `tracing.header_tags` | `DD_TRACE_HEADER_TAGS` | `Array` | `nil` | Record HTTP headers as span tags. See [Applying header tags to root spans][header tags] for more information. |
| `tracing.instrument(<integration-name>, <options...>)` | | | | Activates instrumentation for a specific library. See [Integration instrumentation](#integration-instrumentation) for more details. |
| `tracing.log_injection` | `DD_LOGS_INJECTION` | `Bool` | `true` | Injects [Trace Correlation](#trace-correlation) information into Rails logs if present. Supports the default logger (`ActiveSupport::TaggedLogging`), `lograge`, and `semantic_logger`. |
| `tracing.native_span_events` | `DD_TRACE_NATIVE_SPAN_EVENTS` | `Bool` | `false` | Forces the tracer to always send span events with the native span events format regardless of the agent support. This is useful to change the serialization format in agent-less setups. |
| `tracing.partial_flush.enabled` | | `Bool` | `false` | Enables or disables partial flushing. Partial flushing submits completed portions of a trace to the agent. Used when tracing instruments long running tasks (e.g. jobs) with many spans. |
| `tracing.partial_flush.min_spans_threshold` | | `Integer` | `500` | The number of spans that must be completed in a trace before partial flushing submits those completed spans. |
| `tracing.sampler` | | `Datadog::Tracing::Sampling::Sampler` | `nil` | Advanced usage only. Sets a custom `Datadog::Tracing::Sampling::Sampler` instance. If provided, the tracer will use this sampler to determine sampling behavior. See [Custom sampling](#custom-sampling) for details. |
Expand Down
1 change: 1 addition & 0 deletions lib/datadog/tracing/configuration/ext.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ module Ext
ENV_OTEL_TRACES_EXPORTER = 'OTEL_TRACES_EXPORTER'
ENV_HEADER_TAGS = 'DD_TRACE_HEADER_TAGS'
ENV_TRACE_ID_128_BIT_GENERATION_ENABLED = 'DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED'
ENV_NATIVE_SPAN_EVENTS = 'DD_TRACE_NATIVE_SPAN_EVENTS'

# @public_api
module SpanAttributeSchema
Expand Down
11 changes: 11 additions & 0 deletions lib/datadog/tracing/configuration/settings.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,17 @@ def self.extended(base)
o.type :bool
end

# Forces the tracer to always send span events with the native span events format
# regardless of the agent support. This is useful in agent-less setups.
#
# @default `DD_TRACE_NATIVE_SPAN_EVENTS` environment variable, otherwise `false`
# @return [Boolean,nil]
option :native_span_events do |o|
o.env Tracing::Configuration::Ext::ENV_NATIVE_SPAN_EVENTS
o.default nil
o.type :bool, nilable: true
end

# A custom sampler instance.
# The object must respect the {Datadog::Tracing::Sampling::Sampler} interface.
# @default `nil`
Expand Down
8 changes: 8 additions & 0 deletions lib/datadog/tracing/transport/traces.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,14 @@ def change_api!(api_id)
def native_events_supported?
return @native_events_supported if defined?(@native_events_supported)

# Check for an explicit override
option = Datadog.configuration.tracing.native_span_events
unless option.nil?
@native_events_supported = option
return option
end

# Otherwise, check for agent support, to ensure a configuration-less setup.
if (res = Datadog.send(:components).agent_info.fetch)
@native_events_supported = res.span_events == true
else
Expand Down
39 changes: 39 additions & 0 deletions spec/datadog/tracing/configuration/settings_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,6 +503,45 @@ def propagation_style_inject
end
end

describe '#native_span_events' do
subject(:native_span_events) { settings.tracing.native_span_events }

context "when #{Datadog::Tracing::Configuration::Ext::ENV_NATIVE_SPAN_EVENTS}" do
around do |example|
ClimateControl.modify(Datadog::Tracing::Configuration::Ext::ENV_NATIVE_SPAN_EVENTS => environment) do
example.run
end
end

context 'is not defined' do
let(:environment) { nil }

it { is_expected.to be nil }
end

context 'is set to true' do
let(:environment) { 'true' }

it { is_expected.to be true }
end

context 'is set to false' do
let(:environment) { 'false' }

it { is_expected.to be false }
end
end
end

describe '#native_span_events=' do
it 'changes the #native_span_events setting' do
expect { settings.tracing.native_span_events = true }
.to change { settings.tracing.native_span_events }
.from(nil)
.to(true)
end
end

describe '#sampler' do
subject(:sampler) { settings.tracing.sampler }

Expand Down
106 changes: 80 additions & 26 deletions spec/datadog/tracing/transport/traces_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,59 +283,113 @@
end

context 'for native span event support by the agent' do
context 'on a successful agent info call' do
context 'with support not advertised' do
let(:native_events_supported) { nil }

it 'does not encode native span events' do
expect(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).with(
encoder_v2,
native_events_supported: false
).and_return(chunker)
send_traces
after do
Datadog.configuration.tracing.reset_options!
end
context 'when native_span_events option is configured' do
context 'when set to true' do
before do
Datadog.configuration.tracing.native_span_events = true
end
end

context 'with support advertised as supported' do
let(:native_events_supported) { true }

it 'encodes native span events' do
it 'uses the configured value' do
expect(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).with(
encoder_v2,
native_events_supported: true
).and_return(chunker)

send_traces
end

it 'does not query the agent' do
allow(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).and_return(chunker)
expect_any_instance_of(Datadog::Core::Environment::AgentInfo).not_to receive(:fetch)

send_traces
end
end

context 'with support advertised as unsupported' do
context 'when set to false' do
before do
Datadog.configuration.tracing.native_span_events = false
end

let(:native_events_supported) { false }

it 'encodes native span events' do
it 'uses the configured value' do
expect(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).with(
encoder_v2,
native_events_supported: false
).and_return(chunker)
send_traces
end
end

it 'caches the agent result' do
transport.send_traces(traces)
transport.send_traces(traces)
it 'does not query the agent' do
allow(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).and_return(chunker)
expect_any_instance_of(Datadog::Core::Environment::AgentInfo).not_to receive(:fetch)

expect(Datadog.send(:components).agent_info).to have_received(:fetch).once
send_traces
end
end
end

context 'on an unsuccessful agent info call' do
let(:agent_info_response) { nil }
context 'when native_span_events option is not configured' do
context 'on a successful agent info call' do
context 'with support not advertised' do
let(:native_events_supported) { nil }

it 'does not encode native span events' do
expect(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).with(
encoder_v2,
native_events_supported: false
).and_return(chunker)
send_traces
end
end

context 'with support advertised as supported' do
let(:native_events_supported) { true }

it 'does not cache the agent result' do
transport.send_traces(traces)
transport.send_traces(traces)
it 'encodes native span events' do
expect(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).with(
encoder_v2,
native_events_supported: true
).and_return(chunker)
send_traces
end
end

context 'with support advertised as unsupported' do
let(:native_events_supported) { false }

it 'encodes native span events' do
expect(Datadog::Tracing::Transport::Traces::Chunker).to receive(:new).with(
encoder_v2,
native_events_supported: false
).and_return(chunker)
send_traces
end
end

expect(Datadog.send(:components).agent_info).to have_received(:fetch).twice
it 'caches the agent result' do
transport.send_traces(traces)
transport.send_traces(traces)

expect(Datadog.send(:components).agent_info).to have_received(:fetch).once
end
end

context 'on an unsuccessful agent info call' do
let(:agent_info_response) { nil }

it 'does not cache the agent result' do
transport.send_traces(traces)
transport.send_traces(traces)

expect(Datadog.send(:components).agent_info).to have_received(:fetch).twice
end
end
end
end
Expand Down
Loading