Download the PHP package systemverk/laravel-api-usage without Composer

Laravel API Usage

Self-hosted, actor-aware API usage analytics for Laravel.

Track who uses your API, which endpoints they use, how much they use them, and how they perform — without an external observability platform.

What problem does this solve?

Most Laravel applications can tell you that their API is busy. Far fewer can answer "how much did this customer use us last month", "which endpoint is getting slower", or "which API key is generating all the 422s" — the questions that show up in support threads, capacity planning and invoicing.

This package answers them from your own database. Every request is buffered in Redis after the response has been sent, flushed to SQL in batches by a scheduled command, and rolled up into per-actor, per-endpoint daily and monthly summaries you query through a small PHP API.

When should I use this?

These are different jobs, not competitors. This package deliberately does not ship a dashboard, enforce quotas, trace across services, or record request bodies. See Out of scope.

Requirements

Quick Start

1. Install

2. Run migrations

The package ships its migrations and loads them automatically — there is nothing to publish. Two tables are created:

• api_usage_requests — one row per recorded request
• api_usage_summaries — daily and monthly aggregates

3. Make sure Redis is configured

Requests are appended to a Redis list before being flushed to SQL.

• A connection must exist under database.redis (or database.redis.clusters)
• The package uses the default connection unless told otherwise
• Override with API_USAGE_REDIS_CONNECTION

If the configured connection does not exist, the middleware records nothing rather than throwing — usage tracking never takes an application down.

4. Run the scheduler

The commands are registered on the scheduler automatically, but they only run if your scheduler runs.

5. Check that it is working

Architecture

The important property is where the line falls: nothing between the request arriving and the response leaving touches SQL. Actor resolution, endpoint resolution, serialization and the two Redis round trips all happen in terminate(), after the client already has its response.

Failure is handled the same way at every step. A minute buffer is claimed with RENAMENX into a private processing key, tracked in a Redis set, and only deleted once the database write is confirmed — so a crashed or failed flush is retried on the next run instead of silently losing entries. See What can be lost.

Terminology

Actor

An entity usage is attributed to. The package never assumes it is a User:

user:42 · organization:12 · tenant:acme · api_key:abc123 · service_account:billing · guest

An actor has a type and an id, both stored as first-class columns, plus an actor_key (type:id) for convenient grouping. Ids are normalized to strings, so integer and UUID keys behave identically.

Credential

Which key the actor used — a personal access token, an API key, an OAuth client. This is a second dimension, orthogonal to the actor: it lets you keep "the Acme team" as the actor while still breaking usage down per token.

Endpoint

The logical Laravel endpoint, not the concrete URL. The endpoint key prefers GET:api.orders.show over GET:/api/orders/123, so resource ids never fragment your analytics. The raw path is still stored on each row for debugging.

Actor Tracking

Out of the box, usage is attributed to the authenticated user, and to guest when there is none. That is one class:

Because Sanctum lets any model be tokenable, this already gives you team- or organization-level attribution when your tokens belong to a Team.

Custom actor resolver

Anything else is a resolver of your own:

Resolvers are built through the container, so constructor injection works. Returning null means do not record this request at all — that is how track_guests drops anonymous traffic.

Per-credential attribution

credential_id is filled by a callback you register. The package never guesses:

The same closure can live in actor.credential_resolver in the config file instead, at the cost of making the config uncacheable. A resolver registered in code wins.

Endpoint Tracking

RouteEndpointResolver is the default and needs no configuration. For unusual routing setups, implement ResolvesUsageEndpoint and point endpoint.resolver at it. Unlike actor resolution it never returns null: a request that matched no route is still recorded, keyed by its path.

Querying

Three entry points, all sharing the same period selection and filters.

Periods

today() · yesterday() · thisWeek() · lastDays(int $days) · thisMonth() · lastMonth() · between(DateTimeInterface $from, DateTimeInterface $to)

All dates are UTC and both ends of a range are inclusive. Without a period, a query covers the current month.

Filters

forActor(UsageActor $actor) · forActorType(string $type) · forCredential(string|int $id) · forEndpoint(string $endpointKey)

Queries are immutable, so a partially built query is safe to reuse:

Usage totals

UsageSummary exposes totalRequests, informational, successfulRequests, redirects, clientErrors, serverErrors, totalDurationMs, averageDurationMs, minDurationMs, maxDurationMs, plus errorRate(), serverErrorRate(), hasUsage() and toArray(). An empty period returns zero counts and null durations — never a misleading zero-millisecond average.

Endpoint analytics

Each EndpointUsage carries endpointKey, method, routeName, routeUri and a full UsageSummary. Ordering ties break on the endpoint key, so results are stable between runs.

Actor analytics

Each ActorUsage carries actorType, actorId, actorKey, a UsageSummary, and actor() to turn the result back into a UsageActor you can feed into another query. Different actor types never collide: user:42 and organization:42 are separate rows.

Query freshness

The query API reads daily summaries, not raw rows. Summaries are small, outlive raw retention, and already carry duration totals. The cost is freshness: numbers are as current as the last consolidation run.

