Skip to content

Commit f9f7593

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

3 files changed

Lines changed: 705 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: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
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 and receives everything the extension
9+
# depends on (configuration, collaborators) through its constructor. Sentry
10+
# treats jobs as opaque objects: only the extension interprets the job it is
11+
# given.
12+
class Extension
13+
include LoggingHelper
14+
15+
PUBLISH_OP = "queue.publish"
16+
PROCESS_OP = "queue.process"
17+
18+
MESSAGING_DATA_ATTRIBUTES = {
19+
system: Span::DataConventions::MESSAGING_SYSTEM,
20+
message_id: Span::DataConventions::MESSAGING_MESSAGE_ID,
21+
destination: Span::DataConventions::MESSAGING_DESTINATION_NAME,
22+
receive_latency: Span::DataConventions::MESSAGING_MESSAGE_RECEIVE_LATENCY,
23+
retry_count: Span::DataConventions::MESSAGING_MESSAGE_RETRY_COUNT
24+
}.freeze
25+
26+
# The extension's name, used to identify it in SDK log messages.
27+
#
28+
# @return [String]
29+
attr_reader :name
30+
31+
# @param name [String, Symbol] a non-empty name identifying the backend,
32+
# stored as a frozen String
33+
# @raise [ArgumentError] if the name is not a non-empty String or Symbol
34+
def initialize(name:, integration:, origin:)
35+
unless (name.is_a?(String) || name.is_a?(Symbol)) && !name.empty?
36+
raise ArgumentError, "job extension name must be a non-empty String or Symbol, got #{name.inspect}"
37+
end
38+
39+
@name = name.to_s.dup.freeze
40+
@integration = integration
41+
@origin = origin
42+
end
43+
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+
def start_job(scope:, job:, **context)
59+
apply_scope_data(scope, safely("collect the scope data", fallback: {}) { Hash(scope_data(job: job, **context)) })
60+
61+
job_name = safely("name the transaction") { transaction_name(job: job, **context) }
62+
scope.set_transaction_name(job_name, source: :task) if job_name
63+
64+
trace_headers = safely("extract trace headers", fallback: {}) { Hash(extract_trace_headers(job: job, **context)) }
65+
origin = safely("set the transaction origin", fallback: @origin) { span_origin(job: job, **context) }
66+
transaction = start_transaction(scope, trace_headers, origin)
67+
return unless transaction
68+
69+
scope.set_span(transaction)
70+
set_messaging_data(transaction, safely("collect the messaging data", fallback: {}) { Hash(messaging_data(job: job, **context)) })
71+
transaction
72+
end
73+
74+
def finish_job(transaction:, status:)
75+
return if !transaction || transaction.timestamp
76+
77+
transaction.set_http_status(status)
78+
transaction.finish
79+
end
80+
81+
def capture_exception(job:, exception:, contexts: {}, tags: {}, extra: {}, **context)
82+
data = safely("collect the error data", fallback: {}) { Hash(error_data(job: job, exception: exception, **context)) }
83+
capturing_integration = safely("pick the capturing integration", fallback: @integration) { integration(job: job, **context) }
84+
85+
capturing_integration.capture_exception(exception, **merged_error_data(data, contexts: contexts, tags: tags, extra: extra))
86+
end
87+
88+
def safely(context, fallback: nil)
89+
yield
90+
rescue StandardError => e
91+
log_failure(context, e)
92+
fallback
93+
end
94+
95+
# @!group Hooks
96+
#
97+
# Hooks are called directly by job integrations on the extension they
98+
# are given. Each hook maps its input to data and must not mutate
99+
# the objects it is given; the job integration applies the returned
100+
# data. Override only the hooks the backend can supply.
101+
102+
def record_publish_span?(job:, **)
103+
true
104+
end
105+
106+
# Data to apply to the scope the job is performed in. Called before the
107+
# job is performed. A supplied user replaces the user the job
108+
# integration sets on the scope.
109+
#
110+
# @param job [Object] the job being performed
111+
# @return [Hash] a Hash with any of the keys +:contexts+ (a Hash of
112+
# context name to Hash), +:tags+ (a Hash), +:extra+ (a Hash) and
113+
# +:user+ (a Hash). Empty by default.
114+
def scope_data(job:, **)
115+
{}
116+
end
117+
118+
# Data to add to the event captured for an exception raised by the job.
119+
# Called when the job fails and its exception is about to be captured.
120+
#
121+
# Supplied tags and extra never replace a key already on the job's
122+
# scope. Each supplied context is merged into the scope's context of the
123+
# same name, keeping values already on the scope. Data the job integration captures
124+
# explicitly with the exception takes precedence over this data.
125+
#
126+
# @param job [Object] the job that failed
127+
# @param exception [Exception] the exception raised by the job
128+
# @return [Hash] a Hash with any of the keys +:contexts+ (a Hash of
129+
# context name to Hash), +:tags+ (a Hash) and +:extra+ (a Hash).
130+
# Empty by default.
131+
def error_data(job:, exception:, **)
132+
{}
133+
end
134+
135+
# Whether the backend will retry the failed attempt.
136+
#
137+
# @param job [Object] the job that failed
138+
# @return [Boolean] false by default.
139+
def will_retry?(job:, **)
140+
false
141+
end
142+
143+
# Whether the job integration captures the exception raised by the job.
144+
# Called when the job fails. Declining to capture does not change the
145+
# job's outcome: the job still fails and its transaction is still
146+
# finished as failed.
147+
#
148+
# @param job [Object] the job that failed
149+
# @param exception [Exception] the exception raised by the job
150+
# @return [Boolean] true to capture the exception. By default true
151+
# only when #will_retry? is false.
152+
def report_exception?(job:, exception:, **context)
153+
!will_retry?(job: job, exception: exception, **context)
154+
end
155+
156+
# Whether the job integration captures an exception that the job
157+
# integration's own retry mechanism rescued and retries, so the backend
158+
# never sees it. Called when the job integration schedules the retry.
159+
#
160+
# @param job [Object] the job being retried
161+
# @param exception [Exception] the exception the job raised
162+
# @return [Boolean] true to capture the exception. False by default.
163+
def report_retried_exception?(job:, exception:, **)
164+
false
165+
end
166+
167+
# Adds trace propagation headers to the backend's job payload. Called
168+
# when a job is enqueued.
169+
#
170+
# @param payload [Object] the backend's job payload
171+
# @param headers [Hash{String => String}] the trace propagation headers
172+
# to carry, such as +sentry-trace+ and +baggage+
173+
# @return [Object] a payload of the same class as the one given,
174+
# carrying the headers. By default the given payload, unchanged.
175+
def inject_trace_headers(job:, payload:, headers:, **)
176+
payload
177+
end
178+
179+
# Reads the trace propagation headers carried by the job. Called before
180+
# the job is performed, to continue the trace started when it was
181+
# enqueued.
182+
#
183+
# @param job [Object] the job being performed
184+
# @return [Hash{String => String}] the headers the job carries. The
185+
# job continues the trace they describe; an empty Hash continues no
186+
# trace. Empty by default.
187+
def extract_trace_headers(job:, **)
188+
{}
189+
end
190+
191+
# Data for the messaging attributes of the consumer span created when
192+
# the job is performed. Also used for the producer span created when the
193+
# job is enqueued unless #publish_messaging_data is overridden.
194+
#
195+
# @param job [Object] the job being enqueued or performed
196+
# @return [Hash] a Hash with any of the keys +:system+ (a String naming
197+
# the backend), +:message_id+ (a String), +:destination+ (a String,
198+
# such as the queue name), +:receive_latency+ (a Numeric, the
199+
# milliseconds between enqueueing and the start of the job) and
200+
# +:retry_count+ (an Integer, the retries already attempted). Empty by
201+
# default.
202+
def messaging_data(job:, **)
203+
{}
204+
end
205+
206+
# Data for the messaging attributes of the producer span created when
207+
# the job is enqueued.
208+
#
209+
# @param job [Object] the job being enqueued
210+
# @return [Hash] a Hash with the keys documented on #messaging_data. By
211+
# default the result of #messaging_data.
212+
def publish_messaging_data(job:, **context)
213+
messaging_data(job: job, **context)
214+
end
215+
216+
def transaction_name(job:, **)
217+
job.class.name
218+
end
219+
220+
def publish_description(job:, **)
221+
job.class.name
222+
end
223+
224+
def span_origin(job:, **)
225+
@origin
226+
end
227+
228+
def publish_span_origin(job:, **context)
229+
span_origin(job: job, **context)
230+
end
231+
232+
def integration(job:, **)
233+
@integration
234+
end
235+
236+
# @!endgroup
237+
238+
private
239+
240+
def start_transaction(scope, trace_headers, origin)
241+
options = {
242+
name: scope.transaction_name,
243+
source: scope.transaction_source,
244+
op: PROCESS_OP,
245+
origin: origin
246+
}
247+
248+
if trace_headers.empty?
249+
Sentry.start_transaction(**options)
250+
else
251+
Sentry.start_transaction(transaction: Sentry.continue_trace(trace_headers, **options), **options)
252+
end
253+
end
254+
255+
def apply_scope_data(scope, data)
256+
scope.set_contexts(data[:contexts]) if data[:contexts]
257+
scope.set_tags(data[:tags]) if data[:tags]
258+
scope.set_extras(data[:extra]) if data[:extra]
259+
scope.set_user(data[:user]) if data[:user]
260+
end
261+
262+
def set_messaging_data(span, data)
263+
data.slice(*MESSAGING_DATA_ATTRIBUTES.keys).each do |key, value|
264+
span.set_data(MESSAGING_DATA_ATTRIBUTES[key], value)
265+
end
266+
end
267+
268+
def merged_error_data(data, contexts:, tags:, extra:)
269+
scope = Sentry.get_current_scope
270+
271+
merged_contexts = data.fetch(:contexts, {}).to_h { |context_name, context| [context_name, context.merge(scope.contexts.fetch(context_name, {}))] }.merge(contexts)
272+
options = {
273+
extra: data.fetch(:extra, {}).reject { |key, _value| scope.extra.key?(key) }.merge(extra),
274+
tags: data.fetch(:tags, {}).reject { |key, _value| scope.tags.key?(key) }.merge(tags),
275+
hint: { background: false }
276+
}
277+
options[:contexts] = merged_contexts unless merged_contexts.empty?
278+
options
279+
end
280+
281+
def log_failure(context, error)
282+
log_error("Job extension #{name.inspect} failed to #{context}", error)
283+
end
284+
285+
def sdk_logger
286+
Sentry.sdk_logger if Sentry.initialized?
287+
end
288+
end
289+
end
290+
end

0 commit comments

Comments
 (0)