Class: Sentry::Scope

Inherits:
Object
  • Object
show all
Includes:
ArgumentCheckingHelper, CallbackHelper
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:

  • max_breadcrumbs (Integer) (defaults to: nil) —

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



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

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:

  • block (Proc) 


451
452
453
 
# File 'lib/sentry/scope.rb', line 451

def add_global_event_processor(&block)
  global_event_processors << block
end

.global_event_processors ⇒ Array<Proc>

Returns the global event processors array.

Returns:

  • (Array<Proc>) 


441
442
443
 
# File 'lib/sentry/scope.rb', line 441

def global_event_processors
  @global_event_processors ||= []
end

.os_context ⇒ Hash

Returns:

  • (Hash) 


417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/sentry/scope.rb', line 417

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:

  • (Hash) 


432
433
434
435
436
437
 
# File 'lib/sentry/scope.rb', line 432

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.



380
381
382
383
 
# File 'lib/sentry/scope.rb', line 380

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:



127
128
129
 
# File 'lib/sentry/scope.rb', line 127

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:

  • block (Proc) 


368
369
370
 
# File 'lib/sentry/scope.rb', line 368

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:

  • event (Event)
  • hint (Hash) (defaults to: nil) —

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

Returns:



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

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 = safe_dispatch_callback("event_processor", processor_block, [event, hint])
      return unless event
    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:

Returns:



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
119
120
121
122
 
# File 'lib/sentry/scope.rb', line 90

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

  sdk_meta = telemetry.respond_to?(:integration_meta) ? telemetry.integration_meta : nil
  sdk_meta ||= Sentry.sdk_meta
  telemetry.attributes["sentry.sdk.name"] ||= sdk_meta[:name] || sdk_meta["name"]
  telemetry.attributes["sentry.sdk.version"] ||= sdk_meta[:version] || 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.



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

def clear
  set_default_value
end

#clear_breadcrumbs ⇒ void

This method returns an undefined value.

Clears the scope's breadcrumbs buffer



133
134
135
 
# File 'lib/sentry/scope.rb', line 133

def clear_breadcrumbs
  set_new_breadcrumb_buffer
end

#dup ⇒ Scope

Returns:



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/sentry/scope.rb', line 138

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:

  • env (Hash, nil) (defaults to: nil) 


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

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

#get_span ⇒ Span?

Returns the associated Span object.

Returns:



338
339
340
 
# File 'lib/sentry/scope.rb', line 338

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:

  • (Hash) 


345
346
347
348
349
350
351
352
353
354
 
# File 'lib/sentry/scope.rb', line 345

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:



332
333
334
 
# File 'lib/sentry/scope.rb', line 332

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:

  • key (String, Symbol) 


297
298
299
 
# File 'lib/sentry/scope.rb', line 297

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:

  • key (String, Symbol)
  • value (Object)
  • unit (String, Symbol, nil) (defaults to: nil) —

    an optional measurement unit for the value

Returns:

  • (Hash) 


289
290
291
292
 
# File 'lib/sentry/scope.rb', line 289

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:

  • attributes_hash (Hash)

Returns:

  • (Hash) 


278
279
280
281
282
 
# File 'lib/sentry/scope.rb', line 278

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:

  • key (String, Symbol)
  • value (Object)

Returns:

  • (Hash) 


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

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:

  • contexts (Hash)

Returns:

  • (Hash) 


258
259
260
261
262
263
264
265
266
267
 
# File 'lib/sentry/scope.rb', line 258

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:

  • key (String, Symbol)
  • value (Object)

Returns:

  • (Hash) 


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

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:

  • extras (Hash)

Returns:

  • (Hash) 


228
229
230
231
 
# File 'lib/sentry/scope.rb', line 228

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:

  • fingerprint (Array)

Returns:

  • (Array) 


359
360
361
362
363
 
# File 'lib/sentry/scope.rb', line 359

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:

  • level (String, Symbol) 


304
305
306
 
# File 'lib/sentry/scope.rb', line 304

def set_level(level)
  @level = level
end

#set_rack_env(env) ⇒ Hash

Sets the scope's rack_env attribute.

Parameters:

  • env (Hash)

Returns:

  • (Hash) 


208
209
210
211
 
# File 'lib/sentry/scope.rb', line 208

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:



320
321
322
 
# File 'lib/sentry/scope.rb', line 320

def set_session(session)
  @session = session
end

#set_span(span) ⇒ Span

Sets the scope's span attribute.

Parameters:

Returns:



216
217
218
219
 
# File 'lib/sentry/scope.rb', line 216

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:

  • key (String, Symbol)
  • value (Object)

Returns:

  • (Hash) 


251
252
253
 
# File 'lib/sentry/scope.rb', line 251

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:

  • tags (Hash)

Returns:

  • (Hash) 


242
243
244
245
 
# File 'lib/sentry/scope.rb', line 242

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:

  • transaction_name (String) 


312
313
314
315
 
# File 'lib/sentry/scope.rb', line 312

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:

  • user (Hash)

Returns:

  • (Hash) 


222
223
224
225
 
# File 'lib/sentry/scope.rb', line 222

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:

  • (Boolean) 


326
327
328
 
# File 'lib/sentry/scope.rb', line 326

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:

  • contexts (Hash) (defaults to: nil)
  • extra (Hash) (defaults to: nil)
  • tags (Hash) (defaults to: nil)
  • user (Hash) (defaults to: nil)
  • level (String, Symbol) (defaults to: nil)
  • fingerprint (Array) (defaults to: nil)
  • attachments (Array<Attachment>) (defaults to: nil)

Returns:

  • (Array) 


184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/sentry/scope.rb', line 184

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:



160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/sentry/scope.rb', line 160

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