By default the package re-consolidates the current day every hour, so today() is at most an hour behind. Consolidation is idempotent — a rerun recomputes the day rather than double-counting it — so you can run it as often as you like:

Turn the hourly run off with API_USAGE_SCHEDULE_CONSOLIDATE_TODAY=false on very high-volume installations, and accept that today's usage appears after the nightly run.

Raw access

Both Eloquent models are public API, and are the right tool for questions the query services do not cover:

Treat them as the advanced API. The query services are the stable surface; the schema may change in a future major version.

What Runs Automatically

Plus api-usage:status, which is never scheduled: it reads the enabled state, Redis and database connectivity, buffer depth, sampling rate and retention windows, and mutates nothing.

RecordApiUsage is appended to the api middleware group. If that group does not exist, registration is skipped silently.

Configuration

Defaults are usable as-is. Publish the config only if you need to change them:

Excluding noisy endpoints

Sampling

Counts are never scaled back up. At a rate below 1.0 the package reports what it observed, not an estimate of the true total, because a number labelled "total requests" that is silently extrapolated is worse than an honest sample. Keep the rate at 1.0 if the counts must be exact — for billing, say.

Retention

api-usage:prune applies all three, deletes in chunks so a large backlog never holds one long transaction open, and is safe to run repeatedly. Set a summary retention to 0 to keep it indefinitely.

Note that consolidation recomputes a day from raw rows, so re-running consolidate-daily for a date whose raw rows have been pruned will zero that day's summaries. Backfill before you prune, not after.

Privacy

What is stored:

• Timestamp, actor type/id, credential id, HTTP method, route name, route URI, concrete path, endpoint key, status code, duration
• A salted SHA-256 digest of the IP address, or nothing when hash_ips is off
• The user agent string, unless record_user_agent is off
• One correlation id, from the headers you list

What is never stored:

• Request bodies · response bodies · query-string values · cookies · Authorization headers · any header other than the configured correlation id
• Actor labels. UsageActor accepts a human-readable label for your own use in query results, and it is deliberately dropped before serialization, so a customer name cannot leak into the usage tables by accident.

Two things to be aware of:

• Request paths are stored verbatim. If your API puts secrets in the URL path, exclude those routes via except.
• Rotating APP_KEY changes the default IP hash salt, so hashes recorded before and after will not correlate. Set an explicit API_USAGE_IP_HASH_SALT if that matters.

Reliability

What can be lost

• Redis unreachable when a request finishes. That request is not recorded. The failure is logged at warning level; the response is unaffected.
• Redis loses data (eviction, flush, failover to an empty replica) before a flush. Those buffered events are gone.
• A resolver throws. An actor resolver failure drops that one record rather than misfiling it; an endpoint resolver failure falls back to the raw path and keeps the record.

What can be double-counted

Delivery into api_usage_requests is at-least-once, not exactly-once. A flush inserts the batch, then deletes the buffer. If the process is killed between those two steps, the next run replays the batch and those rows are inserted twice — inflating that day's raw rows and, once consolidated, its summaries.

The window is milliseconds wide and only opens on a hard kill, not on an ordinary error. It is called out here rather than papered over: if your counts feed invoicing, reconcile against a source that is exactly-once.

What is guaranteed

• A failed database write never discards buffered events. The claimed buffer stays in the processing registry and is retried on the next run.
• Two flushes running concurrently cannot both process the same buffer: it is claimed atomically with RENAMENX and guarded by a short-lived SET NX lock.
• Consolidation cannot double-count. Rows are upserted on the full aggregation identity — period, actor, credential, endpoint — and each run recomputes the period from scratch.
• A usage-tracking failure never fails an HTTP request. Everything happens after the response is sent, and every path is wrapped.

Manual Wiring

Data Model

All timestamps are stored in UTC, independent of app.timezone.

api_usage_requests

api_usage_summaries

One row per (period_type, period_start, bucket_key, endpoint_key) — the full aggregation identity, and the unique index consolidation upserts on.

period_type is day or month. Alongside the counters (total_requests, responses_1xx … responses_5xx) each row carries total_duration_ms, min_duration_ms and max_duration_ms.

bucket_key rather than credential_id carries the uniqueness on purpose: a nullable column in a unique index would defeat the upsert, because SQL treats every NULL as distinct and traffic without a credential would accumulate duplicate rows on every rerun. actor_type, actor_id and credential_id are still separate indexed columns, so you filter on those, never by parsing a key.

What This Package Deliberately Does Not Do

No dashboard. No Filament dependency. No billing or quota enforcement. No rate limiting. No request/response body logging. No distributed tracing or OpenTelemetry exporter. No query profiling or N+1 detection. No p95/p99 latency — that needs a histogram design this package does not have, and a percentile computed from daily min/max would be a lie.

Its whole job is: measure API usage; do not become an observability platform.

Testing

The suite runs against SQLite in memory with an in-memory Redis double, so no services are required.

Contributing

See SECURITY.md.

License

MIT — see LICENSE