Class: Datadog::Tracing::TraceOperation

Inherits:
Object
  • Object
show all
Includes:
OpenTelemetry::API::TraceOperation, Metadata::Tagging
Defined in:
lib/datadog/tracing/trace_operation.rb

Overview

Represents the act of tracing a series of operations, by generating and collecting span measurements. When completed, it yields a trace.

Supports synchronous code flow only. Usage across multiple threads will result in incorrect relationships. For async support, a TraceOperation should be employed per execution context (e.g. Thread, etc.)

Defined Under Namespace

Classes: Events

Constant Summary collapse

DEFAULT_MAX_LENGTH = 
100_000

Constants included from Metadata::Tagging

Metadata::Tagging::ENSURE_AGENT_TAGS, Metadata::Tagging::NUMERIC_TAG_SIZE_RANGE

Instance Attribute Summary collapse

Attributes included from OpenTelemetry::API::TraceOperation

#otel_context

Instance Method Summary collapse

Methods included from OpenTelemetry::API::TraceOperation

#otel_value, #otel_values

Methods included from Metadata::Tagging

#clear_metric, #clear_tag, #has_tag?, #set_metric, #set_tag, #set_tags

Constructor Details

#initialize(logger: Datadog.logger, agent_sample_rate: nil, events: nil, hostname: nil, id: nil, max_length: DEFAULT_MAX_LENGTH, name: nil, origin: nil, parent_span_id: nil, rate_limiter_rate: nil, resource: nil, rule_sample_rate: nil, sample_rate: nil, sampled: nil, sampling_priority: nil, service: nil, profiling_enabled: nil, apm_tracing_enabled: nil, tags: nil, metrics: nil, trace_state: nil, trace_state_unknown_fields: nil, remote_parent: false, tracer: nil, baggage: nil, auto_finish: true) ⇒ TraceOperation

Creates a new TraceOperation.

Parameters:



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/datadog/tracing/trace_operation.rb', line 64

def initialize(
  logger: Datadog.logger,
  agent_sample_rate: nil,
  events: nil,
  hostname: nil,
  id: nil,
  max_length: DEFAULT_MAX_LENGTH,
  name: nil,
  origin: nil,
  parent_span_id: nil,
  rate_limiter_rate: nil,
  resource: nil,
  rule_sample_rate: nil,
  sample_rate: nil,
  sampled: nil,
  sampling_priority: nil,
  service: nil,
  profiling_enabled: nil,
  apm_tracing_enabled: nil,
  tags: nil,
  metrics: nil,
  trace_state: nil,
  trace_state_unknown_fields: nil,
  remote_parent: false,
  tracer: nil, # DEV-3.0: deprecated, remove in 3.0
  baggage: nil,
  auto_finish: true
)
  @logger = logger

  # Attributes
  @id = id || Tracing::Utils::TraceId.next_id
  @max_length = max_length || DEFAULT_MAX_LENGTH
  @parent_span_id = parent_span_id
  @sampled = sampled.nil? || sampled
  @remote_parent = remote_parent

  # Tags
  @agent_sample_rate = agent_sample_rate
  @hostname = hostname
  @name = name
  @origin = origin
  @rate_limiter_rate = rate_limiter_rate
  @resource = resource
  @rule_sample_rate = rule_sample_rate
  @sample_rate = sample_rate
  @sampling_priority = sampling_priority
  @service = service
  @profiling_enabled = profiling_enabled
  @apm_tracing_enabled = apm_tracing_enabled
  @trace_state = trace_state
  @trace_state_unknown_fields = trace_state_unknown_fields
  @baggage = baggage

  # Generic tags
  set_tags(tags) if tags
  set_tags(metrics) if metrics

  # State
  @root_span = nil
  @active_span = nil
  @active_span_count = 0
  @events = events || Events.new
  @finished = false
  @spans = []
  @auto_finish = !!auto_finish
end

Instance Attribute Details

#active_span ⇒ Object (readonly)

Returns the value of attribute active_span.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def active_span
  @active_span
end

#active_span_count ⇒ Object (readonly)

