Class: Sentry::Span

Inherits:
Object
  • Object
show all
Defined in:
lib/sentry/span.rb

Direct Known Subclasses

Transaction

Defined Under Namespace

Modules: DataConventions

Constant Summary collapse

STATUS_MAP = 
{
  400 => "invalid_argument",
  401 => "unauthenticated",
  403 => "permission_denied",
  404 => "not_found",
  409 => "already_exists",
  429 => "resource_exhausted",
  499 => "cancelled",
  500 => "internal_error",
  501 => "unimplemented",
  503 => "unavailable",
  504 => "deadline_exceeded"
}
DEFAULT_SPAN_ORIGIN = 
"manual"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(transaction:, description: nil, op: nil, status: nil, trace_id: nil, span_id: nil, parent_span_id: nil, sampled: nil, start_timestamp: nil, timestamp: nil, origin: nil) ⇒ Span

Returns a new instance of Span.

[View source]

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/sentry/span.rb', line 117

def initialize(
  transaction:,
  description: nil,
  op: nil,
  status: nil,
  trace_id: nil,
  span_id: nil,
  parent_span_id: nil,
  sampled: nil,
  start_timestamp: nil,
  timestamp: nil,
  origin: nil
)
  @trace_id = trace_id || SecureRandom.uuid.delete("-")
  @span_id = span_id || SecureRandom.uuid.delete("-").slice(0, 16)
  @parent_span_id = parent_span_id
  @sampled = sampled
  @start_timestamp = start_timestamp || Sentry.utc_now.to_f
  @timestamp = timestamp
  @description = description
  @transaction = transaction
  @op = op
  @status = status
  @data = {}
  @tags = {}
  @origin = origin || DEFAULT_SPAN_ORIGIN
end

Instance Attribute Details

#data ⇒ Hash (readonly)

Span data

Returns:

  • (Hash) 

102
103
104
 
# File 'lib/sentry/span.rb', line 102

def data
  @data
end

#description ⇒ String (readonly)

Span description

Returns:

  • (String) 

90
91
92
 
# File 'lib/sentry/span.rb', line 90

def description
  @description
end

#op ⇒ String (readonly)

Span operation

Returns:

  • (String) 

93
94
95
 
# File 'lib/sentry/span.rb', line 93

def op
  @op
end

#origin ⇒ String (readonly)

Span origin that tracks what kind of instrumentation created a span

Returns:

  • (String) 

105
106
107
 
# File 'lib/sentry/span.rb', line 105

def origin
  @origin
end

#parent_span_id ⇒ String (readonly)

Span parent’s span_id.

Returns:

  • (String) 

78
79
80
 
# File 'lib/sentry/span.rb', line 78

def parent_span_id
  @parent_span_id
end

#sampled ⇒ Boolean? (readonly)

Sampling result of the span.

Returns:

  • (Boolean, nil) 

81
82
83
 
# File 'lib/sentry/span.rb', line 81

def sampled
  @sampled
end

#span_id ⇒ String (readonly)

An uuid that can be used to identify the span.

Returns:

  • (String) 

75
76
77
 
# File 'lib/sentry/span.rb', line 75

def span_id
  @span_id
end

#span_recorder ⇒ SpanRecorder

The SpanRecorder the current span belongs to. SpanRecorder holds all spans under the same Transaction object (including the Transaction itself).

Returns:

  • (SpanRecorder) 

110
111
112
 
# File 'lib/sentry/span.rb', line 110

def span_recorder
  @span_recorder
end

#start_timestamp ⇒ Float (readonly)

Starting timestamp of the span.

Returns:

  • (Float) 

84
85
86
 
# File 'lib/sentry/span.rb', line 84

def start_timestamp
  @start_timestamp
end

#status ⇒ String (readonly)

Span status

Returns:

  • (String) 

96
97
98
 
# File 'lib/sentry/span.rb', line 96

def status
  @status
end

#tags ⇒ Hash (readonly)

Span tags

Returns:

  • (Hash) 

99
100
101
 
# File 'lib/sentry/span.rb', line 99

def tags
  @tags
end

#timestamp ⇒ Float (readonly)

Finishing timestamp of the span.

Returns:

  • (Float) 

87
88
89
 
# File 'lib/sentry/span.rb', line 87

def timestamp
  @timestamp
end

#trace_id ⇒ String (readonly)

An uuid that can be used to identify a trace.

Returns:

  • (String) 

72
73
74
 
# File 'lib/sentry/span.rb', line 72

def trace_id
  @trace_id
end

#transaction ⇒ Transaction (readonly)

The Transaction object the Span belongs to. Every span needs to be attached to a Transaction and their child spans will also inherit the same transaction.

Returns:


115
116
117
 
# File 'lib/sentry/span.rb', line 115

def transaction
  @transaction
end

Instance Method Details

#deep_dup ⇒ Object

[View source]

246
247
248
 
# File 'lib/sentry/span.rb', line 246

def deep_dup
  dup
end

#finish(end_timestamp: nil) ⇒ self

Finishes the span by adding a timestamp.

Returns:

  • (self)
[View source]

147
148
149
150
 
# File 'lib/sentry/span.rb', line 147

def finish(end_timestamp: nil)
  @timestamp = end_timestamp || @timestamp || Sentry.utc_now.to_f
  self
end

#get_dynamic_sampling_context ⇒ Hash?

Returns the Dynamic Sampling Context from the transaction baggage.

Returns:

  • (Hash, nil)
[View source]

170
171
172
 
# File 'lib/sentry/span.rb', line 170

def get_dynamic_sampling_context
  transaction.get_baggage&.dynamic_sampling_context
end

#get_trace_context ⇒ Hash

