Wrapping

guides/error_handling.md

@@ -2,37 +2,42 @@
 
 This page guides you through handling errors in Oban.
 
-The basics: jobs can fail in expected or unexpected ways. To mark a job as failed, you can return `{:error, reason}` from a worker's [`perform/1` callback](`c:Oban.Worker.perform/1`), as documented in the `t:Oban.Worker.result/0` type. A job can also fail because of unexpected raised errors or exits.
+The basics: jobs can fail in expected or unexpected ways. To mark a job as failed, you can return
+`{:error, reason}` from a worker's [`perform/1` callback](`c:Oban.Worker.perform/1`), as
+documented in the `t:Oban.Worker.result/0` type. A job can also fail because of unexpected raised
+errors or exits.
 
-In any case, when a job fails the details of the failure are recorded in the `errors` array on the `Oban.Job` struct.
+In any case, when a job fails the details of the failure are recorded in the `errors` array on the
+`Oban.Job` struct.
 
 ## Error Details
 
-Oban stores execution errors as a list of maps (`t:Oban.Job.errors/0`). Each error contains the following keys:
+Oban stores execution errors as a list of maps (`t:Oban.Job.errors/0`). Each error contains the
+following keys:
 
   * `:at` — The UTC timestamp when the error occurred at
   * `:attempt` — The attempt number when the error occurred
   * `:error` — A *formatted* error message and stacktrace
 
-See the [Instrumentation docs](instrumentation.html) for an example of
-integrating with external error reporting systems.
+See the [Instrumentation docs](instrumentation.html) for an example of integrating with external
+error reporting systems.
 
 ## Retries
 
-When a job fails and the number of execution attempts is below the configured
-`max_attempts` limit for that job, the job will automatically be retried in the future.
+When a job fails and the number of execution attempts is below the configured `max_attempts` limit
+for that job, the job will automatically be retried in the future. If the number of failures
+reaches `max_attempts`, the job gets **discarded**.
 
-The retry delay has an exponential backoff, meaning the job's second attempt
-will be after 16s, third after 31s, fourth after 1m 36s, and so on.
+The retry delay has an exponential backoff, meaning the job's second attempt will be after 16s,
+third after 31s, fourth after 1m 36s, and so on.
 
-See the `Oban.Worker` documentation on "Customizing Backoff" for alternative
-backoff strategies.
+See the `Oban.Worker` documentation on "Customizing Backoff" for alternative backoff strategies.
 
 ### Limiting Retries
 
-By default, jobs are retried up to 20 times. The number of retries is controlled
-by the `:max_attempts` value, which can be set at the **worker** or **job** level. For
-example, to instruct a worker to discard jobs after three failures:
+By default, jobs are retried up to 20 times. The number of retries is controlled by the
+`:max_attempts` value, which can be set at the **worker** or **job** level. For example, to
+instruct a worker to discard jobs after three failures:
 
 ```elixir
 use Oban.Worker, queue: :limited, max_attempts: 3

guides/instrumentation.md

@@ -1,7 +1,8 @@
 # Instrumentation, Error Reporting, and Logging
 
-Oban provides integration with [Telemetry][telemetry], a dispatching library for
-metrics and instrumentation. It is easy to report Oban metrics to any backend by attaching to Telemetry events prefixed with `:oban`.
+Oban provides integration with [Telemetry][telemetry], a dispatching library for metrics and
+instrumentation. It is easy to report Oban metrics to any backend by attaching to Telemetry events
+prefixed with `:oban`.
 
 Here is an example of an unstructured log handler:
 
@@ -19,7 +20,8 @@ defmodule MyApp.ObanLogger do
 end
 ```
 
-Attach the handler to success and failure events in your application's `c:Application.start/2` callback (usually in `lib/my_app/application.ex`):
+Attach the handler to success and failure events in your application's `c:Application.start/2`
+callback (usually in `lib/my_app/application.ex`):
 
 ```elixir
 def start(_type, _args) do
@@ -35,21 +37,20 @@ def start(_type, _args) do
 end
 ```
 
-The `Oban.Telemetry` module provides a robust structured logger that handles all
-of Oban's telemetry events. As in the example above, attach it within your
-application module:
+The `Oban.Telemetry` module provides a robust structured logger that handles all of Oban's
+telemetry events. As in the example above, attach it within your application module:
 
 ```elixir
 :ok = Oban.Telemetry.attach_default_logger()
 ```
 
-For more details on the default structured logger and information on event
-metadata see docs for the `Oban.Telemetry` module.
+For more details on the default structured logger and information on event metadata see docs for
+the `Oban.Telemetry` module.
 
 ## Reporting Errors
 
-Another great use of execution data and instrumentation is error reporting. Here is an example of an event handler module that
-integrates with [Honeybadger][honeybadger] to report job failures:
+Another great use of execution data and instrumentation is error reporting. Here is an example of
+an event handler module that integrates with [Honeybadger][honeybadger] to report job failures:
 
 ```elixir
 defmodule MyApp.ErrorReporter do
@@ -71,11 +72,13 @@ end
 MyApp.ErrorReporter.attach()
 ```
 
-You can use exception events to send error reports to Sentry, AppSignal, Honeybadger, Rollbar, or any other application monitoring platform.
+You can use exception events to send error reports to Sentry, AppSignal, Honeybadger, Rollbar, or
+any other application monitoring platform.
 
 ### Built-in Reporting
 
-Some error-reporting and application-monitoring services support reporting Oban errors out of the box:
+Some error-reporting and application-monitoring services support reporting Oban errors out of the
+box:
 
   - Sentry — [Oban integration documentation][sentry-integration]
   - AppSignal — [Oban integration documentation][appsignal-integration]