README

Laravel SDK for reporting AI usage events to the AI Usage Monitor ingestion API. Drop-in, non-blocking — your app never slows down or crashes because of monitoring.

Requirements

PHP 8.0+
Laravel 9, 10, 11, or 12

Getting an API key

Each application authenticates with its own key, minted from the Monitor dashboard:

Sign in to the Monitor dashboard and open API keys in the top nav.
Click Create key, enter your application slug (lowercase a-z 0-9 -, e.g. my-saas-app), an optional label, and an optional expiry.
The full key (aum_…) is shown once — copy it immediately. The server stores only a hash and can never display it again; if you lose it, mint a new one.
Set it as AUM_API_KEY in your app's .env (see below). Never commit it.

The app you report (see Usage) must match the slug the key was minted for, or the event is rejected with 403. Rotate by minting a new key, deploying it, then revoking the old one from the dashboard — revoked or expired keys are rejected with 401.

Installation

1. Require the package:

composer require logique/ai-usage-monitor-sdk

2. Publish the config:

php artisan vendor:publish --tag=ai-monitor-config

3. Set environment variables in your app's .env:

AUM_ENDPOINT=https://YOUR-MONITOR-HOST/api/v1   # base URL — the SDK appends /events/batch
AUM_API_KEY=your-app-api-key
AUM_APP=my-saas-app                             # must equal the "Application" field the key was minted for
AUM_ENVIRONMENT=production                      # any lowercase slug: production | staging | development | dev | uat | …
AUM_BATCH_SIZE=50
AUM_TIMEOUT=5

AUM_APP must be exactly the slug you entered in the Application field when creating the key on the Monitor's /api-keys page — a mismatch rejects every event with 403. With AUM_APP set, report() calls may omit 'app'; an explicit 'app' param still wins when provided.

The Service Provider and Facade are auto-discovered via Composer — no manual registration needed.

Usage

use Logique\AiUsageMonitor\Facades\AiMonitor;

// After an LLM call completes ('app' defaults to AUM_APP from .env):
AiMonitor::report([
    'service'  => 'ai-conversation', // feature slug — powers the "Usage by service"
                                     // breakdown; slug only: ^[a-z0-9-]+$
    'provider' => 'openai',        // google | openai | anthropic | azure_openai | other
    'model'    => 'gpt-4o',
    'usage'    => [
        'input_tokens'  => 150,
        'output_tokens' => 200,
    ],
]);

With optional fields:

AiMonitor::report([
    'app'       => 'my-saas-app',
    'provider'  => 'anthropic',
    'model'     => 'claude-3-5-sonnet-20241022',
    'service'   => 'summarizer',                 // sub-component slug
    'operation' => 'chat',                       // chat | completion | embedding | image_generation | audio | other
    'usage'     => ['input_tokens' => 100, 'output_tokens' => 50],
    'status'    => 'error',                       // success (default) | error
    'error'     => ['type' => 'rate_limit', 'message' => 'Rate limit exceeded'],
    'timing'    => ['duration_ms' => 1240],
    'metadata'  => [
        'user_id' => 'u_123',
        'feature' => 'summarize',
    ],
]);

provider and model are required; app is required unless AUM_APP is set (explicit param wins); usage.input_tokens / usage.output_tokens default to 0 when omitted. event_id (UUID v4), schema_version, timestamp, and trace_id/span_id are generated automatically. An invalid payload is dropped (and logged) — report() never throws into your application.

Events are buffered in-memory and flushed as async batches — the report() call returns immediately. On Laravel app shutdown, any remaining buffered events are auto-flushed.

How it works

report() builds a contract-v1 event and adds it to an in-memory buffer
When buffer hits AUM_BATCH_SIZE, it dispatches a FlushBufferJob to your queue
The job POSTs the batch to <AUM_ENDPOINT>/events/batch with retry on 429/5xx (backoff: 5s → 30s → 60s; Retry-After honored on 429). A 413 splits the batch and re-dispatches.
If Monitor is unreachable, the SDK swallows the error after retries (logged via Log::warning) — your app keeps running
On app termination, remaining buffer is auto-flushed

Important: Ensure a queue worker is running in your app:

php artisan queue:work

Event Contract

The SDK sends payloads conforming to AUM Event Contract v1.

Required from caller: app, provider, model (and usage.input_tokens / usage.output_tokens, default 0)
Auto-set by the SDK: event_id (UUID v4), schema_version ("1.0"), timestamp (UTC ISO 8601), trace_id/span_id, app (from AUM_APP when omitted), environment (from AUM_ENVIRONMENT, any lowercase slug), operation (default chat), status (default success)
Content policy: content is only sent when AUM_ENVIRONMENT is not production
Never sent: cost — calculated server-side

logique / ai-usage-monitor-sdk

Maintainers

Package info

Statistics

Security