Laravel SDK Logging
Structured logging for Laravel via Monolog channel integration and batched sending with retry.
Structured logging for Laravel via Monolog channel integration and batched sending with retry. Logs appear under Abrova Trace → Logs; they are separate from AbrovaTrace::captureMessage(), which goes to Messages.
Use Laravel's native Log facade with a custom abrovatrace channel driver.
Logs are buffered and sent when the buffer reaches batch_size, and at shutdown.
HTTP client retries connection errors and 5xx responses up to 3 times, waiting 1s, 2s, then 3s.
Monolog levels automatically mapped to AbrovaTrace levels (debug, info, warn, error, fatal).
Installation#
Add the Abrova repository to composer.json, then install (see Laravel SDK):
"repositories": [
{ "type": "composer", "url": "https://center.abrova.ir/api/packages/abrova/composer" }
]composer require abrova-trace/laravel-sdk
Add the log channel to config/logging.php:
'channels' => [
// ... other channels
'abrovatrace' => [
'driver' => 'custom',
'via' => AbrovaTrace\Laravel\Logging\AbrovaTraceLogChannel::class,
],
],Basic Usage#
use Illuminate\Support\Facades\Log;
// Send logs to AbrovaTrace
Log::channel('abrovatrace')->info('User signed up', ['userId' => 123]);
Log::channel('abrovatrace')->warning('Rate limit approaching', ['remaining' => 5]);
Log::channel('abrovatrace')->error('Payment failed', [
'orderId' => 'ORD-456',
'reason' => 'insufficient_funds',
]);Log Levels#
use Illuminate\Support\Facades\Log;
Log::channel('abrovatrace')->debug('Debug information');
Log::channel('abrovatrace')->info('User action completed');
Log::channel('abrovatrace')->notice('Approaching rate limit'); // Maps to 'info'
Log::channel('abrovatrace')->warning('Slow query detected'); // Maps to 'warn'
Log::channel('abrovatrace')->error('Failed to save data');
Log::channel('abrovatrace')->critical('Service unavailable'); // Maps to 'fatal'
Log::channel('abrovatrace')->alert('Database connection lost'); // Maps to 'fatal'
Log::channel('abrovatrace')->emergency('App crashed'); // Maps to 'fatal'Monolog levels are mapped to AbrovaTrace levels: DEBUG=debug, INFO/NOTICE=info, WARNING=warn, ERROR=error, CRITICAL/ALERT/EMERGENCY=fatal.
Direct SDK Logging#
You can also log directly via the AbrovaTrace facade:
use AbrovaTrace\Laravel\AbrovaTraceFacade as AbrovaTrace;
use AbrovaTrace\Laravel\Logging\LogLevel;
// Basic log
AbrovaTrace::log('Server started', LogLevel::INFO);
// With metadata
AbrovaTrace::log('Order processed', LogLevel::INFO, [
'orderId' => 'ORD-123',
'amount' => 99.99,
]);
// User ID: logs carry the id from setUser() (set automatically by the middleware)
AbrovaTrace::setUser(['id' => 'user_abc123']);
AbrovaTrace::log('Payment declined', LogLevel::ERROR, [
'reason' => 'card_expired',
]);
// Convenience methods
AbrovaTrace::info('User logged in');
AbrovaTrace::warn('API rate limit at 80%');
AbrovaTrace::logError('Failed to send email');
// also: trace(), logDebug(), fatal()Stack Channel#
Send logs to multiple destinations by adding abrovatrace to a stack channel:
// config/logging.php
'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['daily', 'abrovatrace'],
'ignore_exceptions' => false,
],
'abrovatrace' => [
'driver' => 'custom',
'via' => AbrovaTrace\Laravel\Logging\AbrovaTraceLogChannel::class,
],
],// Now Log::info() sends to both daily file AND AbrovaTrace
Log::info('User action', ['userId' => 123]);Laravel writes reported exceptions to your default log channel, and since 0.2.3 the SDK no longer stops that. If abrovatrace is in the default stack, an exception also arrives in Logs as a log entry, in addition to being reported as an error.
Metadata & Context#
// Structured metadata
Log::channel('abrovatrace')->info('Order placed', [
'orderId' => 'ORD-12345',
'amount' => 4500000,
'currency' => 'IRR',
'items' => 3,
]);
// Automatically included with every log:
// - Platform ('laravel'), environment name and release
// - User id, when a user is set (the middleware sets the authenticated user)Configuration#
// config/abrovatrace.php
'logging' => [
'source_id' => env('ABROVATRACE_LOG_SOURCE_ID', null), // Groups logs into one source; enables batch sending
'source_name' => env('ABROVATRACE_LOG_SOURCE_NAME', null), // Display name for the source
'batch_size' => 50, // Send when buffer reaches this size
],| Option | Type | Required | Description |
|---|---|---|---|
| logging.source_id | string | No | Log source identifier (e.g., "api-server"). With it, a flush is one batch request; without it, one request per log |
| logging.source_name | string | No | Human-readable display name for the source |
| logging.batch_size | integer | No | Flush when buffer reaches this size (default: 50) |
| api_key | string | Yes | Your project API key (ab_live_xxx) |
| server_secret | string | No | Your server secret (ab_srv_xxx). Needed when the project setting "Server routes require the server secret" is on |
| debug | boolean | No | Enable debug output (default: false) |
Best Practices#
Use Log::channel('abrovatrace') to integrate with Laravel's native logging
Add abrovatrace to a stack channel for local file + cloud logging
Include structured metadata (IDs, durations, counts) for better filtering in the dashboard
Logs carry the user id from AbrovaTrace::setUser() (set automatically for authenticated requests)
Use info for normal operations, warn for degraded state, error for failures
Never log passwords, tokens, or PII in metadata