Skip to content

Commit bf6aff9

Browse files
committed
feat(ruby): add job extensions and shared instrumentation
Closes #3117 Closes #3123
1 parent 0c76f63 commit bf6aff9

3 files changed

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

0 commit comments

Comments
 (0)