Class: Datadog::Span

Inherits:
Object
  • Object
show all
Defined in:
lib/ddtrace/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.

Constant Summary collapse

MAX_ID =

The max value for a Span identifier

2**64 - 1

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(tracer, name, options = {}) ⇒ Span

Create a new span linked to the given tracer. Call the finish() method once the tracer operation is over or use the finish_at(time) helper to close the span with the given time. Available options are:

  • service: the service name for this span

  • resource: the resource this span refers, or name if it’s missing

  • span_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



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/ddtrace/span.rb', line 30

def initialize(tracer, name, options = {})
  @tracer = tracer

  @name = name
  @service = options.fetch(:service, nil)
  @resource = options.fetch(:resource, name)
  @span_type = options.fetch(:span_type, nil)

  @span_id = Datadog::Utils.next_id()
  @parent_id = options.fetch(:parent_id, 0)
  @trace_id = options.fetch(:trace_id, @span_id)

  @meta = {}
  @metrics = {}
  @status = 0

  @parent = nil
  @sampled = true

  @start_time = Time.now.utc
  @end_time = nil
end

Instance Attribute Details

#end_time ⇒ Object

Returns the value of attribute end_time.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def end_time
  @end_time
end

#name ⇒ Object

Returns the value of attribute name.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def name
  @name
end

#parent ⇒ Object

Returns the value of attribute parent.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def parent
  @parent
end

#parent_id ⇒ Object

Returns the value of attribute parent_id.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def parent_id
  @parent_id
end

#resource ⇒ Object

Returns the value of attribute resource.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def resource
  @resource
end

#sampled ⇒ Object

Returns the value of attribute sampled.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def sampled
  @sampled
end

#service ⇒ Object

Returns the value of attribute service.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def service
  @service
end

#span_id ⇒ Object

Returns the value of attribute span_id.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def span_id
  @span_id
end

#span_type ⇒ Object

Returns the value of attribute span_type.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def span_type
  @span_type
end

#start_time ⇒ Object

Returns the value of attribute start_time.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def start_time
  @start_time
end

#status ⇒ Object

Returns the value of attribute status.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def status
  @status
end

#trace_id ⇒ Object

Returns the value of attribute trace_id.



16
17
18
 
# File 'lib/ddtrace/span.rb', line 16

def trace_id
  @trace_id
end

Instance Method Details

#finish(finish_time = nil) ⇒ Object

Mark the span finished at the current time and submit it.



93
94
95
96
97
98
99
 
# File 'lib/ddtrace/span.rb', line 93

def finish(finish_time = nil)
  return if finished?

  @end_time = finish_time.nil? ? Time.now.utc : finish_time
  @tracer.record(self) unless @tracer.nil?
  self
end

#finish_at(finish_time) ⇒ Object

Proxy function that flag a span as finished with the given timestamp. This function is used for retro-compatibility. DEPRECATED: remove this function in the next release



104
105
106
 
# File 'lib/ddtrace/span.rb', line 104

def finish_at(finish_time)
  finish(finish_time)
end

#finished? ⇒ Boolean

Return whether the span is finished or not.

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/ddtrace/span.rb', line 109

def finished?
  !@end_time.nil?
end

#get_metric(key) ⇒ Object

Return the metric with the given key, nil if it doesn’t exist.



79
80
81
 
# File 'lib/ddtrace/span.rb', line 79

def get_metric(key)
  @metrics[key]
end

#get_tag(key) ⇒ Object

Return the tag with the given key, nil if it doesn’t exist.



64
65
66
 
# File 'lib/ddtrace/span.rb', line 64

def get_tag(key)
  @meta[key]
end

#pretty_print(q) ⇒ Object

Return a human readable version of the span



157
158
159
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
 
# File 'lib/ddtrace/span.rb', line 157

def pretty_print(q)
  start_time = (@start_time.to_f * 1e9).to_i rescue '-'
  end_time = (@end_time.to_f * 1e9).to_i rescue '-'
  duration = ((@end_time - @start_time) * 1e9).to_i rescue 0
  q.group 0 do
    q.breakable
    q.text "Name: #{@name}\n"
    q.text "Span ID: #{@span_id}\n"
    q.text "Parent ID: #{@parent_id}\n"
    q.text "Trace ID: #{@trace_id}\n"
    q.text "Type: #{@span_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}\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

Mark the span with the given error.



84
85
86
87
88
89
90
 
# File 'lib/ddtrace/span.rb', line 84

def set_error(e)
  return if e.nil?
  @status = 1
  @meta[Datadog::Ext::Errors::MSG] = e.message if e.respond_to?(:message) && e.message
  @meta[Datadog::Ext::Errors::TYPE] = e.class.to_s
  @meta[Datadog::Ext::Errors::STACK] = e.backtrace.join("\n") if e.respond_to?(:backtrace) && e.backtrace
end

#set_metric(key, value) ⇒ Object

Set the given key / value metric pair on the span. Keys must be string. Values must be floating point numbers.



70
71
72
73
74
75
76
 
# File 'lib/ddtrace/span.rb', line 70

def set_metric(key, value)
  # enforce that the value is a floating point number
  value = Float(value)
  @metrics[key] = value
rescue StandardError => e
  Datadog::Tracer.log.debug("Unable to set the metric #{key}, ignoring it. Caused by: #{e}")
end

#set_parent(parent) ⇒ Object

Set this span’s parent, inheriting any properties not explicitly set. If the parent is nil, set the span zero values.



120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/ddtrace/span.rb', line 120

def set_parent(parent)
  @parent = parent

  if parent.nil?
    @trace_id = @span_id
    @parent_id = 0
  else
    @trace_id = parent.trace_id
    @parent_id = parent.span_id
    @service ||= parent.service
  end
end

#set_tag(key, value) ⇒ Object

Set the given key / value tag pair on the span. Keys and values must be strings. A valid example is:

span.set_tag('http.method', request.method)



57
58
59
60
61
 
# File 'lib/ddtrace/span.rb', line 57

def set_tag(key, value)
  @meta[key] = value.to_s
rescue StandardError => e
  Datadog::Tracer.log.debug("Unable to set the tag #{key}, ignoring it. Caused by: #{e}")
end

#to_hash ⇒ Object

Return the hash representation of the current span.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/ddtrace/span.rb', line 134

def to_hash
  h = {
    span_id: @span_id,
    parent_id: @parent_id,
    trace_id: @trace_id,
    name: @name,
    service: @service,
    resource: @resource,
    type: @span_type,
    meta: @meta,
    metrics: @metrics,
    error: @status
  }

  if !@start_time.nil? && !@end_time.nil?
    h[:start] = (@start_time.to_f * 1e9).to_i
    h[:duration] = ((@end_time - @start_time) * 1e9).to_i
  end

  h
end

#to_s ⇒ Object

Return a string representation of the span.



114
115
116
 
# File 'lib/ddtrace/span.rb', line 114

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