Weave Code
Eagle Eye Laravel Package
dotswan/eagle-eye
dotswan/eagle-eye is a Laravel package for gaining visibility into your application's activity. It offers a lightweight, configurable way to track and inspect users and events, helping you monitor behavior and debug issues faster.
At a glance
Frequently asked questions about Eagle Eye
- How do I install dotswan/eagle-eye in a Laravel application?
- Install it with Composer using the beta constraint, for example composer require dotswan/eagle-eye:^1.0@beta, and make sure your Composer minimum-stability or per-package stability flags allow the beta channel. Pin the exact beta version in composer.json and commit your lockfile rather than relying on a floating constraint, since the package is still pre-1.0. The release notes verify clean-room installs on fresh Laravel 12 and 13 applications with PHP 8.4 and 8.5.
- Which Laravel and PHP versions does dotswan/eagle-eye support?
- The verified runtime matrix is Laravel 12 and 13 on PHP 8.4 and 8.5, tested with lowest dependencies, MySQL and Loki. Laravel 10 and 11, PHP 8.2 and 8.3, and other database or observability backends are not verified by the release notes. If you maintain an older Laravel estate, treat eagle-eye as a spike and confirm support with the maintainers rather than assuming CI coverage applies to your stack.
- Does dotswan/eagle-eye work with Postgres or databases other than MySQL?
- Only MySQL is covered by the verified integration signal in the release notes, so Postgres-first shops should not assume parity. The package description does not advertise a multi-database abstraction, and the audit trail likely depends on MySQL-specific behaviour or types. Run a pilot against your actual database before committing, and test migrations, indexing and retention on a realistic dataset.
- How does the buffered batch flush work in dotswan/eagle-eye?
- Eagle-eye captures events into an in-memory buffer and flushes them to storage in batches rather than writing per event, which keeps instrumentation cheap on hot request paths. The exact flush triggers, maximum buffer size and retention window are not documented in the material available here. Ask the maintainers directly what triggers a flush, whether it fires on request termination, and what the worst-case time window is for losing an unflushed batch.
- Can dotswan/eagle-eye silently drop events?
- Batch buffering means a failure during flush can affect multiple captured events at once, and the recent fix for anonymous model classes poisoning an entire batch shows this is a pipeline-isolation concern rather than just a formatting bug. That specific defect is fixed, but the failure class is not proven eliminated. There is no evidence in the release notes of a dead-letter path or a drop counter, so clarify with the maintainers whether discarded batches are still silent.
- What does the budget pipe in dotswan/eagle-eye actually budget?
- The package uses a budget or sampling pipe in its capture pipeline, but the release notes do not state whether it budgets events, bytes, time or cost. It is also unclear whether events rejected by the pipe are observable in any metric or log. Before production use, confirm the units of the budget, the default thresholds, and how to detect when sampling is silently discarding the audit records you rely on.
- Does zero-code capture cover queue workers, console commands and Octane?
- The zero-code instrumentation model is described as request-scoped, with trace correlation identifiers such as http.request, model.created and auth.login. Queue workers, console commands, Horizon and Octane are not verified in the release notes, and long-lived workers behave differently from per-request lifecycles. If your audit surface includes background jobs, validate buffer flushing and trace propagation in a queue worker before relying on eagle-eye as your audit trail.
- Is dotswan/eagle-eye production-ready?
- Treat it as promising but unproven for production-critical audit use. It is a pre-1.0 beta, the maintainers explicitly call out API instability, and the capture pipeline's drop, retry and dead-letter semantics are not documented. A sensible approach is a contained pilot in a non-critical area, with a clear fallback for audit records that must never be lost.
- How does the erasure barrier and identity digesting work in eagle-eye?
- Eagle-eye uses an erasure barrier that digests actor and subject identities, so stored audit records reference a digest rather than raw personal data. The open question is whether that digest is stable and collision-resistant across upgrades, and what happens to erasure requests targeting digests created before beta.2. If identities are sanitised before digesting, the digest for affected models can change, so plan for historical correlation and erasure handling before you go live.
- How should I pin eagle-eye and plan a beta-to-1.0 upgrade?
- Pin the exact beta version in composer.json, commit the lockfile, and avoid deep customisation of internal classes because the API may change before 1.0. Limit your integration to documented configuration and public extension points, and check that config caching and service-provider registration behave correctly in your deployment. Agree an upgrade contract with the maintainers or budget explicit rework time for the beta-to-1.0 transition.
Weaver
How can I help you explore Laravel packages today?