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

def duration
  return @duration if @duration
  return @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



124
125
126
127
 
# File 'lib/datadog/tracing/span.rb', line 124

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

#pretty_print(q) ⇒ Object

Return a human readable version of the span



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

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 



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

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.



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

def to_hash
  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[:meta]['events'] = @events.map(&:to_hash).to_json unless @events.empty?

  h
end

#to_s ⇒ Object

Return a string representation of the span.



130
131
132
 
# File 'lib/datadog/tracing/span.rb', line 130

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