Returns the value of attribute active_span_count.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def active_span_count
  @active_span_count
end

#agent_sample_rate ⇒ Object

Returns the value of attribute agent_sample_rate.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def agent_sample_rate
  @agent_sample_rate
end

#baggage ⇒ Object

Returns the value of attribute baggage.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def baggage
  @baggage
end

#hostname ⇒ Object

Returns the value of attribute hostname.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def hostname
  @hostname
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def id
  @id
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def logger
  @logger
end

#max_length ⇒ Object (readonly)

Returns the value of attribute max_length.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def max_length
  @max_length
end

#name ⇒ Object 



173
174
175
 
# File 'lib/datadog/tracing/trace_operation.rb', line 173

def name
  @name || root_span&.name
end

#origin ⇒ Object

Returns the value of attribute origin.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def origin
  @origin
end

#parent_span_id ⇒ Object (readonly)

Returns the value of attribute parent_span_id.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def parent_span_id
  @parent_span_id
end

#rate_limiter_rate ⇒ Object

Returns the value of attribute rate_limiter_rate.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def rate_limiter_rate
  @rate_limiter_rate
end

#remote_parent ⇒ Object

Returns the value of attribute remote_parent.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def remote_parent
  @remote_parent
end

#resource ⇒ Object 



177
178
179
 
# File 'lib/datadog/tracing/trace_operation.rb', line 177

def resource
  @resource || root_span&.resource
end

#rule_sample_rate ⇒ Object

Returns the value of attribute rule_sample_rate.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def rule_sample_rate
  @rule_sample_rate
end

#sample_rate ⇒ Object

Returns the value of attribute sample_rate.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def sample_rate
  @sample_rate
end

#sampled=(value) ⇒ Object (writeonly)

Sets the attribute sampled

Parameters:

  • the value to set the attribute sampled to.



52
53
54
 
# File 'lib/datadog/tracing/trace_operation.rb', line 52

def sampled=(value)
  @sampled = value
end

#sampling_priority ⇒ Object

Returns the value of attribute sampling_priority.



31
32
33
 
# File 'lib/datadog/tracing/trace_operation.rb', line 31

def sampling_priority
  @sampling_priority
end

#service ⇒ Object 



211
212
213
 
# File 'lib/datadog/tracing/trace_operation.rb', line 211

def service
  @service || root_span&.service
end

#trace_state ⇒ Object (readonly)

Returns the value of attribute trace_state.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def trace_state
  @trace_state
end

#trace_state_unknown_fields ⇒ Object (readonly)

Returns the value of attribute trace_state_unknown_fields.



42
43
44
 
# File 'lib/datadog/tracing/trace_operation.rb', line 42

def trace_state_unknown_fields
  @trace_state_unknown_fields
end

Instance Method Details

#build_span(op_name, logger: Datadog.logger, events: nil, on_error: nil, resource: nil, service: nil, start_time: nil, tags: nil, type: nil, id: nil) ⇒ Object 



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/datadog/tracing/trace_operation.rb', line 254

def build_span(
  op_name,
  logger: Datadog.logger,
  events: nil,
  on_error: nil,
  resource: nil,
  service: nil,
  start_time: nil,
  tags: nil,
  type: nil,
  id: nil
)
  # Resolve span options:
  # Parent, service name, etc.
  # Add default options
  trace_id = @id
  parent = @active_span

  # Use active span's span ID if available. Otherwise, the parent span ID.
  # Necessary when this trace continues from another, e.g. distributed trace.
  parent_id = parent ? parent.id : @parent_span_id || 0

  # Build events
  events ||= SpanOperation::Events.new(logger: logger)

  # Before start: activate the span, publish events.
  events.before_start.subscribe do |span_op|
    start_span(span_op)
  end

  # After finish: deactivate the span, record, publish events.
  events.after_finish.subscribe do |span, span_op|
    finish_span(span, span_op, parent)
  end

  # Build a new span operation
  SpanOperation.new(
    op_name,
    logger: logger,
    events: events,
    on_error: on_error,
    parent_id: parent_id,
    resource: resource || op_name,
    service: service,
    start_time: start_time,
    tags: tags,
    trace_id: trace_id,
    type: type,
    id: id
  )
