README

Official Laravel SDK for RiviumTrace — error tracking, logging, and APM.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• Guzzle 7

Installation

composer require rivium-trace/laravel-sdk

Auto-discovery handles service provider and facade registration.

Configuration

Publish config:

php artisan vendor:publish --tag=riviumtrace-config

Add to .env:

RIVIUMTRACE_API_KEY=rv_live_your_api_key_here
RIVIUMTRACE_SERVER_SECRET=rv_srv_your_secret_here
RIVIUMTRACE_ENVIRONMENT=production
RIVIUMTRACE_RELEASE=0.1.2

Self-Hosted

If you're running RiviumTrace Self-Hosted, add RIVIUMTRACE_API_URL pointing to your server:

RIVIUMTRACE_API_URL=http://your-server:3001
RIVIUMTRACE_API_KEY=rv_live_your_api_key_here
RIVIUMTRACE_SERVER_SECRET=rv_srv_your_secret_here
RIVIUMTRACE_ENVIRONMENT=production

Everything else works the same — error tracking, logging, APM, middleware.

Usage

Automatic Tracking

RiviumTrace automatically captures:

• Unhandled exceptions through Laravel's exception handler
• HTTP requests through middleware (timing, status, breadcrumbs)
• Slow DB queries as performance spans

Manual Error Capture

use RiviumTrace\Laravel\RiviumTraceFacade as RiviumTrace;

try {
    riskyOperation();
} catch (\Throwable $e) {
    RiviumTrace::captureException($e, [
        'extra' => ['order_id' => $orderId],
    ]);
}

RiviumTrace::captureMessage('Payment processed', [
    'extra' => ['amount' => 99.99],
]);

Breadcrumbs

use RiviumTrace\Laravel\Models\Breadcrumb;

RiviumTrace::addBreadcrumb(
    Breadcrumb::custom('User signed up', 'auth', ['plan' => 'pro'])
);

RiviumTrace::addBreadcrumb(
    Breadcrumb::http('POST', '/api/payments', 201, 450.5)
);

RiviumTrace::addBreadcrumb(
    Breadcrumb::user('checkout_completed', ['items' => 3])
);

User Context

RiviumTrace::setUser([
    'id' => $user->id,
    'email' => $user->email,
    'name' => $user->name,
]);

Scoped Context

RiviumTrace::withScope(function ($scope) {
    $scope->setUser(['id' => 'temp-user']);
    processOrder($order);
});

Logging

Add the RiviumTrace channel to config/logging.php:

'channels' => [
    'riviumtrace' => [
        'driver' => 'custom',
        'via' => \RiviumTrace\Laravel\Logging\RiviumTraceLogChannel::class,
    ],

    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily', 'riviumtrace'],
    ],
],

Usage:

Log::channel('riviumtrace')->info('Order created', ['order_id' => 123]);
Log::channel('riviumtrace')->error('Payment failed', ['reason' => 'declined']);

RiviumTrace::info('Processing started');
RiviumTrace::warn('Rate limit approaching', ['current' => 95, 'max' => 100]);
RiviumTrace::logError('External API timeout', ['service' => 'stripe']);

Set a source ID for batched log delivery:

RIVIUMTRACE_LOG_SOURCE_ID=my-laravel-api
RIVIUMTRACE_LOG_SOURCE_NAME=My Laravel API

Performance Monitoring

use RiviumTrace\Laravel\Performance\PerformanceSpan;

$result = RiviumTrace::trackOperation('process_payment', function () use ($order) {
    return PaymentGateway::charge($order);
}, ['operationType' => 'custom', 'tags' => ['provider' => 'stripe']]);

RiviumTrace::reportPerformanceSpan(
    PerformanceSpan::custom([
        'operation' => 'generate_report',
        'durationMs' => 1500,
        'startTime' => $startTime,
        'tags' => ['report_type' => 'monthly'],
    ])
);

RiviumTrace::reportPerformanceSpan(
    PerformanceSpan::fromHttpRequest([
        'method' => 'POST',
        'url' => 'https://api.stripe.com/v1/charges',
        'statusCode' => 200,
        'durationMs' => 320,
        'startTime' => $startTime,
    ])
);

Config Reference

Ignored Exceptions

By default these exceptions are not reported:

• AuthenticationException
• ValidationException
• NotFoundHttpException
• 4xx HTTP exceptions

Customize in config/riviumtrace.php:

'exception_handler' => [
    'ignored_exceptions' => [
        \App\Exceptions\BusinessException::class,
    ],
    'report_4xx' => true,
],

Middleware

Auto-added to web and api groups. Disable via config:

'middleware' => ['enabled' => false],

Ignore specific paths:

'middleware' => [
    'ignored_paths' => ['_debugbar/*', 'telescope/*', 'health'],
],

License

MIT