Class: Datadog::Tracing::TraceOperation

Inherits:
Object
  • Object
show all
Includes:
OpenTelemetry::API::TraceOperation.self, 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

Instance Method Summary collapse

Methods included from Metadata::Tagging

#clear_metric, #clear_tag, #get_metric, #get_tag, #has_tag?, #set_metric, #set_tag, #set_tags, #tags

Constructor Details

#initialize(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, tags: nil, metrics: nil) ⇒ TraceOperation

Returns a new instance of TraceOperation.



52
53
54
55
56
57
58
59
60
61
62
63
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
 
# File 'lib/datadog/tracing/trace_operation.rb', line 52

def initialize(
  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,
  tags: nil,
  metrics: nil
)
  # Attributes
  @id = id || Tracing::Utils::TraceId.next_id
  @max_length = max_length || DEFAULT_MAX_LENGTH
  @parent_span_id = parent_span_id
  @sampled = sampled.nil? ? true : sampled

  # 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

  # 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 = []
end

Instance Attribute Details

#active_span ⇒ Object (readonly)

Returns the value of attribute active_span.



39
40
41
 
# File 'lib/datadog/tracing/trace_operation.rb', line 39

def active_span
  @active_span
end

#active_span_count ⇒ Object (readonly)

Returns the value of attribute active_span_count.



39
40
41
 
# File 'lib/datadog/tracing/trace_operation.rb', line 39

def active_span_count
  @active_span_count
end

#agent_sample_rate ⇒ Object

Returns the value of attribute agent_sample_rate.



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

def agent_sample_rate
  @agent_sample_rate
end

#hostname ⇒ Object

Returns the value of attribute hostname.



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

def hostname
  @hostname
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



39
40
41
 
# File 'lib/datadog/tracing/trace_operation.rb', line 39

def id
  @id
end

#max_length ⇒ Object (readonly)

Returns the value of attribute max_length.



39
40
41
 
# File 'lib/datadog/tracing/trace_operation.rb', line 39

def max_length
  @max_length
end

#name ⇒ Object 



144
145
146
 
# File 'lib/datadog/tracing/trace_operation.rb', line 144

def name
  @name || (root_span && root_span.name)
end

#origin ⇒ Object

Returns the value of attribute origin.



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

def origin
  @origin
end

#parent_span_id ⇒ Object (readonly)

Returns the value of attribute parent_span_id.



39
40
41
 
# File 'lib/datadog/tracing/trace_operation.rb', line 39

def parent_span_id
  @parent_span_id
end

#rate_limiter_rate ⇒ Object

Returns the value of attribute rate_limiter_rate.



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

def rate_limiter_rate
  @rate_limiter_rate
end

#resource ⇒ Object 



148
149
150
 
# File 'lib/datadog/tracing/trace_operation.rb', line 148

def resource
  @resource || (root_span && root_span.resource)
end

#rule_sample_rate ⇒ Object

Returns the value of attribute rule_sample_rate.



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

def rule_sample_rate
  @rule_sample_rate
end

#sample_rate ⇒ Object

Returns the value of attribute sample_rate.



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

def sample_rate
  @sample_rate
end

#sampled=(value) ⇒ Object (writeonly)

Sets the attribute sampled

Parameters:

  • value —

    the value to set the attribute sampled to.



46
47
48
 
# File 'lib/datadog/tracing/trace_operation.rb', line 46

def sampled=(value)
  @sampled = value
end

#sampling_priority ⇒ Object

Returns the value of attribute sampling_priority.



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

def sampling_priority
  @sampling_priority
end

#service ⇒ Object 



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

def service
  @service || (root_span && root_span.service)
end

Instance Method Details

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



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
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
 
# File 'lib/datadog/tracing/trace_operation.rb', line 195

def build_span(
  op_name,
  events: nil,
  on_error: nil,
  resource: nil,
  service: nil,
  start_time: nil,
  tags: nil,
  type: nil
)
  begin
    # 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

    # 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,
      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
    )
  rescue StandardError => e
    Datadog.logger.debug { "Failed to build new span: #{e}" }

    # Return dummy span
    SpanOperation.new(op_name)
  end
end

#finished? ⇒ Boolean

Returns:

  • (Boolean) 


110
111
112
 
# File 'lib/datadog/tracing/trace_operation.rb', line 110

def finished?
  @finished == true
end

#finished_span_count ⇒ Object 



106
107
108
 
# File 'lib/datadog/tracing/trace_operation.rb', line 106

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:



255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/datadog/tracing/trace_operation.rb', line 255

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.



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/datadog/tracing/trace_operation.rb', line 297

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

#full? ⇒ Boolean

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/datadog/tracing/trace_operation.rb', line 102

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

#keep! ⇒ Object 



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

def keep!
  self.sampled = true
  self.sampling_priority = Sampling::Ext::Priority::USER_KEEP
  set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Tracing::Sampling::Ext::Decision::MANUAL)
end

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



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/datadog/tracing/trace_operation.rb', line 163

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

  # 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
  )

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

#priority_sampled? ⇒ Boolean

Has the priority sampling chosen to keep this span?

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/datadog/tracing/trace_operation.rb', line 128

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

#reject! ⇒ Object 



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

def reject!
  self.sampled = false
  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:

  • (Boolean) 


155
156
157
 
# File 'lib/datadog/tracing/trace_operation.rb', line 155

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:

  • (Boolean) 


122
123
124
 
# File 'lib/datadog/tracing/trace_operation.rb', line 122

def sampled?
  @sampled == true || priority_sampled?
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.



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/datadog/tracing/trace_operation.rb', line 271

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

  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,
  ).freeze
end