Class: Sentry::Scope

Inherits:
Object
  • Object
show all
Includes:
ArgumentCheckingHelper
Defined in:
lib/sentry/scope.rb

Constant Summary collapse

ATTRIBUTES = 
[
  :transaction_name,
  :transaction_source,
  :contexts,
  :extra,
  :tags,
  :user,
  :level,
  :breadcrumbs,
  :fingerprint,
  :event_processors,
  :rack_env,
  :span,
  :session,
  :attachments,
  :propagation_context,
  :attributes
]

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(max_breadcrumbs: nil) ⇒ Scope

Returns a new instance of Scope.

Parameters:

  • (defaults to: nil)

    the maximum number of breadcrumbs to be stored in the scope.



35
36
37
38
 
# File 'lib/sentry/scope.rb', line 35

def initialize(max_breadcrumbs: nil)
  @max_breadcrumbs = max_breadcrumbs
  set_default_value
end

Class Method Details

.add_global_event_processor(&block) ⇒ void

This method returns an undefined value.

Adds a new global event processor [Proc]. Sometimes we need a global event processor without needing to configure scope. These run before scope event processors.

Parameters:



447
448
449
 
# File 'lib/sentry/scope.rb', line 447

def add_global_event_processor(&block)
  global_event_processors << block
end

.global_event_processors ⇒ Array<Proc>

Returns the global event processors array.

Returns:



437
438
439
 
# File 'lib/sentry/scope.rb', line 437

def global_event_processors
  @global_event_processors ||= []
end

.os_context ⇒ Hash

Returns:



413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/sentry/scope.rb', line 413

def os_context
  @os_context ||=
    begin
      uname = Etc.uname
      {
        name: uname[:sysname] || RbConfig::CONFIG["host_os"],
        version: uname[:version],
        build: uname[:release],
        kernel_version: uname[:version],
        machine: uname[:machine]
      }
    end
end

.runtime_context ⇒ Hash

Returns:



428
429
430
431
432
433
 
# File 'lib/sentry/scope.rb', line 428

def runtime_context
  @runtime_context ||= {
    name: RbConfig::CONFIG["ruby_install_name"],
    version: RUBY_DESCRIPTION || Sentry.sys_command("ruby -v")
  }
end

Instance Method Details

#add_attachment(**opts) ⇒ Object

Add a new attachment to the scope.



376
377
378
379
 
# File 'lib/sentry/scope.rb', line 376

def add_attachment(**opts)
  attachments << (attachment = Attachment.new(**opts))
  attachment
end

#add_breadcrumb(breadcrumb) ⇒ void

This method returns an undefined value.

Adds the breadcrumb to the scope's breadcrumbs buffer.

Parameters:



123
124
125
 
# File 'lib/sentry/scope.rb', line 123

def add_breadcrumb(breadcrumb)
  breadcrumbs.record(breadcrumb)
end

#add_event_processor(&block) ⇒ void

This method returns an undefined value.

Adds a new event processor [Proc] to the scope.

Parameters:



364
365
366
 
# File 'lib/sentry/scope.rb', line 364

def add_event_processor(&block)
  @event_processors << block
end

#apply_to_event(event, hint = nil) ⇒ Event

Applies stored attributes and event processors to the given event.

Parameters:

  • (defaults to: nil)

    the hint data that'll be passed to event processors.

Returns:



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
 
# File 'lib/sentry/scope.rb', line 50

