Eagle Eye Laravel Package

Getting Started

Install on the beta channel and pin it, since 1.0.0 is still pre-release:

composer require dotswan/eagle-eye:^1.0@beta

You will likely also need "minimum-stability": "beta" (or a prefer-stable + explicit constraint) in composer.json.

First steps, in order:

1. Publish and read the config file. It is the whole product surface: which event families are captured (http.request, model.created, auth.login, …), the trace-id propagation settings, the sampling budget, the redaction rules, and the driver (Loki, MySQL, or a local sink). Publish it before writing any code — most "why isn't this captured?" questions are answered there.
2. Run a smoke test that produces a shared trace id. This is exactly what the maintainers verify on each release: hit a route, create a model, log in, then confirm all three events land with the same trace id. If that works, the plumbing (middleware, buffer, exporter) is healthy.
3. Point it at a local sink first. Ship to stdout/file in local and only wire Loki/MySQL in staging, so you are not debugging your observability tool through your observability tool.

The first real use case is almost always: "I need to correlate an HTTP request with the model writes and the auth event it caused, without adding Log::info calls to every controller." That is the zero-code capture path — middleware plus Eloquent/auth event listeners — and it is the part worth validating before you tune anything else.

Implementation Patterns

Zero-code capture as the default, opt-in per family. Leave model/auth/HTTP capture enabled globally and disable noisy families per environment (model.updated on a high-write table will dwarf everything else). Prefer config-level toggles over removing listeners, so the trace id stays consistent across whatever remains.

Treat the trace id as the contract. Everything downstream — log correlation, the erasure barrier, the budget pipe — keys off it. Propagate it through queued jobs and outbound HTTP calls explicitly; a job dispatched without the trace id produces an orphaned model.created that looks like a bug in the package but is a gap in your dispatch path.

Redaction belongs in the sanitiser layer, not in your models. Actor and subject identities are sanitised before the erasure barrier digests them. If you add a custom identity (a tenant, an API client), register its sanitiser alongside the built-in ones rather than mutating the attribute in a model accessor — accessor-level changes leak into your application logic and are invisible to the barrier.

Budget the volume, don't sample blindly. The budget pipe is your cost control. Set a per-environment budget and, critically, make sure "dropped by budget" is distinguishable from "never captured" in your own dashboards — otherwise a sampling change looks identical to a regression.

Integration testing pattern. Assert on captured events rather than on the destination: run the action under test, then assert the emitted event set and that the trace ids match. Include an anonymous model subclass (new class extends Model) in at least one test — it is an explicitly covered regression case and a cheap guard against the class of bug fixed in beta.2.

Driver abstraction is your escape hatch. Keep Loki/MySQL specifics out of application code; if you find yourself importing a driver class into a service, the config is doing too little.

Gotchas and Tips

• Silent batch loss is the headline failure mode. In beta.1 an anonymous model class with control characters in its generated name caused the entire buffered flush — including unrelated auth.login entries — to be discarded with no trace. If telemetry vanishes wholesale rather than partially, suspect the buffer/flush path, not your listeners. Upgrade to beta.2 and, regardless, emit a low-volume canary event you can alert on.
• Anonymous model classes are now safe but still worth avoiding as tracked subjects. Their names contain characters that are meaningless as identifiers; sanitisation makes them harmless, not useful. Reach for a named class or an explicit subject resolver when you actually need to query by subject later.
• Ordering matters in the erasure barrier. Sanitisation must precede digesting. Any custom identity hook you add that hashes or fingerprints before sanitising will reintroduce the same class of instability — and produce identifiers that change between requests.
• Buffered flush is all-or-nothing. One malformed payload costs you the batch. Keep payloads small, avoid stuffing large serialised relations into captured properties, and watch for flush-size configuration that trades latency against blast radius.
• Loki label cardinality. Model IDs and raw actor IDs are values, not labels. Putting them in labels is the fastest way to melt a Loki instance and is not something the package can prevent for you.
• Beta API churn. The maintainers state the API may change before 1.0.0. Pin the exact beta, read the upgrade notes on each bump, and isolate any direct use of package classes behind a thin internal wrapper so a rename is a one-file change.
• Platform floor: verified on Laravel 12/13 and PHP 8.4/8.5. Older Laravel/PHP combinations are untested — check before assuming an install works on an LTS you have not migrated yet.
• Debugging checklist, in order: config published and cached-cleared → trace id present on the request → event family enabled → budget not exhausted → sanitiser not throwing (a throwing sanitiser can take the flush with it) → driver reachable.