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.4+
• Laravel 11+

Getting an API key

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

1. Sign in to the Monitor dashboard and open API keys in the top nav.
2. Click Create key, enter your application slug (lowercase a-z 0-9 -, e.g. my-saas-app), an optional label, and an optional expiry.
3. 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.
4. 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_ENVIRONMENT=production                              # production | staging | development
AUM_BATCH_SIZE=50
AUM_TIMEOUT=5

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:
AiMonitor::report([
    'app'      => 'my-saas-app',   // registered app slug (must match the API key)
    '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',
    ],
]);

app, provider and model are required; 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

1. report() builds a contract-v1 event and adds it to an in-memory buffer
2. When buffer hits AUM_BATCH_SIZE, it dispatches a FlushBufferJob to your queue
3. 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.
4. If Monitor is unreachable, the SDK swallows the error after retries (logged via Log::warning) — your app keeps running
5. 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, environment (from AUM_ENVIRONMENT), operation (default chat), status (default success)
• Content policy: content is only sent when AUM_ENVIRONMENT is not production
• Never sent: cost — calculated server-side