def apply_to_event(event, hint = nil)
  unless event.is_a?(CheckInEvent)
    event.tags = tags.merge(event.tags)
    event.user = user.merge(event.user)
    event.extra = extra.merge(event.extra)
    event.contexts = contexts.merge(event.contexts)
    event.transaction = transaction_name if transaction_name
    event.transaction_info = { source: transaction_source } if transaction_source
    event.fingerprint = fingerprint
    event.level = level
    event.breadcrumbs = breadcrumbs
    event.rack_env = rack_env if rack_env
    event.attachments = attachments
  end

  trace_context = get_trace_context
  dynamic_sampling_context = trace_context.delete(:dynamic_sampling_context)
  event.contexts[:trace] ||= trace_context
  event.dynamic_sampling_context ||= dynamic_sampling_context

  all_event_processors = self.class.global_event_processors + @event_processors

  unless all_event_processors.empty?
    all_event_processors.each do |processor_block|
      event = processor_block.call(event, hint)
    end
  end

  event
end

#apply_to_telemetry(telemetry) ⇒ MetricEvent, LogEvent

A leaner version of apply_to_event that applies to lightweight payloads like Logs and Metrics.

Adds trace_id, span_id, user from the scope and default attributes from configuration.

Parameters:

  • the telemetry event to apply scope context to

Returns:

  • the telemetry event with scope context applied



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/sentry/scope.rb', line 88

def apply_to_telemetry(telemetry)
  # Compare as strings since String and Symbol keys serialize to the same wire key.
  existing_keys = telemetry.attributes.keys.map(&:to_s).to_set

  attributes.each do |key, value|
    next if existing_keys.include?(key)

    telemetry.attributes[key] = value
  end

  trace_context = get_trace_context
  telemetry.trace_id = trace_context[:trace_id]
  telemetry.span_id = trace_context[:span_id]

  configuration = Sentry.configuration
  return telemetry unless configuration

  telemetry.attributes["sentry.sdk.name"] ||= Sentry.sdk_meta["name"]
  telemetry.attributes["sentry.sdk.version"] ||= Sentry.sdk_meta["version"]
  telemetry.attributes["sentry.environment"] ||= configuration.environment if configuration.environment
  telemetry.attributes["sentry.release"] ||= configuration.release if configuration.release
  telemetry.attributes["server.address"] ||= configuration.server_name if configuration.server_name

  unless user.empty?
    telemetry.attributes["user.id"] ||= user[:id] if user[:id]
    telemetry.attributes["user.name"] ||= user[:username] if user[:username]
    telemetry.attributes["user.email"] ||= user[:email] if user[:email]
  end

  telemetry
end

#clear ⇒ void

This method returns an undefined value.

Resets the scope's attributes to defaults.



42
43
44
 
# File 'lib/sentry/scope.rb', line 42

def clear
  set_default_value
end

#clear_breadcrumbs ⇒ void

This method returns an undefined value.

Clears the scope's breadcrumbs buffer



129
130
131
 
# File 'lib/sentry/scope.rb', line 129

def clear_breadcrumbs
  set_new_breadcrumb_buffer
end

#dup ⇒ Scope

Returns:



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/sentry/scope.rb', line 134

def dup
  copy = super
  copy.breadcrumbs = breadcrumbs.dup
  copy.contexts = contexts.deep_dup
  copy.extra = extra.deep_dup
  copy.tags = tags.deep_dup
  copy.user = user.deep_dup
  copy.transaction_name = transaction_name.dup
  copy.transaction_source = transaction_source.dup
  copy.fingerprint = fingerprint.deep_dup
  copy.span = span.deep_dup
  copy.session = session.deep_dup
  copy.propagation_context = propagation_context.deep_dup
  copy.attachments = attachments.dup
  copy.event_processors = event_processors.dup
  copy.attributes = attributes.deep_dup
  copy
end

#generate_propagation_context(env = nil) ⇒ void

This method returns an undefined value.

Generate a new propagation context either from the incoming env headers or from scratch.

Parameters:

  • (defaults to: nil) 


371
372
373
 
# File 'lib/sentry/scope.rb', line 371

def generate_propagation_context(env = nil)
  @propagation_context = PropagationContext.new(self, env)
end

#get_span ⇒ Span?

Returns the associated Span object.

Returns:



334
335
336
 
# File 'lib/sentry/scope.rb', line 334

