Class: Datadog::Tracing::Span

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

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Metadata

included

Constructor Details

#initialize(name, duration: nil, end_time: nil, id: nil, meta: nil, metrics: 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) ⇒ Span

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.



50
51
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/span.rb', line 50

def initialize(
  name,
  duration: nil,
  end_time: nil,
  id: nil,
  meta: nil,
  metrics: 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 || {}
  @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 ⇒ Object 



113
114
115
116
117
118
119
 
# File 'lib/datadog/tracing/span.rb', line 113

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

#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



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

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

#pretty_print(q) ⇒ Object

Return a human readable version of the span



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
194
195
 
# File 'lib/datadog/tracing/span.rb', line 166

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: [', ']') do
      q.breakable
      q.seplist @metrics.each do |key, value|
        q.text "#{key} => #{value}"
      end
    end
  end
end

#set_error(e) ⇒ Object 



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

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

#started? ⇒ Boolean

Return whether the duration is started or not

Returns:

  • (Boolean) 


103
104
105
 
# File 'lib/datadog/tracing/span.rb', line 103

def started?
  !@start_time.nil?
end

#stopped? ⇒ Boolean Also known as: finished?

Return whether the duration is stopped or not.

Returns:

  • (Boolean) 


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

def stopped?
  !@end_time.nil?
end

#to_hash ⇒ Object

Return the hash representation of the current span. TODO: Change this to reflect attributes when serialization isn’t handled by this method.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/datadog/tracing/span.rb', line 140

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

  h = {
    error: @status,
    meta: @meta,
    metrics: @metrics,
    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.



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

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