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, span_type: nil, start_time: nil, status: 0, type: span_type, trace_id: nil, service_entry: 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.


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 55

def initialize(
  name,
  duration: nil,
  end_time: nil,
  id: nil,
  meta: nil,
  metrics: nil,
  parent_id: 0,
  resource: name,
  service: nil,
  span_type: nil,
  start_time: nil,
  status: 0,
  type: span_type,
  trace_id: nil,
  service_entry: 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

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



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def end_time
  @end_time
end

#id ⇒ Object Also known as: span_id

Returns the value of attribute id.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def id
  @id
end

#meta ⇒ Object

Returns the value of attribute meta.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def meta
  @meta
end

#metrics ⇒ Object

Returns the value of attribute metrics.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def metrics
  @metrics
end

#name ⇒ Object

Returns the value of attribute name.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def name
  @name
end

#parent_id ⇒ Object

Returns the value of attribute parent_id.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def parent_id
  @parent_id
end

#resource ⇒ Object

Returns the value of attribute resource.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def resource
  @resource
end

#service ⇒ Object

Returns the value of attribute service.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def service
  @service
end

#start_time ⇒ Object

Returns the value of attribute start_time.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def start_time
  @start_time
end

#status ⇒ Object

Returns the value of attribute status.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def status
  @status
end

#trace_id ⇒ Object

Returns the value of attribute trace_id.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

def trace_id
  @trace_id
end

#type ⇒ Object Also known as: span_type

Returns the value of attribute type.



22
23
24
 
# File 'lib/datadog/tracing/span.rb', line 22

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



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

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
  super
end

#started? ⇒ Object

Return whether the duration is started or not



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

def started?
  !@start_time.nil?
end

#stopped? ⇒ Object Also known as: finished?

Return whether the duration is stopped or not.



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.

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

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

  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