Download the PHP package kbeaud11/laravel-cloud-tracker without Composer

Laravel Cloud Tracker

Track usage-based infrastructure costs per model in Laravel Cloud environments. Built for observability — not billing.

Laravel Cloud Tracker gives you per-entity, per-feature cost visibility by wrapping expensive operations in a fluent API that measures execution time, calculates estimated cost across multiple infrastructure dimensions, and stores both granular events and aggregated monthly rollups.

Why?

Laravel Cloud bills by usage: compute time, database CPU, cache operations, bandwidth, and more. When you run a multi-tenant SaaS, you need to understand which tenants consume which resources and how much it costs.

This package answers questions like:

• "How much compute does Organization X consume monthly?"
• "What's the most expensive feature across all tenants?"
• "Are our enterprise clients actually covering their infrastructure costs?"

It does not enforce billing, integrate with Stripe, or render UI. It's the observability layer that makes those things possible.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• MySQL, PostgreSQL, or SQLite

Installation

Publish Configuration

Publish & Run Migrations

This creates three tables:

Configuration

After publishing, the config lives at config/cloud-tracker.php.

Master Switch & Environments

Tracking is disabled by default in local development. The callback always executes — only timing, cost calculation, and DB writes are skipped.

Laravel Cloud Plan

Stored for reference and future quota features. Does not affect per-unit rates (those are determined by instance selection).

Supported values: starter, growth, business, enterprise.

Cost Dimensions

Every billable Laravel Cloud resource is represented as a cost dimension. Rates are pre-populated from Laravel Cloud's published pricing (US East region).

Compute (Time-Based)

Select your instance size via environment variable:

Available instances:

Queue Workers (Time-Based)

Queue workers use the same instance pricing as compute but are configured independently:

Serverless Postgres (Time-Based)

Billed at $0.106/hour per vCPU:

Cache / Valkey (Flat Monthly)

Flat monthly rate amortized over estimated operations:

Adjust estimated_operations_per_month to match your actual usage for more accurate per-operation cost.

WebSockets / Reverb (Flat Monthly)

Amortized over estimated_messages_per_month (default: 1,000,000).

Bandwidth (Count-Based)

Object Storage (Count-Based)

Event Logging

Set to false to skip writing to model_usage_events and only maintain rollups. Reduces write volume in high-throughput scenarios.

Default Dimension

Applied when no dimension is explicitly chained on a track() call.

Usage

1. Add the Trait to Your Billable Model

This provides three relationships:

2. Track an Operation

The callback's return value is always passed through. Timing, cost calculation, event logging, and rollup upsert happen transparently.

3. Chain Multiple Dimensions

When an operation spans multiple infrastructure resources:

Each dimension calculates cost independently based on its unit type, then all are summed.

For time-based dimensions (compute, postgres, queue), cost is derived from execution time automatically.

For count-based and flat-monthly dimensions (cache, websocket, bandwidth, storage), pass a quantity:

4. Force Tracking (Bypass Policy)

For admin or internal operations that should always be tracked regardless of the model's policy:

force() bypasses the tracking policy but still respects environment restrictions (local stays disabled).

5. Attach Metadata

Store arbitrary context with the event for debugging or reporting:

Metadata is stored as JSON on the model_usage_events row.

Tracking Policies

Every billable model can have a tracking policy that controls which features are tracked and at what cost multiplier. Policies are stored in the model_tracking_policies table (created by the package migration).

Creating a Policy

Or via the trait relationship:

Tracking Modes

Usage Multiplier

The usage_multiplier column scales all cost calculations for a model:

Policy Resolution

Policy is evaluated before timing starts. When tracking is disabled for a model+feature:

• The callback still executes normally
• No hrtime calls
• No cost calculation
• No database writes
• Near-zero overhead

Policies are cached in memory for the duration of the request to avoid redundant queries.

Querying Usage Data

Via Relationships

Via Models Directly

Extending the Package

Both the policy resolver and cost calculator are bound to contracts in the service container. You can swap in your own implementations.

Custom Policy Resolver

Register in your AppServiceProvider:

Custom Cost Calculator

Register in your AppServiceProvider:

How It Works

Execution Flow

Cost Calculation

Each dimension type calculates cost differently:

The total cost across all dimensions is then multiplied by the model's usage_multiplier.

Rollup Aggregation

Rollups use an atomic database upsert keyed by (billable_type, billable_id, feature, period_start). On conflict, total_execution_ms, total_cost, and event_count are incremented atomically — no read-then-write race conditions.

Compatible with MySQL, PostgreSQL, and SQLite.

Testing

Running Package Tests

Tests run against an in-memory SQLite database with no external dependencies.

Test Coverage

Testing in Your Application

The package respects the environments config. Add 'testing' to track during tests, or leave it out to skip tracking entirely in your test suite:

To assert tracking in your application tests:

What This Package Is Not

• Not a billing engine. No Stripe, no invoices, no payment processing.
• Not a UI. No dashboards, charts, or admin panels.
• Not real infrastructure introspection. It doesn't read CloudWatch metrics or parse SQL queries. It estimates cost from execution time and configured rates.
• Not a rate limiter or quota enforcer. It observes — it doesn't restrict.

It is the observability foundation that makes all of those things possible.

License

MIT