Class: Datadog::Tracing::Span

Inherits:
Object
  • Object
show all
Includes:
Metadata
Defined in:
lib/datadog/tracing/span.rb,
sig/datadog/tracing/span.rbs

Overview

Represents a logical unit of work in the system. Each trace consists of one or more spans. Each span consists of a start time and a duration. For example, a span can describe the time spent on a distributed call on a separate machine, or the time spent in a small component within a larger operation. Spans can be nested within each other, and in those instances will have a parent-child relationship.

Constant Summary

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

included

Methods included from Metadata::Tagging

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

Methods included from Metadata::Errors

#set_error_tags

Constructor Details

#initialize(name, duration: nil, end_time: nil, id: nil, meta: nil, metrics: nil, metastruct: nil, parent_id: 0, resource: name, service: nil, start_time: nil, status: 0, type: nil, trace_id: nil, service_entry: nil, links: nil, events: nil) ⇒ Object

Create a new span manually. Call the start() method to start the time measurement and then stop() once the timing operation is over.

  • +service+: the service name for this span
  • +resource+: the resource this span refers, or +name+ if it's missing. +nil+ can be used as a placeholder, when the resource value is not yet known at +#initialize+ time.
  • +type+: the type of the span (such as +http+, +db+ and so on)
  • +parent_id+: the identifier of the parent span
  • +trace_id+: the identifier of the root span for this trace
  • +service_entry+: whether it is a service entry span.
  • +events+: the list of events that occurred while a span was active.


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
101
102
103
104
105
 
# File 'lib/datadog/tracing/span.rb', line 53

def initialize(
  name,
  duration: nil,
  end_time: nil,
  id: nil,
  meta: nil,
  metrics: nil,
  metastruct: nil,
  parent_id: 0,
  resource: name,
  service: nil,
  start_time: nil,
  status: 0,
  type: nil,
  trace_id: nil,
  service_entry: nil,
  links: nil,
  events: nil
)
  @name = Core::Utils::SafeDup.frozen_or_dup(name)
  @service = Core::Utils::SafeDup.frozen_or_dup(service)
  @resource = Core::Utils::SafeDup.frozen_or_dup(resource)
  @type = Core::Utils::SafeDup.frozen_or_dup(type)

  @id = id || Tracing::Utils.next_id
  @parent_id = parent_id || 0
  @trace_id = trace_id || Tracing::Utils.next_id

  @meta = meta || {}
  @metrics = metrics || {}
  @metastruct = metastruct || Metastruct.new
  @status = status || 0

  # start_time and end_time track wall clock. In Ruby, wall clock
  # has less accuracy than monotonic clock, so if possible we look to only use wall clock
  # to measure duration when a time is supplied by the user, or if monotonic clock
  # is unsupported.
  @start_time = start_time
  @end_time = end_time

  # duration_start and duration_end track monotonic clock, and may remain nil in cases where it
  # is known that we have to use wall clock to measure duration.
  @duration = duration

  @service_entry = service_entry

  @links = links || []

  @events = events || []

  # Mark with the service entry span metric, if applicable
  set_metric(Metadata::Ext::TAG_TOP_LEVEL, 1.0) if service_entry
end

Instance Attribute Details

#duration ⇒ Float?

Returns:

  • (Float, nil) 


118
119
120
121
122
123
124
 
# File 'lib/datadog/tracing/span.rb', line 118

def duration
  return @duration if @duration

  start_time = @start_time
  end_time = @end_time
  end_time - start_time if start_time && end_time
end

#end_time ⇒ Object

Returns the value of attribute end_time.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def end_time
  @end_time
end

#events ⇒ Object

Returns the value of attribute events.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def events
  @events
end

#id ⇒ Object

Returns the value of attribute id.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def id
  @id
end

#links ⇒ Object

Returns the value of attribute links.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def links
  @links
end

#meta ⇒ Object

Returns the value of attribute meta.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def meta
  @meta
end

#metastruct ⇒ Object (readonly)

Returns the value of attribute metastruct.



36
37
38
 
# File 'lib/datadog/tracing/span.rb', line 36

def metastruct
  @metastruct
end

#metrics ⇒ Object

Returns the value of attribute metrics.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def metrics
  @metrics
end

#name ⇒ Object

Returns the value of attribute name.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def name
  @name
end

#parent_id ⇒ Object

Returns the value of attribute parent_id.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def parent_id
  @parent_id
end

#resource ⇒ Object

Returns the value of attribute resource.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def resource
  @resource
end

#service ⇒ Object

Returns the value of attribute service.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def service
  @service
end

#start_time ⇒ Object

Returns the value of attribute start_time.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def start_time
  @start_time