rescue => e
  logger.debug { "Failed to build new span: #{e}" }

  # Return dummy span
  SpanOperation.new(op_name, logger: logger)
end

#finished? ⇒ Boolean

Returns:



140
141
142
 
# File 'lib/datadog/tracing/trace_operation.rb', line 140

def finished?
  @finished == true
end

#finished_span_count ⇒ Object 



136
137
138
 
# File 'lib/datadog/tracing/trace_operation.rb', line 136

def finished_span_count
  @spans.length
end

#flush! {|spans| ... } ⇒ TraceSegment

Returns a Datadog::Tracing::TraceSegment with all finished spans that can be flushed at invocation time. All other finished spans are discarded.

Yields:

  • (spans) —

    spans that will be returned as part of the trace segment returned

Returns:



316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/datadog/tracing/trace_operation.rb', line 316

def flush!
  finished = finished?

  # Copy out completed spans
  spans = @spans.dup
  @spans = []

  spans = yield(spans) if block_given?

  # Use them to build a trace
  build_trace(spans, !finished)
end

#fork_clone ⇒ Object

Returns a copy of this trace suitable for forks (w/o spans.) Used for continuation of traces across forks.



400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
 
# File 'lib/datadog/tracing/trace_operation.rb', line 400

def fork_clone
  self.class.new(
    agent_sample_rate: @agent_sample_rate,
    events: @events&.dup,
    hostname: @hostname&.dup,
    id: @id,
    max_length: @max_length,
    name: name&.dup,
    origin: @origin&.dup,
    parent_span_id: @active_span&.id || @parent_span_id,
    rate_limiter_rate: @rate_limiter_rate,
    resource: resource&.dup,
    rule_sample_rate: @rule_sample_rate,
    sample_rate: @sample_rate,
    sampled: @sampled,
    sampling_priority: @sampling_priority,
    service: service&.dup,
    trace_state: @trace_state&.dup,
    trace_state_unknown_fields: @trace_state_unknown_fields&.dup,
    tags: meta.dup,
    metrics: metrics.dup,
    remote_parent: @remote_parent
  )
end

#full? ⇒ Boolean

Returns:



132
133
134
 
# File 'lib/datadog/tracing/trace_operation.rb', line 132

def full?
  @max_length > 0 && @active_span_count >= @max_length
end

#get_metric(key) ⇒ Object 



186
187
188
 
# File 'lib/datadog/tracing/trace_operation.rb', line 186

def get_metric(key)
  super || root_span&.get_metric(key)
end

#get_tag(key) ⇒ Object

When retrieving tags or metrics we need to include root span tags for sampling purposes



182
183
184
 
# File 'lib/datadog/tracing/trace_operation.rb', line 182

def get_tag(key)
  super || root_span&.get_tag(key)
end

#keep! ⇒ Object 



162
163
164
165
166
 
# File 'lib/datadog/tracing/trace_operation.rb', line 162

def keep!
  self.sampling_priority = Sampling::Ext::Priority::USER_KEEP
  set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Tracing::Sampling::Ext::Decision::MANUAL)
  self.sampled = true # Just in case the in-app sampler had decided to drop this span, we revert that decision.
end

#measure(op_name, logger: Datadog.logger, events: nil, on_error: nil, resource: nil, service: nil, start_time: nil, tags: nil, type: nil, id: nil, &block) ⇒ Object 



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/datadog/tracing/trace_operation.rb', line 215

def measure(
  op_name,
  logger: Datadog.logger,
  events: nil,
  on_error: nil,
  resource: nil,
  service: nil,
  start_time: nil,
  tags: nil,
  type: nil,
  id: nil,
  &block
)
  # Don't allow more span measurements if the
  # trace is already completed. Prevents multiple
  # root spans with parent_span_id = 0.
  if finished? || full?
    return yield(
      SpanOperation.new(op_name, logger: logger),
      TraceOperation.new(logger: logger))
  end

  # Create new span
  span_op = build_span(
    op_name,
    events: events,
    on_error: on_error,
    resource: resource,
    service: service,
    start_time: start_time,
    tags: tags,
    type: type,
    id: id
  )

  # Start span measurement
  span_op.measure { |s| yield(s, self) }