def get_span
  span
end

#get_trace_context ⇒ Hash

Returns the trace context for this scope. Prioritizes external propagation context (from OTel) over local propagation context.

Returns:



341
342
343
344
345
346
347
348
349
350
 
# File 'lib/sentry/scope.rb', line 341

def get_trace_context
  if span
    span.get_trace_context.merge(dynamic_sampling_context: span.get_dynamic_sampling_context)
  elsif (external_context = Sentry.get_external_propagation_context)
    trace_id, span_id = external_context
    { trace_id: trace_id, span_id: span_id }
  else
    propagation_context.get_trace_context.merge(dynamic_sampling_context: propagation_context.get_dynamic_sampling_context)
  end
end

#get_transaction ⇒ Transaction?

Returns the associated Transaction object.

Returns:



328
329
330
 
# File 'lib/sentry/scope.rb', line 328

def get_transaction
  span.transaction if span
end

#remove_attribute(key) ⇒ void

This method returns an undefined value.

Removes a single attribute from the scope. No-op if the attribute is not set.

Parameters:



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

def remove_attribute(key)
  @attributes.delete(key.to_s)
end

#set_attribute(key, value, unit: nil) ⇒ Hash

Sets a single attribute on the scope.

Parameters:

  • (defaults to: nil)

    an optional measurement unit for the value

Returns:



285
286
287
288
 
# File 'lib/sentry/scope.rb', line 285

def set_attribute(key, value, unit: nil)
  value = { value: value, unit: unit } unless unit.nil?
  set_attributes(key => value)
end

#set_attributes(attributes_hash) ⇒ Hash

Updates the scope's attributes by merging with the old value.

Parameters:

Returns:



274
275
276
277
278
 
# File 'lib/sentry/scope.rb', line 274

def set_attributes(attributes_hash)
  check_argument_type!(attributes_hash, Hash)
  attributes_hash.each { |key, value| @attributes[key.to_s] = value }
  @attributes
end

#set_context(key, value) ⇒ Hash

Adds a new key-value pair to current contexts.

Parameters:

Returns:



266
267
268
269
 
# File 'lib/sentry/scope.rb', line 266

def set_context(key, value)
  check_argument_type!(value, Hash)
  set_contexts(key => value)
end

#set_contexts(contexts_hash) ⇒ Hash

Updates the scope's contexts attribute by merging with the old value.

Parameters:

Returns:



254
255
256
257
258
259
260
261
262
263
 
# File 'lib/sentry/scope.rb', line 254

def set_contexts(contexts_hash)
  check_argument_type!(contexts_hash, Hash)
  contexts_hash.values.each do |val|
    check_argument_type!(val, Hash)
  end

  @contexts.merge!(contexts_hash) do |key, old, new|
    old.merge(new)
  end
end

#set_extra(key, value) ⇒ Hash

Adds a new key-value pair to current extras.

Parameters:

Returns:



233
234
235
 
# File 'lib/sentry/scope.rb', line 233

def set_extra(key, value)
  set_extras(key => value)
end

#set_extras(extras_hash) ⇒ Hash

Updates the scope's extras attribute by merging with the old value.

Parameters:

Returns:



224
225
226
227
 
# File 'lib/sentry/scope.rb', line 224

def set_extras(extras_hash)
  check_argument_type!(extras_hash, Hash)
  @extra.merge!(extras_hash)
end

#set_fingerprint(fingerprint) ⇒ Array

Sets the scope's fingerprint attribute.

Parameters:

Returns:



355
356
357
358
359
 
# File 'lib/sentry/scope.rb', line 355

def set_fingerprint(fingerprint)
  check_argument_type!(fingerprint, Array)

  @fingerprint = fingerprint
end

#set_level(level) ⇒ void

This method returns an undefined value.

Sets the scope's level attribute.

Parameters:



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

def set_level(level)
  @level = level
end

