Skip to content

Commit 8c91ba4

Browse files
committed
feat(ruby): add job extensions and shared instrumentation
1 parent 475a5c5 commit 8c91ba4

10 files changed

Lines changed: 1115 additions & 0 deletions

File tree

‎sentry-ruby/lib/sentry-ruby.rb‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
require "sentry/cron/slug"
3232
require "sentry/vernier/profiler"
3333
require "sentry/metrics"
34+
require "sentry/job_extensions"
3435

3536
[
3637
"sentry/rake",
@@ -65,6 +66,8 @@ module Sentry
6566
exception_locals_tp
6667
].freeze
6768

69+
JOB_EXTENSIONS = JobExtensions::Registry.new
70+
6871
class << self
6972
# @!visibility private
7073
def exception_locals_tp
@@ -150,6 +153,27 @@ def register_integration(name, version)
150153
integrations[name.to_s] = meta
151154
end
152155

156+
##### Job Extensions #####
157+
158+
# Returns the process-wide registry of background-job extensions.
159+
#
160+
# @return [JobExtensions::Registry]
161+
def job_extensions
162+
JOB_EXTENSIONS
163+
end
164+
165+
# Registers a background-job extension built by a backend gem. It can be
166+
# called at load time, before or after {Sentry.init}.
167+
#
168+
# @param extension [JobExtensions::Extension] an extension instance,
169+
# constructed with its own configuration and collaborators
170+
# @return [JobExtensions::Extension] the registered extension
171+
# @raise [ArgumentError] if the argument is not a {JobExtensions::Extension}
172+
# instance, or an extension with the same name is already registered
173+
def register_job_extension(extension)
174+
job_extensions.register(extension)
175+
end
176+
153177
##### Method Delegation #####
154178