end

#priority_sampled? ⇒ Boolean

Has the priority sampling chosen to keep this span?

Returns:



158
159
160
 
# File 'lib/datadog/tracing/trace_operation.rb', line 158

def priority_sampled?
  !@sampling_priority.nil? && @sampling_priority > 0
end

#reject! ⇒ Object 



168
169
170
171
 
# File 'lib/datadog/tracing/trace_operation.rb', line 168

def reject!
  self.sampling_priority = Sampling::Ext::Priority::USER_REJECT
  set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Tracing::Sampling::Ext::Decision::MANUAL)
end

#resource_override? ⇒ Boolean

Returns true if the resource has been explicitly set

Returns:



207
208
209
 
# File 'lib/datadog/tracing/trace_operation.rb', line 207

def resource_override?
  !@resource.nil?
end

#sampled? ⇒ Boolean

Will this trace be flushed by the tracer transport? This includes cases where the span is kept solely due to priority sampling.

This is not the ultimate Datadog App sampling decision. Downstream systems can decide to reject this trace, especially for cases where priority sampling is set to AUTO_KEEP.

Returns:



152
153
154
 
# File 'lib/datadog/tracing/trace_operation.rb', line 152

def sampled?
  @sampled == true || priority_sampled?
end

#set_distributed_source(product_bit) ⇒ Object 



190
191
192
193
194
 
# File 'lib/datadog/tracing/trace_operation.rb', line 190

def set_distributed_source(product_bit)
  source = get_tag(Metadata::Ext::Distributed::TAG_TRACE_SOURCE)&.to_i(16) || 0
  source |= product_bit
  set_tag(Metadata::Ext::Distributed::TAG_TRACE_SOURCE, format('%02X', source))
end

#tags ⇒ Object 



196
197
198
199
200
201
202
 
# File 'lib/datadog/tracing/trace_operation.rb', line 196

def tags
  all_tags = {}
  all_tags.merge!(root_span&.tags || {}) if root_span
  all_tags.merge!(super)

  all_tags
end

#to_correlation ⇒ Object 



387
388
389
390
391
392
393
394
395
396
 
# File 'lib/datadog/tracing/trace_operation.rb', line 387

def to_correlation
  # Resolve current span ID
  span_id = @active_span&.id
  span_id ||= @parent_span_id unless finished?

  Correlation::Identifier.new(
    trace_id: @id,
    span_id: span_id
  )
end

#to_digest ⇒ Object

Returns a set of trace headers used for continuing traces. Used for propagation across execution contexts. Data should reflect the active state of the trace. DEV-3.0: Sampling is a side effect of generating the digest. We should move the sample call to inject and right before moving to new contexts(threads, forking etc.)



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/datadog/tracing/trace_operation.rb', line 357

def to_digest
  # Resolve current span ID
  span_id = @active_span&.id
  span_id ||= @parent_span_id unless finished?
  # sample the trace_operation with the tracer
  events.trace_propagated.publish(self)

  TraceDigest.new(
    span_id: span_id,
    span_name: @active_span && @active_span.name,
    span_resource: @active_span && @active_span.resource,
    span_service: @active_span && @active_span.service,
    span_type: @active_span && @active_span.type,
    trace_distributed_tags: distributed_tags,
    trace_hostname: @hostname,
    trace_id: @id,
    trace_name: name,
    trace_origin: @origin,
    trace_process_id: Core::Environment::Identity.pid,
    trace_resource: resource,
    trace_runtime_id: Core::Environment::Identity.id,
    trace_sampling_priority: @sampling_priority,
    trace_service: service,
    trace_state: @trace_state,
    trace_state_unknown_fields: @trace_state_unknown_fields,
    span_remote: @remote_parent && @active_span.nil?,
    baggage: (@baggage.nil? || @baggage.empty?) ? nil : @baggage
  ).freeze
end