Weave Code
Sentry Monolog Adapter Laravel Package
macpaw/sentry-monolog-adapter
A Monolog handler that forwards log records to Sentry as events and breadcrumbs, making it easy to capture errors and context from Laravel and PHP applications. Configurable log levels and simple integration with existing logging stacks.
Symfony Sentry Monolog Adapter
Frequently asked questions about Sentry Monolog Adapter
- How do I install macpaw/sentry-monolog-adapter with Composer?
- Install it with composer require macpaw/sentry-monolog-adapter. Because the package is a thin adapter rather than a framework bundle, you may also need to bind or pass a Sentry\ClientInterface (or HubInterface) instance into the handler yourself. Check the repository README for the exact constructor signature and any suggested service provider wiring before you register it in your logging stack.
- Does this package work with Laravel, or is it only for Symfony?
- Despite the Symfony label in the package description, the code is effectively framework-agnostic: it converts Monolog records into Sentry events and calls the Sentry client directly. That means it can run inside Laravel, standalone PHP workers, CLI consumers, or shared internal packages. It was extracted from a Symfony stack, so Laravel-specific semantics such as report filtering and Octane lifecycle handling were not design targets and should be validated yourself.
- Which Monolog and Sentry SDK versions does it support?
- The adapter exists because Sentry removed Sentry\Monolog\Handler from the core SDK, so it has to track both Monolog 3.x and Sentry SDK 4.x or 5.x. Open composer.json and confirm the pinned constraints for monolog/monolog, sentry/sentry, and the minimum PHP version before you adopt it. Do not assume compatibility with older Monolog 1.x or 2.x releases or with future Sentry majors until the constraints are updated.
- How do I register a Sentry Monolog handler in Laravel's config/logging.php?
- Laravel's Monolog log driver accepts handler and handler_with keys, so you can point a channel at the adapter class and pass the Sentry client as a constructor argument. You will typically add a small service provider binding so the handler resolves the correct Sentry client from the container. Keep a separate channel for Sentry rather than replacing your existing file or stack channels, so local debugging output is preserved.
- Should I use this adapter instead of sentry/sentry-laravel?
- For a standard Laravel application, no. sentry/sentry-laravel already ships and wires a Monolog handler, so adopting this package replaces a vendor-maintained component with a single-maintainer one. It is justified when you are on Sentry SDK 4+ without the Laravel SDK, when you maintain a framework-agnostic package that must log to Sentry from both Laravel apps and standalone workers, or when you need custom record-to-event mapping the official handler does not expose. If none of those apply, stay on sentry/sentry-laravel.
- How does the adapter map a Monolog record to a Sentry event?
- The handler converts each Monolog LogRecord into a Sentry Event and calls captureEvent on the injected client, with lower-severity records typically sent as breadcrumbs instead of full events. Read the source to confirm the exact mapping: whether context is promoted to extra, whether an exception in the record's context is attached as a Throwable, and whether channel and level are preserved as tags. Pay attention to extra filtering, because unserializable objects or large payloads can bloat or break event serialization.
- Do log levels and channels still filter records before Sentry is called?
- Level filtering depends on the handler exposing an isHandling() gate that matches the configured threshold, so verify that method exists before relying on it. If isHandling() is missing or permissive, every record reaching the handler will be serialized and sent, which adds latency even when Sentry would discard the event. Channel-level filtering in config/logging.php still short-circuits before the handler runs, so route Sentry through a dedicated channel if you want strict control.
- Is the handler safe for Octane, Horizon and queue:work processes?
- Long-running processes require correct reset() and close() behavior so state and buffered events are flushed between requests and jobs. The adapter is small, but it is worth checking the source for those methods and for any static state before running it under Octane or Horizon. If they are missing, wrap or extend the handler and flush the Sentry client yourself at the end of each lifecycle hook.
- Can a Sentry outage break my application logging?
- Because the handler delegates transport to the Sentry client you inject, request latency and timeouts follow that client's configuration rather than the adapter itself. Check whether the handler catches exceptions thrown by captureEvent; if it does not, a Sentry API failure can propagate into your logging path. In production, configure a sane timeout and consider wrapping the handler in a try/catch or a dedicated logging channel so Sentry problems never break application logging.
- Is macpaw/sentry-monolog-adapter actively maintained, and what are the alternatives?
- This is a low-gravity project with around 25 stars and essentially no dependents, so breakage will likely be reported only by you. Check the commit history since the 2025-08 release and whether it has responded to Sentry SDK majors, then weigh the supply-chain review of license, provenance, and CI against the cost of writing an equivalent handler in-house. For Laravel-only use the safest alternative remains sentry/sentry-laravel; for shared framework-agnostic packages, a small in-house handler is often cheaper to own.
Weaver
How can I help you explore Laravel packages today?