Kendo Error Tracker Laravel Package

Getting Started

kendo is an error tracker for Laravel: you install it, let it capture exceptions/reports, and it groups reports by an anonymised user_hash so you can see how many distinct users a bug affects. Day-to-day you will mostly touch two things: the config file and the ErrorTracker singleton.

First steps:

1. Install and publish config, then set your project key / DSN in .env as documented in the README.
2. Confirm reports land by throwing a test exception from a route or artisan tinker.
3. Identify who "a user" is for your app — that is the first real decision. By default kendo derives user_hash from the authenticated user's id. If your ids are not globally unique (see multi-tenant below), fix that before you rely on affected-user counts.
4. If you run one database per tenant, register a tenant resolver once, ideally in a service provider's boot():

app(\Kendo\ErrorTracker::class)->scopeUserHashUsing(
    fn (): int|string|null => tenant()->getKey() // or whatever identifies the tenant
);

The first real use case is triage: open kendo, sort by affected users rather than raw occurrences, and work down the list. That ordering is only trustworthy once user_hash is correct, which is exactly what v0.2.1 addresses.

Implementation Patterns

Centralise tenant scoping in a provider. Register scopeUserHashUsing in a dedicated service provider rather than in middleware or a controller. The resolver is called lazily at report time, so it can read whatever the current request's tenant context is without you having to pass it around. Do not register it per-request — you will stack resolvers and get confusing results.

Treat the resolver as a pure read. It should only read ambient state (current tenant, current request) and return a scalar. Anything with side effects — DB writes, HTTP calls, queue dispatches — will run inside exception handling, where failures are hard to observe and can mask the original error.

Return null deliberately for single-tenant or public/unauthenticated contexts. In v0.2.1 null means "use the v0.2.0 hash exactly", so a single-tenant app that adds a resolver returning null in some paths keeps byte-identical hashes. This makes it safe to roll out the resolver in a mixed codebase — multi-tenant workers get scoped hashes, single-tenant paths stay unchanged.

Use integer or non-empty string tenant keys only. The contract is int|string|null. Empty strings, 0-as-empty-string, models, and UUID objects coerced badly are all footguns. Cast explicitly: fn () => (string) tenant()->getKey() or return null when there is no tenant.

Watch for id collisions in shared-database multi-tenancy too. The fix targets one-database-per-tenant, where ids restart. If you use a single database with a tenant column and composite keys, ids are already unique per user row and you likely do not need a resolver — adding one only fragments hashes for users who legitimately span tenants.

Verify the count before and after rollout. Compare kendo's affected-user count for a known bug before and after deploying the resolver. In a two-tenant app where both tenants have a user id 42, the count should go from 1 to 2. That single check validates the whole change.

Gotchas and Tips

• Hashes change the moment you deploy the resolver. Existing reports keep their old hashes; new reports use the tenant-scoped hash. Expect a discontinuity in per-user grouping across the deploy boundary. This is not a bug, but it will look like one if you are watching a dashboard during the release.
• The tenant key is hashed into the key, never transmitted. If you are doing a privacy review, note that scopeUserHashUsing does not widen your data footprint — the tenant identifier stays local. Return values that are themselves sensitive (e.g. an API token) are still a bad idea, because they become part of the hash input.
• A throwing resolver silently sends no hash. The report is still delivered, but it will be unattributed. That failure mode is quiet by design — no exception, just a report with no user. If affected-user counts suddenly drop to zero in one environment, suspect the resolver throwing (missing tenant binding, null tenant in a queued job, etc.) before you suspect kendo.
• Invalid return types are also silently dropped. Returning '', a float, or an object produces no hash rather than an error. Type-hint your closure and add a test that asserts the resolver returns int|string|null for each of your tenant states.
• Queued jobs and console commands have no tenant context. Exception reports from jobs are a common source of null returns. Either bind the tenant in the job's handle() and clear it in finally, or accept that job-originated reports are unattributed.
• Debugging hash mismatches: log the resolver's return value locally (not the user id) and compare against what kendo stores. If two reports you expect to group are separate, check that the resolver returns the same tenant key in both paths — a resolver that reads from a different source depending on request type is the usual cause.
• Extension point to prefer over patching: scopeUserHashUsing is the supported hook. Do not reach into kendo's internals to rewrite hashes after the fact; you will lose the guarantee that the tenant key never leaves your app.