Returns the span’s context that can be used to embed in an Event.

Returns:

  • (Hash)
[View source]

198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/sentry/span.rb', line 198

def get_trace_context
  {
    trace_id: @trace_id,
    span_id: @span_id,
    parent_span_id: @parent_span_id,
    description: @description,
    op: @op,
    status: @status,
    origin: @origin,
    data: @data
  }
end

#metrics_local_aggregator ⇒ Object

Collects gauge metrics on the span for metric summaries.

[View source]

311
312
313
 
# File 'lib/sentry/span.rb', line 311

def metrics_local_aggregator
  @metrics_local_aggregator ||= Sentry::Metrics::LocalAggregator.new
end

#metrics_summary ⇒ Object

[View source]

315
316
317
 
# File 'lib/sentry/span.rb', line 315

def metrics_summary
  @metrics_local_aggregator&.to_hash
end

#set_data(key, value) ⇒ Object

Inserts a key-value pair to the span’s data payload.

Parameters:

  • key (String, Symbol)
  • value (Object)
[View source]

293
294
295
 
# File 'lib/sentry/span.rb', line 293

def set_data(key, value)
  @data[key] = value
end

#set_description(description) ⇒ Object

Sets the span’s description.

Parameters:

  • description (String) —

    description of the span.

[View source]

258
259
260
 
# File 'lib/sentry/span.rb', line 258

def set_description(description)
  @description = description
end

#set_http_status(status_code) ⇒ Object

Sets the span’s status with given http status code.

Parameters:

  • status_code (String) —

    example: “500”.

[View source]

277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/sentry/span.rb', line 277

def set_http_status(status_code)
  status_code = status_code.to_i
  set_data(DataConventions::HTTP_STATUS_CODE, status_code)

  status =
    if status_code >= 200 && status_code < 299
      "ok"
    else
      STATUS_MAP[status_code]
    end
  set_status(status)
end

#set_op(op) ⇒ Object

Sets the span’s operation.

Parameters:

  • op (String) —

    operation of the span.

[View source]

252
253
254
 
# File 'lib/sentry/span.rb', line 252

def set_op(op)
  @op = op
end

#set_origin(origin) ⇒ Object

Sets the origin of the span.

Parameters:

  • origin (String)
[View source]

306
307
308
 
# File 'lib/sentry/span.rb', line 306

def set_origin(origin)
  @origin = origin
end

#set_status(status) ⇒ Object

Sets the span’s status.

Parameters:

  • satus (String) —

    status of the span.

[View source]

265
266
267
 
# File 'lib/sentry/span.rb', line 265

def set_status(status)
  @status = status
end

#set_tag(key, value) ⇒ Object

Sets a tag to the span.

Parameters:

  • key (String, Symbol)
  • value (String)
[View source]

300
301
302
 
# File 'lib/sentry/span.rb', line 300

def set_tag(key, value)
  @tags[key] = value
end

#set_timestamp(timestamp) ⇒ Object

Sets the span’s finish timestamp.

Parameters:

  • timestamp (Float) —

    finished time in float format (most precise).

[View source]

271
272
273
 
# File 'lib/sentry/span.rb', line 271

def set_timestamp(timestamp)
  @timestamp = timestamp
end

#start_child(**attributes) ⇒ Object

Starts a child span with given attributes.

Parameters:

  • attributes (Hash) —

    the attributes for the child span.

[View source]

213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/sentry/span.rb', line 213

def start_child(**attributes)
  attributes = attributes.dup.merge(transaction: @transaction, trace_id: @trace_id, parent_span_id: @span_id, sampled: @sampled)
  new_span = Span.new(**attributes)
  new_span.span_recorder = span_recorder

  if span_recorder
    span_recorder.add(new_span)
  end

  new_span
end

#to_baggage ⇒ String?

Generates a W3C Baggage header string for distributed tracing from the incoming baggage stored on the transaction.

Returns:

  • (String, nil)
[View source]

164
165
166
 
# File 'lib/sentry/span.rb', line 164

def to_baggage
  transaction.get_baggage&.serialize
end

#to_hash ⇒ Hash

Returns:

  • (Hash)
[View source]

175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/sentry/span.rb', line 175

def to_hash
  hash = {
    trace_id: @trace_id,
    span_id: @span_id,
    parent_span_id: @parent_span_id,
    start_timestamp: @start_timestamp,
    timestamp: @timestamp,
    description: @description,
    op: @op,
    status: @status,
    tags: @tags,
    data: @data,
    origin: @origin
  }

  summary = metrics_summary
  hash[:_metrics_summary] = summary if summary

  hash
end

#to_sentry_trace ⇒ String

Generates a trace string that can be used to connect other transactions.

Returns:

  • (String)
[View source]

154
155
156
157
158
159
 
# File 'lib/sentry/span.rb', line 154

def to_sentry_trace
  sampled_flag = ""
  sampled_flag = @sampled ? 1 : 0 unless @sampled.nil?

  "#{@trace_id}-#{@span_id}-#{sampled_flag}"
end

#with_child_span(**attributes, &block) {|child_span| ... } ⇒ Object

Starts a child span, yield it to the given block, and then finish the span after the block is executed.

Examples:

span.with_child_span do |child_span|
  # things happen here will be recorded in a child span
end

Parameters:

  • attributes (Hash) —

    the attributes for the child span.

  • block (Proc) —

    the action to be recorded in the child span.

Yield Parameters:

[View source]

234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/sentry/span.rb', line 234

def with_child_span(**attributes, &block)
  child_span = start_child(**attributes)

  yield(child_span)

  child_span.finish
rescue
  child_span.set_http_status(500)
  child_span.finish
  raise
end