155179
extend Forwardable
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# frozen_string_literal: true
2+
3+
require "sentry/job_extensions/extension"
4+
require "sentry/job_extensions/registry"
5+
require "sentry/job_extensions/instrumentation"
6+
require "sentry/job_extensions/consumer"
7+
require "sentry/job_extensions/producer"
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# frozen_string_literal: true
2+
3+
module Sentry
4+
module JobExtensions
5+
# @api private
6+
class Consumer < Instrumentation
7+
OP_NAME = "queue.process"
8+
9+
def apply_scope_data(scope, job)
10+
data = registry.for(job).scope_data(job: job)
11+
scope.set_contexts(data[:contexts]) if data[:contexts]
12+
scope.set_tags(data[:tags]) if data[:tags]
13+
scope.set_extras(data[:extra]) if data[:extra]
14+
scope.set_user(data[:user]) if data[:user]
15+
end
16+
17+
def start_transaction(scope, job, trace_headers: {})
18+
extension = registry.for(job)
19+
options = {
20+
name: scope.transaction_name,
21+
source: scope.transaction_source,
22+
op: OP_NAME,
23+
origin: extension.span_origin(job: job)
24+
}
25+
26+
transaction = if trace_headers.empty?
27+
Sentry.start_transaction(**options)
28+
else
29+
Sentry.start_transaction(transaction: Sentry.continue_trace(trace_headers, **options), **options)
30+
end
31+
return unless transaction
32+
33+
scope.set_span(transaction)
34+
safely(extension, "record the messaging data") do
35+
set_messaging_data(transaction, extension.messaging_data(job: job))
36+
set_retry_count(transaction, extension, job)
37+
end
38+
39+
transaction
40+
end
41+
42+
def finish_transaction(transaction, status)
43+
return if !transaction || transaction.timestamp
44+
45+
transaction.set_http_status(status)
46+
transaction.finish
47+
end
48+
49+
def report_exception?(job, exception)
50+
registry.for(job).report_exception?(job: job, exception: exception)
51+
end
52+
53+
def report_retried_exception?(job, exception)
54+
registry.for(job).report_retried_exception?(job: job, exception: exception)
55+
end
56+
57+
def capture_exception(job, exception, contexts: {}, tags: {}, extra: {})
58+
extension = registry.for(job)
59+
error_data = additive_error_data(extension.error_data(job: job, exception: exception))
60+
61+
options = {
62+
extra: error_data[:extra].merge(matching_keys(extra, error_data[:extra])),
63+
tags: error_data[:tags].merge(matching_keys(tags, error_data[:tags])),
64+
hint: { background: false }
65+
}
66+
contexts = error_data[:contexts].merge(matching_keys(contexts, error_data[:contexts]))
67+
options[:contexts] = contexts unless contexts.empty?
68+
69+
extension.integration(job: job).capture_exception(exception, **options)
70+
end
71+
72+
private
73+
74+
def additive_error_data(data)
75+
scope = Sentry.get_current_scope
76+
77+
{
78+
contexts: matching_keys(data.fetch(:contexts, {}), scope.contexts).to_h do |name, context|
79+
scope_context = scope.contexts.fetch(name, {})
80+
context = matching_keys(context, scope_context)
81+
[name, context.merge(scope_context)]
82+
end,
83+
tags: matching_keys(data.fetch(:tags, {}), scope.tags).reject { |key, _value| scope.tags.key?(key) },
84+
extra: matching_keys(data.fetch(:extra, {}), scope.extra).reject { |key, _value| scope.extra.key?(key) }
85+
}
86+
end
87+
88+
def matching_keys(data, reference)
89+
keys = reference.keys.to_h { |key| [key.to_s, key] }
90+
data.transform_keys { |key| keys.fetch(key.to_s, key) }
91+
end
92+
end
93+
end
94+
end
Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# frozen_string_literal: true
2+
3+
module Sentry
4+
module JobExtensions
5+
# Base class for objects that let a background-job backend enrich Sentry's
6+
# job integrations.
7+
#
8+
# A backend gem subclasses this class, receives everything the extension
9+
# depends on (configuration, collaborators) through its constructor, and
10+
# registers one instance with {Sentry.register_job_extension}. Sentry treats
11+
# jobs as opaque objects: only the extension interprets the job it is given.
12+
#
13+
# @example Defining and registering an extension
14+
# class MyBackend::SentryJobExtension < Sentry::JobExtensions::Extension
15+
# def initialize(config:)
16+
# super(name: "my_backend")
17+
# @config = config
18+
# end
19+
#
20+
# def handles?(job)
21+
# job.class.queue_adapter_name.to_s == "my_backend"
22+
# end
23+
# end
24+
#
25+
# Sentry.register_job_extension(MyBackend::SentryJobExtension.new(config: MyBackend.config))
26+
class Extension
27+
# The extension's unique name. No two registered extensions can share it.
28+
#
29+
# @return [String]
30+
attr_reader :name
31+
32+
# @param name [String, Symbol] a non-empty name identifying the backend,
33+
# stored as a frozen String
34+
# @raise [ArgumentError] if the name is not a non-empty String or Symbol
35+
def initialize(name:)
36+
unless (name.is_a?(String) || name.is_a?(Symbol)) && !name.empty?
37+
raise ArgumentError, "job extension name must be a non-empty String or Symbol, got #{name.inspect}"
38+
end
39+
40+
@name = name.to_s.dup.freeze
41+
end
42+
43+
# Whether this extension handles the given job. Override it to claim
44+
# the jobs run by the extension's backend.
45+
#
46+
# If this method raises a StandardError, the failure is logged through the
47+
# SDK logger and the extension is treated as not handling the job.
48+
#
49+
# @param job [Object] the job, as passed by the job integration
50+
# @return [Boolean] false unless overridden
51+
def handles?(job)
52+
false
53+
end
54+
55+
# @!group Hooks
56+
#
57+
# Hooks are called directly by job integrations on the extension that
58+
# handles the job. Each hook maps its input to data and must not mutate
59+
# the objects it is given; the job integration applies the returned
60+
# data. Override only the hooks the backend can supply.
61+
62+
# Data to apply to the scope the job is performed in. Called before the
63+
# job is performed. A supplied user replaces the user the job
64+
# integration sets on the scope.
65+
#
66+
# @param job [Object] the job being performed
67+
# @return [Hash] a Hash with any of the keys +:contexts+ (a Hash of
68+
# context name to Hash), +:tags+ (a Hash), +:extra+ (a Hash) and
69+
# +:user+ (a Hash). Empty by default.
70+
def scope_data(job:)
71+
{}
72+
end
73+
74+
# Data to add to the event captured for an exception raised by the job.
75+
# Called when the job fails and its exception is about to be captured.
76+
#
77+
# Supplied tags and extra never replace a key already on the job's
78+
# scope. Each supplied context is merged into the scope's context of the
79+
# same name, keeping values already on the scope. Data the job integration captures
80+
# explicitly with the exception takes precedence over this data.
81+
#
82+
# @param job [Object] the job that failed
83+
# @param exception [Exception] the exception raised by the job
84+
# @return [Hash] a Hash with any of the keys +:contexts+ (a Hash of
85+
# context name to Hash), +:tags+ (a Hash) and +:extra+ (a Hash).
86+
# Empty by default.
87+
def error_data(job:, exception:)
88+
{}
89+
end
90+
91+
# The backend's own retry state for the job. Called when the job is
92+
# enqueued, before it is performed, and when it fails. The hook may be
93+
# called several times for the same attempt, so it must not change any
94+
# state.
95+
#
96+
# @param job [Object] the job being enqueued, performed, or that failed
97+
# @return [Hash] a Hash with the keys +:count+ (a non-negative Integer,
98+
# the number of retries already attempted) and +:will_retry+ (true or
99+
# false, whether the backend will retry the failed attempt). By
100+
# default +{ count: 0, will_retry: false }+.
101+
def retry_info(job:)
102+
{ count: 0, will_retry: false }
103+
end
104+
105+
# Whether the job integration captures the exception raised by the job.
106+
# Called when the job fails. Declining to capture does not change the
107+
# job's outcome: the job still fails and its transaction is still
108+
# finished as failed.
109+
#
110+
# @param job [Object] the job that failed
111+
# @param exception [Exception] the exception raised by the job
112+
# @return [Boolean] true to capture the exception. By default true
113+
# only when +:will_retry+ from #retry_info is false.
114+
def report_exception?(job:, exception:)
115+
!retry_info(job: job)[:will_retry]
116+
end
117+
118+
# Whether the job integration captures an exception that the job
119+
# integration's own retry mechanism rescued and retries, so the backend
120+
# never sees it. Called when the job integration schedules the retry.
121+
#
122+
# @param job [Object] the job being retried
123+
# @param exception [Exception] the exception the job raised
124+
# @return [Boolean] true to capture the exception. False by default.
125+
def report_retried_exception?(job:, exception:)
126+
false
127+
end
128+
129+
# Adds trace propagation headers to the backend's job payload. Called
130+
# when a job is enqueued.
131+
#
132+
# @param payload [Object] the backend's job payload
133+
# @param headers [Hash{String => String}] the trace propagation headers
134+
# to carry, such as +sentry-trace+ and +baggage+
135+
# @return [Object] a payload of the same class as the one given,
136+
# carrying the headers. By default the given payload, unchanged.
137+
def inject_trace_headers(job:, payload:, headers:)
138+
payload
139+
end
140+
141+
# Reads the trace propagation headers carried by the backend's job
142+
# payload. Called before the job is performed, to continue the trace
143+
# started when it was enqueued.
144+
#
145+
# @param payload [Object] the backend's job payload
146+
# @return [Hash{String => String}] the headers the payload carries. The
147+
# job continues the trace they describe; an empty Hash continues no
148+
# trace. Empty by default.
149+
def extract_trace_headers(job:, payload:)
150+
{}
151+
end
152+
153+
# Data for the messaging attributes of the consumer span created when
154+
# the job is performed. Also used for the producer span created when the
155+
# job is enqueued unless #publish_messaging_data is overridden.
156+
#
157+
# @param job [Object] the job being enqueued or performed
158+
# @return [Hash] a Hash with any of the keys +:system+ (a String naming
159+
# the backend), +:message_id+ (a String), +:destination+ (a String,
160+
# such as the queue name), +:receive_latency+ (a Numeric, the
161+
# milliseconds between enqueueing and the start of the job). Empty by
162+
# default.
163+
def messaging_data(job:)
164+
{}
165+
end
166+
167+
# Data for the messaging attributes of the producer span created when
168+
# the job is enqueued.
169+
#
170+
# @param job [Object] the job being enqueued
171+
# @return [Hash] a Hash with the keys documented on #messaging_data. By
172+
# default the result of #messaging_data.
173+
def publish_messaging_data(job:)
174+
messaging_data(job: job)
175+
end
176+
177+
# @!endgroup
178+
end
179+
end
180+
end
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# frozen_string_literal: true
2+
3+
module Sentry
4+
module JobExtensions
5+
# @api private
6+
class Instrumentation
7+
include LoggingHelper
8+
9+
MESSAGING_DATA_ATTRIBUTES = {
10+
system: Span::DataConventions::MESSAGING_SYSTEM,
11+
message_id: Span::DataConventions::MESSAGING_MESSAGE_ID,
12+
destination: Span::DataConventions::MESSAGING_DESTINATION_NAME,
13+
receive_latency: Span::DataConventions::MESSAGING_MESSAGE_RECEIVE_LATENCY
14+
}.freeze
15+
16+
attr_reader :registry
17+
18+
def initialize(registry: Sentry.job_extensions)
19+
@registry = registry
20+
end
21+
22+
private
23+
24+
def safely(extension, context, fallback: nil)
25+
yield
26+
rescue StandardError => e
27+
log_error("Job extension #{extension.name.inspect} failed to #{context}", e)
28+
fallback
29+
end
30+
31+
def set_messaging_data(span, data)
32+
data.slice(*MESSAGING_DATA_ATTRIBUTES.keys).each do |key, value|
33+
span.set_data(MESSAGING_DATA_ATTRIBUTES[key], value)
34+
end
35+
end
36+
37+
def set_retry_count(span, extension, job)
38+
span.set_data(Span::DataConventions::MESSAGING_MESSAGE_RETRY_COUNT, extension.retry_info(job: job)[:count])
39+
end
40+
41+
def sdk_logger
42+
Sentry.sdk_logger if Sentry.initialized?
43+
end
44+
end
45+
end
46+
end

0 commit comments

Comments
 (0)