#set_rack_env(env) ⇒ Hash

Sets the scope's rack_env attribute.

Parameters:

Returns:



204
205
206
207
 
# File 'lib/sentry/scope.rb', line 204

def set_rack_env(env)
  env = env || {}
  @rack_env = env
end

#set_session(session) ⇒ void

This method returns an undefined value.

Sets the currently active session on the scope.

Parameters:



316
317
318
 
# File 'lib/sentry/scope.rb', line 316

def set_session(session)
  @session = session
end

#set_span(span) ⇒ Span

Sets the scope's span attribute.

Parameters:

Returns:



212
213
214
215
 
# File 'lib/sentry/scope.rb', line 212

def set_span(span)
  check_argument_type!(span, Span)
  @span = span
end

#set_tag(key, value) ⇒ Hash

Adds a new key-value pair to current tags.

Parameters:

Returns:



247
248
249
 
# File 'lib/sentry/scope.rb', line 247

def set_tag(key, value)
  set_tags(key => value)
end

#set_tags(tags_hash) ⇒ Hash

Updates the scope's tags attribute by merging with the old value.

Parameters:

Returns:



238
239
240
241
 
# File 'lib/sentry/scope.rb', line 238

def set_tags(tags_hash)
  check_argument_type!(tags_hash, Hash)
  @tags.merge!(tags_hash)
end

#set_transaction_name(transaction_name, source: :custom) ⇒ void

This method returns an undefined value.

Appends a new transaction name to the scope. The "transaction" here does not refer to Transaction objects.

Parameters:



308
309
310
311
 
# File 'lib/sentry/scope.rb', line 308

def set_transaction_name(transaction_name, source: :custom)
  @transaction_name = transaction_name
  @transaction_source = source
end

#set_user(user_hash) ⇒ Hash

Sets the scope's user attribute.

Parameters:

Returns:



218
219
220
221
 
# File 'lib/sentry/scope.rb', line 218

def set_user(user_hash)
  check_argument_type!(user_hash, Hash)
  @user = user_hash
end

#transaction_source_low_quality? ⇒ Boolean

These are high cardinality and thus bad.

Returns:



322
323
324
 
# File 'lib/sentry/scope.rb', line 322

def transaction_source_low_quality?
  transaction_source == :url
end

#update_from_options(contexts: nil, extra: nil, tags: nil, user: nil, level: nil, fingerprint: nil, attachments: nil, **options) ⇒ Array

Updates the scope's data from the given options.

Parameters:

  • (defaults to: nil)
  • (defaults to: nil)
  • (defaults to: nil)
  • (defaults to: nil)
  • (defaults to: nil)
  • (defaults to: nil)
  • (defaults to: nil)

Returns:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/sentry/scope.rb', line 180

def update_from_options(
  contexts: nil,
  extra: nil,
  tags: nil,
  user: nil,
  level: nil,
  fingerprint: nil,
  attachments: nil,
  **options
)
  self.contexts.merge!(contexts) if contexts
  self.extra.merge!(extra) if extra
  self.tags.merge!(tags) if tags
  self.user = user if user
  self.level = level if level
  self.fingerprint = fingerprint if fingerprint

  # Returns unsupported option keys so we can notify users.
  options.keys
end

#update_from_scope(scope) ⇒ void

This method returns an undefined value.

Updates the scope's data from a given scope.

Parameters:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/sentry/scope.rb', line 156

def update_from_scope(scope)
  self.breadcrumbs = scope.breadcrumbs
  self.contexts = scope.contexts
  self.extra = scope.extra
  self.tags = scope.tags
  self.user = scope.user
  self.transaction_name = scope.transaction_name
  self.transaction_source = scope.transaction_source
  self.fingerprint = scope.fingerprint
  self.span = scope.span
  self.propagation_context = scope.propagation_context
  self.attachments = scope.attachments
  self.attributes = scope.attributes
end