|
| 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 |
0 commit comments