end

#status ⇒ Object

Returns the value of attribute status.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def status
  @status
end

#trace_id ⇒ Object

Returns the value of attribute trace_id.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def trace_id
  @trace_id
end

#type ⇒ Object

Returns the value of attribute type.



20
21
22
 
# File 'lib/datadog/tracing/span.rb', line 20

def type
  @type
end

Instance Method Details

#==(other) ⇒ Object

Spans with the same ID are considered the same span



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

def ==(other)
  other.instance_of?(Span) &&
    @id == other.id
end

#duration_nano ⇒ Integer

Used for serialization

Returns:

  • (Integer) —

    in nanoseconds since Epoch



218
219
220
221
222
223
 
# File 'lib/datadog/tracing/span.rb', line 218

def duration_nano
  duration = self.duration
  return unless duration

  (duration * 1e9).to_i
end

#pretty_print(q) ⇒ Object

Return a human readable version of the span



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/datadog/tracing/span.rb', line 172

def pretty_print(q)
  start_time = (self.start_time.to_f * 1e9).to_i
  end_time = (self.end_time.to_f * 1e9).to_i
  q.group 0 do
    q.breakable
    q.text "Name: #{@name}\n"
    q.text "Span ID: #{@id}\n"
    q.text "Parent ID: #{@parent_id}\n"
    q.text "Trace ID: #{@trace_id}\n"
    q.text "Type: #{@type}\n"
    q.text "Service: #{@service}\n"
    q.text "Resource: #{@resource}\n"
    q.text "Error: #{@status}\n"
    q.text "Start: #{start_time}\n"
    q.text "End: #{end_time}\n"
    q.text "Duration: #{duration.to_f}\n"
    q.group(2, 'Tags: [', "]\n") do
      q.breakable
      q.seplist @meta.each do |key, value|
        q.text "#{key} => #{value}"
      end
    end
    q.group(2, 'Metrics: [', "]\n") do
      q.breakable
      q.seplist @metrics.each do |key, value|
        q.text "#{key} => #{value}"
      end
    end
    q.group(2, 'Metastruct: [', ']') do
      metastruct.pretty_print(q)
    end
  end
end

#service_entry? ⇒ Boolean

https://docs.datadoghq.com/tracing/visualization/#service-entry-span A span is a service entry span when it is the entrypoint method for a request to a service. You can visualize this within Datadog APM when the color of the immediate parent on a flame graph is a different color. Services are also listed on the right when viewing a flame graph.

Returns:

  • (Boolean) —

    true if the span is a serivce entry span



231
232
233
 
# File 'lib/datadog/tracing/span.rb', line 231

def service_entry?
  @service_entry == true
end

#set_error(e) ⇒ void

This method returns an undefined value.

Parameters:

  • e (Exception) 


126
127
128
129
 
# File 'lib/datadog/tracing/span.rb', line 126

def set_error(e)
  @status = Metadata::Ext::Errors::STATUS
  set_error_tags(e)
end

#start_time_nano ⇒ Integer

Used for serialization

Returns:

  • (Integer) —

    in nanoseconds since Epoch



210
211
212
213
214
 
# File 'lib/datadog/tracing/span.rb', line 210

def start_time_nano
  return unless (start_time = @start_time)

  start_time.to_i * 1000000000 + start_time.nsec
end

#started? ⇒ Object

Return whether the duration is started or not



108
109
110
 
# File 'lib/datadog/tracing/span.rb', line 108

def started?
  !@start_time.nil?
end

#stopped? ⇒ Object Also known as: finished?

Return whether the duration is stopped or not.



113
114
115
 
# File 'lib/datadog/tracing/span.rb', line 113

def stopped?
  !@end_time.nil?
end

#to_hash ⇒ Object

Return the hash representation of the current span.

isn't handled by this method.



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/datadog/tracing/span.rb', line 145

def to_hash
  @meta['events'] = @events.map(&:to_hash).to_json unless @events.empty?

  h = {
    error: @status,
    meta: @meta,
    metrics: @metrics,
    meta_struct: @metastruct.to_h,
    name: @name,
    parent_id: @parent_id,
    resource: @resource,
    service: @service,
    span_id: @id,
    trace_id: @trace_id,
    type: @type,
    span_links: @links.map(&:to_hash)
  }

  if stopped?
    h[:start] = start_time_nano
    h[:duration] = duration_nano
  end

  h
end

#to_s ⇒ Object

Return a string representation of the span.



138
139
140
 
# File 'lib/datadog/tracing/span.rb', line 138

def to_s
  "Span(name:#{@name},sid:#{@id},tid:#{@trace_id},pid:#{@parent_id})"
end