Laravel SDK

Drop-in integration for Laravel 10, 11, and 12 with zero-configuration needed. The package auto-registers middleware, a log channel, a Facade, and breadcrumb integrations for database queries, cache events, and queue jobs.

Installation

composer require logtide/logtide-laravel

The service provider and facade are registered automatically via Laravel's package auto-discovery. No manual registration needed.

Publish the configuration file:

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

Quick Start

Add your DSN to .env:

LOGTIDE_DSN=https://[email protected]

That's it! The SDK is now active. Use Laravel's standard logging:

<?php

use Illuminate\Support\Facades\Log;

// Standard Laravel logging — sent to LogTide automatically
Log::info('Order placed', ['order_id' => $order->id, 'amount' => $order->total]);
Log::error('Payment failed', ['exception' => $e]);

// Or use the LogTide Facade for direct Hub access
use LogTide\Laravel\LogtideFacade as Logtide;

Logtide::captureLog(\LogTide\Enum\LogLevel::INFO, 'Direct capture', ['key' => 'value']);
Logtide::captureException($exception);

Configuration

Environment Variables

# .env
LOGTIDE_DSN=https://[email protected]
LOGTIDE_SERVICE=my-laravel-app        # default: APP_NAME
LOGTIDE_ENVIRONMENT=production         # default: APP_ENV
LOGTIDE_RELEASE=1.2.3
LOGTIDE_TRACES_SAMPLE_RATE=1.0
LOGTIDE_DEBUG=false

config/logtide.php

<?php

return [
    'dsn' => env('LOGTIDE_DSN'),

    'service' => env('LOGTIDE_SERVICE', env('APP_NAME', 'laravel')),
    'environment' => env('LOGTIDE_ENVIRONMENT', env('APP_ENV', 'production')),
    'release' => env('LOGTIDE_RELEASE'),

    // Batching
    'batch_size' => (int) env('LOGTIDE_BATCH_SIZE', 100),
    'flush_interval' => (int) env('LOGTIDE_FLUSH_INTERVAL', 5000),
    'max_buffer_size' => (int) env('LOGTIDE_MAX_BUFFER_SIZE', 10000),
    'max_retries' => (int) env('LOGTIDE_MAX_RETRIES', 3),

    // Tracing
    'traces_sample_rate' => (float) env('LOGTIDE_TRACES_SAMPLE_RATE', 1.0),

    // Privacy
    'send_default_pii' => (bool) env('LOGTIDE_SEND_DEFAULT_PII', false),

    // Breadcrumb integrations
    'breadcrumbs' => [
        'db_queries' => true,
        'cache' => true,
        'queue' => true,
        'http_client' => true,
    ],

    // Paths to skip in the HTTP middleware
    'skip_paths' => ['/health', '/healthz'],

    'debug' => (bool) env('LOGTIDE_DEBUG', false),
];

Using the Facade

The Logtide facade provides direct access to the Hub API.

<?php

use LogTide\Laravel\LogtideFacade as Logtide;
use LogTide\Enum\LogLevel;
use LogTide\Breadcrumb\Breadcrumb;
use LogTide\Enum\BreadcrumbType;

// Capture logs
Logtide::captureLog(LogLevel::INFO, 'User action', ['action' => 'purchase']);

// Capture exceptions
Logtide::captureException($exception);

// Add breadcrumbs
Logtide::addBreadcrumb(new Breadcrumb(
    BreadcrumbType::DEFAULT,
    'Custom event happened',
    category: 'app',
));

// Scopes
Logtide::withScope(function () {
    Logtide::getScope()->setTag('handler', 'checkout');
    Logtide::captureLog(LogLevel::INFO, 'Checkout started');
});

// Tracing
$span = Logtide::startSpan('process.order', ['kind' => \LogTide\Enum\SpanKind::INTERNAL]);
// ... do work ...
if ($span !== null) {
    Logtide::finishSpan($span);
}

// Flush
Logtide::flush();

Log Channel

A logtide log channel is automatically registered. Add it to your logging stack to send Laravel logs to LogTide alongside your existing channels.

<?php
// config/logging.php

return [
    'default' => env('LOG_CHANNEL', 'stack'),

    'channels' => [
        'stack' => [
            'driver' => 'stack',
            'channels' => ['daily', 'logtide'],
            'ignore_exceptions' => false,
        ],

        // The 'logtide' channel is auto-registered by the service provider.
        // No manual configuration needed here.

        // ... other channels
    ],
];

Request Middleware

The HTTP middleware is automatically registered by the service provider. For each request it:

• Creates an isolated scope (tags and breadcrumbs don't leak between requests)
• Extracts incoming traceparent header for distributed tracing
• Starts a SERVER span with HTTP attributes (method, URL, user agent)
• Captures 5xx responses as error log events
• Catches and reports uncaught exceptions
• Injects traceparent into the response for trace correlation

Paths listed in config('logtide.skip_paths') are skipped (default: /health, /healthz).

Breadcrumb Integrations

The service provider automatically registers breadcrumb integrations. Toggle them in config/logtide.php:

Database Queries — Records QueryExecuted events as breadcrumbs with query, bindings, and duration
Cache Events — Records cache hits, misses, writes, and deletes
Queue Jobs — Records job processing events with job class, queue name, and attempt count

Best Practices

1. Use the Log Channel Stack

Add logtide to your log channel stack so all Log::info() calls are automatically sent to LogTide alongside your local file logs.

2. Set Environment and Release

The service name defaults to APP_NAME and environment to APP_ENV. Set LOGTIDE_RELEASE to your deployment version for release tracking.

3. Queue Workers

Queue workers automatically have access to LogTide. Make sure the LOGTIDE_DSN environment variable is available to your worker processes.