rivium-trace/laravel-sdk

RiviumTrace Laravel SDK for error tracking, logging, and performance monitoring

v0.1.2 2026-03-30 00:51 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• mockery/mockery: ^1.6
• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• RiviumTrace Team

• logging
• performance
• monitoring
• laravel
• apm
• error-tracking
• observability
• rivium-trace

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

Key	Env Var	Default	Description
api_key	RIVIUMTRACE_API_KEY	''	API key (rv_live_xxx / rv_test_xxx)
api_url	RIVIUMTRACE_API_URL	https://trace.rivium.co	API URL — set for self-hosted only
server_secret	RIVIUMTRACE_SERVER_SECRET	''	Server secret (rv_srv_xxx)
enabled	RIVIUMTRACE_ENABLED	true	Enable/disable SDK
environment	RIVIUMTRACE_ENVIRONMENT	APP_ENV	Environment name
release	RIVIUMTRACE_RELEASE	0.1.0	Release version
sample_rate	RIVIUMTRACE_SAMPLE_RATE	1.0	Error sample rate (0.0-1.0)
debug	RIVIUMTRACE_DEBUG	false	Debug mode
timeout	RIVIUMTRACE_TIMEOUT	5	HTTP timeout (seconds)
performance.enabled	RIVIUMTRACE_PERFORMANCE_ENABLED	true	Enable APM
logging.enabled	RIVIUMTRACE_LOGGING_ENABLED	true	Enable logging
logging.source_id	RIVIUMTRACE_LOG_SOURCE_ID	null	Log source ID

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