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) ⇒ 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.

TODO: Remove span_type



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

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 



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

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

#id ⇒ Object Also known as: span_id

Returns the value of attribute id.



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

def id
  @id
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 Also known as: span_type

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



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

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

#pretty_print(q) ⇒ Object

Return a human readable version of the span



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/datadog/tracing/span.rb', line 158

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 



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

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

#started? ⇒ Boolean

Return whether the duration is started or not

Returns:

  • (Boolean) 


101
102
103
 
# File 'lib/datadog/tracing/span.rb', line 101

def started?
  !@start_time.nil?
end

#stopped? ⇒ Boolean Also known as: finished?

Return whether the duration is stopped or not.

Returns:

  • (Boolean) 


106
107
108
 
# File 'lib/datadog/tracing/span.rb', line 106

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.



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

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.



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

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