Skip to content

Commit 6818450

Browse files
authored
feat(ruby): add job extensions and shared instrumentation (#3129)
* feat(ruby): add job extensions and shared instrumentation Closes #3117 Closes #3123 * ref(ruby): clarify job extension error data precedence Document and name the caller > scope > extension merge in merged_error_data, and skip capture when the SDK is not initialized. * perf(ruby): avoid per-call hash allocations in job extension hooks * fix(ruby): Keep running the job when scope data cannot be applied hook_hash only coerces the top-level value scope_data returns, and apply_scope_data ran outside safely. A tags, extra, user or context value that is not a Hash made the Scope setters raise ArgumentError from start_job, so the job never ran. Apply the scope data through safely, as the other hooks are, so the failure is logged and the job runs.
1 parent bfdb1b9 commit 6818450

3 files changed

Lines changed: 810 additions & 0 deletions

File tree

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

Lines changed: 1 addition & 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/extension"
3435

3536
[
3637
"sentry/rake",
Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
# frozen_string_literal: true
2+
3+
module Sentry
4+
module JobExtensions
5+
# Base class for extensions that let a background-job backend enrich Sentry's
6+
# job integrations. A backend gem subclasses it and overrides the hooks it can
7+
# supply; jobs are opaque to Sentry and only interpreted by the extension.
8+
class Extension
9+
include LoggingHelper
10+
11+
PUBLISH_OP = "queue.publish"
12+
PROCESS_OP = "queue.process"
13+
14+
MESSAGING_DATA_ATTRIBUTES = {
15+
system: Span::DataConventions::MESSAGING_SYSTEM,
16+
message_id: Span::DataConventions::MESSAGING_MESSAGE_ID,
17+
destination: Span::DataConventions::MESSAGING_DESTINATION_NAME,
18+
receive_latency: Span::DataConventions::MESSAGING_MESSAGE_RECEIVE_LATENCY,
19+
retry_count: Span::DataConventions::MESSAGING_MESSAGE_RETRY_COUNT
20+
}.freeze
21+
22+
EMPTY_HASH = {}.freeze
23+
private_constant :EMPTY_HASH
24+
25+
EMPTY_ERROR_DATA = { contexts: {}.freeze, tags: {}.freeze, extra: {}.freeze }.freeze
26+
private_constant :EMPTY_ERROR_DATA
27+
28+
# The extension's name, used in SDK log messages.
29+
# @return [Symbol]
30+
attr_reader :name
31+
32+
# Creates an extension. Raises ArgumentError if the name is not a Symbol.
33+
#
34+
# @param name [Symbol]
35+
# @param integration [Module] the integration that captures the job's exceptions
36+
# @param origin [String] the origin of the job's spans
37+
def initialize(name:, integration:, origin:)
38+
raise ArgumentError, "job extension name must be a Symbol, got #{name.inspect}" unless name.is_a?(Symbol)
39+
40+
@name = name
41+
@integration = integration
42+
@origin = origin
43+
end
44+
45+
# Wraps enqueueing a job in a `queue.publish` span.
46+
#
47+
# @param job [Object]
48+
# @yieldreturn [Object] the result of enqueueing the job
49+
# @return [Object] the block's result
50+
def instrument_enqueue(job:, **context, &enqueue)
51+
return enqueue.call unless safely("decide whether to record the producer span", fallback: true) { record_publish_span?(job: job, **context) }
52+
53+
Sentry.with_child_span(op: PUBLISH_OP) do |span|
54+
if span
55+
span.set_description(safely("describe the producer span") { publish_description(job: job, **context) })
56+
span.set_origin(safely("set the producer span origin", fallback: @origin) { publish_span_origin(job: job, **context) })
57+
set_messaging_data(span, hook_hash("collect the producer messaging data") { publish_messaging_data(job: job, **context) })
58+
end
59+
60+
enqueue.call
61+
end
62+
end
63+
64+
# Prepares the scope for performing the job and starts its `queue.process`
65+
# transaction, continuing the trace the job was enqueued in.
66+
#
67+
# @param scope [Scope]
68+
# @param job [Object]
69+
# @return [Transaction, nil]
70+
def start_job(scope:, job:, **context)
71+
data = hook_hash("collect the scope data") { scope_data(job: job, **context) }
72+
safely("apply the scope data") { apply_scope_data(scope, data) }
73+
74+
job_name = safely("name the transaction") { transaction_name(job: job, **context) }
75+
scope.set_transaction_name(job_name, source: :task) if job_name
76+
77+
trace_headers = hook_hash("extract trace headers") { extract_trace_headers(job: job, **context) }
78+
origin = safely("set the transaction origin", fallback: @origin) { span_origin(job: job, **context) }
79+
transaction = start_transaction(scope, trace_headers, origin)
80+
return unless transaction
81+
82+
scope.set_span(transaction)
83+
set_messaging_data(transaction, hook_hash("collect the messaging data") { messaging_data(job: job, **context) })
84+
transaction
85+
end
86+
87+
# Finishes the job's transaction with the given status.
88+
#
89+
# @param transaction [Transaction, nil]
90+
# @param status [Integer]
91+
# @return [void]
92+
def finish_job(transaction:, status:)
93+
return if !transaction || transaction.timestamp
94+
95+
transaction.set_http_status(status)
96+
transaction.finish
97+
end
98+
99+
# Captures an exception raised by the job, enriched with the extension's error data.
100+
#
101+
# @param job [Object]
102+
# @param exception [Exception]
103+
# @return [Event, nil]
104+
def capture_exception(job:, exception:, contexts: {}, tags: {}, extra: {}, **context)
105+
return unless Sentry.initialized?
106+
107+
data = safely("collect the error data", fallback: EMPTY_ERROR_DATA) { normalized_error_data(error_data(job: job, exception: exception, **context)) }
108+
capturing_integration = safely("pick the capturing integration", fallback: @integration) { integration(job: job, **context) }
109+
110+
capturing_integration.capture_exception(exception, **merged_error_data(data, contexts: contexts, tags: tags, extra: extra))
111+
end
112+
113+
# Runs a hook, logging its failure and returning `fallback` instead of raising.
114+
#
115+
# @param context [String] what the hook does, used in the log message
116+
# @return [Object]
117+
def safely(context, fallback: nil)
118+
yield
119+
rescue StandardError => e
120+
log_failure(context, e)
121+
fallback
122+
end
123+
124+
##### Hooks #####
125+
#
126+
# Called by job integrations with the job and any extra keyword context.
127+
# Hooks must not mutate the objects they are given.
128+
129+
# Returns whether to record a `queue.publish` span when the job is enqueued.
130+
#
131+
# @param job [Object]
132+
# @return [Boolean]
133+
def record_publish_span?(job:, **)
134+
true
135+
end
136+
137+
# Returns data to apply to the scope the job is performed in.
138+
#
139+
# @param job [Object]
140+
# @return [Hash] with optional `:contexts`, `:tags`, `:extra` and `:user`
141+
def scope_data(job:, **)
142+
{}
143+
end
144+
145+
# Returns data to add to the event captured for a failed job. Data already on
146+
# the scope or passed explicitly by the job integration takes precedence.
147+
#
148+
# @param job [Object]
149+
# @param exception [Exception]
150+
# @return [Hash] with optional `:contexts`, `:tags` and `:extra`
151+
def error_data(job:, exception:, **)
152+
{}
153+
end
154+
155+
# Returns whether the backend will retry the failed job.
156+
#
157+
# @param job [Object]
158+
# @return [Boolean]
159+
def will_retry?(job:, **)
160+
false
161+
end
162+
163+
# Returns whether to capture the job's exception. By default only when the
164+
# backend won't retry the job.
165+
#
166+
# @param job [Object]
167+
# @param exception [Exception]
168+
# @return [Boolean]
169+
def report_exception?(job:, exception:, **context)
170+
!will_retry?(job: job, exception: exception, **context)
171+
end
172+
173+
# Returns whether to capture an exception that the job integration's own
174+
# retry mechanism retries, so the backend never sees it.
175+
#
176+
# @param job [Object]
177+
# @param exception [Exception]
178+
# @return [Boolean]
179+
def report_retried_exception?(job:, exception:, **)
180+
false
181+
end
182+
183+
# Returns the backend's job payload carrying the trace propagation headers.
184+
#
185+
# @param job [Object]
186+
# @param payload [Object]
187+
# @param headers [Hash{String => String}]
188+
# @return [Object] a payload of the same class as the one given
189+
def inject_trace_headers(job:, payload:, headers:, **)
190+
payload
191+
end
192+
193+
# Returns the trace propagation headers the job carries, so that performing
194+
# it continues the trace it was enqueued in.
195+
#
196+
# @param job [Object]
197+
# @return [Hash{String => String}]
198+
def extract_trace_headers(job:, **)
199+
{}
200+
end
201+
202+
# Returns messaging attributes for the job's spans.
203+
#
204+
# @param job [Object]
205+
# @return [Hash] with optional `:system`, `:message_id`, `:destination`,
206+
# `:receive_latency` and `:retry_count`
207+
def messaging_data(job:, **)
208+
{}
209+
end
210+
211+
# Returns messaging attributes for the `queue.publish` span. Defaults to
212+
# {#messaging_data}.
213+
#
214+
# @param job [Object]
215+
# @return [Hash]
216+
def publish_messaging_data(job:, **context)
217+
messaging_data(job: job, **context)
218+
end
219+
220+
# Returns the name of the job's transaction. Defaults to the job's class name.
221+
#
222+
# @param job [Object]
223+
# @return [String, nil]
224+
def transaction_name(job:, **)
225+
job.class.name
226+
end
227+
228+
# Returns the description of the `queue.publish` span. Defaults to the job's class name.
229+
#
230+
# @param job [Object]
231+
# @return [String, nil]
232+
def publish_description(job:, **)
233+
job.class.name
234+
end
235+
236+
# Returns the origin of the job's transaction. Defaults to the extension's origin.
237+
#
238+
# @param job [Object]
239+
# @return [String]
240+
def span_origin(job:, **)
241+
@origin
242+
end
243+
244+
# Returns the origin of the `queue.publish` span. Defaults to {#span_origin}.
245+
#
246+
# @param job [Object]
247+
# @return [String]
248+
def publish_span_origin(job:, **context)
249+
span_origin(job: job, **context)
250+
end
251+
252+
# Returns the integration that captures the job's exceptions. Defaults to
253+
# the extension's integration.
254+
#
255+
# @param job [Object]
256+
# @return [Module]
257+
def integration(job:, **)
258+
@integration
259+
end
260+
261+
private
262+
263+
def hook_hash(description)
264+
safely(description, fallback: EMPTY_HASH) do
265+
value = yield
266+
value.nil? ? EMPTY_HASH : Hash(value)
267+
end
268+
end
269+
270+
def start_transaction(scope, trace_headers, origin)
271+
options = {
272+
name: scope.transaction_name,
273+
source: scope.transaction_source,
274+
op: PROCESS_OP,
275+
origin: origin
276+
}
277+
278+
if trace_headers.empty?
279+
Sentry.start_transaction(**options)
280+
else
281+
Sentry.start_transaction(transaction: Sentry.continue_trace(trace_headers, **options), **options)
282+
end
283+
end
284+
285+
def apply_scope_data(scope, data)
286+
scope.set_contexts(data[:contexts]) if data[:contexts]
287+
scope.set_tags(data[:tags]) if data[:tags]
288+
scope.set_extras(data[:extra]) if data[:extra]
289+
scope.set_user(data[:user]) if data[:user]
290+
end
291+
292+
def set_messaging_data(span, data)
293+
MESSAGING_DATA_ATTRIBUTES.each do |key, attribute|
294+
span.set_data(attribute, data[key]) if data.key?(key)
295+
end
296+
end
297+
298+
def normalized_error_data(data)
299+
data = Hash(data)
300+
301+
{
302+
contexts: Hash(data[:contexts]).transform_values { |context| Hash(context) },
303+
tags: Hash(data[:tags]),
304+
extra: Hash(data[:extra])
305+
}
306+
end
307+
308+
# Builds the capture options so that the caller's contexts, tags and extra
309+
# take precedence over the scope's, and the scope's over the extension's.
310+
#
311+
# Every value passed to capture_exception becomes event data, and
312+
# Scope#apply_to_event lets event data beat scope data. It also merges
313+
# contexts by name, so an event context replaces the scope context of the
314+
# same name entirely. The extension's tags and extra therefore leave out
315+
# keys the scope already has, and each extension context absorbs the scope
316+
# context of the same name before the caller's values are merged on top.
317+
def merged_error_data(data, contexts:, tags:, extra:)
318+
scope = Sentry.get_current_scope
319+
320+
merged_contexts = contexts_with_scope_values(data[:contexts], scope.contexts).merge(contexts)
321+
options = {
322+
extra: without_scope_keys(data[:extra], scope.extra).merge(extra),
323+
tags: without_scope_keys(data[:tags], scope.tags).merge(tags),
324+
hint: { background: false }
325+
}
326+
options[:contexts] = merged_contexts unless merged_contexts.empty?
327+
options
328+
end
329+
330+
def without_scope_keys(values, scope_values)
331+
values.reject { |key, _value| scope_values.key?(key) }
332+
end
333+
334+
def contexts_with_scope_values(contexts, scope_contexts)
335+
contexts.to_h { |name, context| [name, context.merge(scope_contexts.fetch(name, {}))] }
336+
end
337+
338+
def log_failure(context, error)
339+
log_error("Job extension #{name.inspect} failed to #{context}", error)
340+
end
341+
342+
def sdk_logger
343+
Sentry.sdk_logger if Sentry.initialized?
344+
end
345+
end
346+
end
347+
end

0 commit comments

Comments
 (0)