README

Send your Laravel application logs to PostHog using the OpenTelemetry OTLP format. Just add the package, configure your environment variables, and your logs are automatically available in PostHog.

Installation

Install the package via Composer:

composer require robbiekibler/laravel-posthog-logs

Configuration

Quick Start

Add these environment variables to your .env file:

POSTHOG_API_KEY=phc_your_project_api_key
POSTHOG_HOST=us.i.posthog.com

Security Note: Use a project API key (starts with phc_), not a personal API key. Project API keys have limited scope and are safe for server-side usage.

Then add the posthog channel to your config/logging.php:

'channels' => [
    // ... other channels

    'posthog' => [
        'driver' => 'posthog',
    ],
],

To use PostHog as your default log channel, or as part of a stack:

// Use PostHog as default
'default' => env('LOG_CHANNEL', 'posthog'),

// Or add to a stack
'stack' => [
    'driver' => 'stack',
    'channels' => ['single', 'posthog'],
],

Environment Variables

Publishing Config (Optional)

To customize all options, publish the config file:

php artisan vendor:publish --tag="posthog-logs-config"

Testing Your Configuration

Verify your setup is working by running the test command:

php artisan posthog:test

This will display your current configuration and send a test log entry to PostHog. You can customize the test message:

php artisan posthog:test --message="Hello from my app!"

Usage

Once configured, use Laravel's standard logging:

use Illuminate\Support\Facades\Log;

// Basic logging
Log::info('User logged in');
Log::warning('Rate limit approaching');
Log::error('Payment failed', ['order_id' => 123]);

// With context
Log::channel('posthog')->info('Order created', [
    'order_id' => $order->id,
    'customer_id' => $customer->id,
    'total' => $order->total,
]);

Trace Correlation

If you're using distributed tracing, you can include trace context:

Log::info('Processing request', [
    'trace_id' => $traceId,
    'span_id' => $spanId,
    'user_id' => $userId,
]);

Log Levels

The package maps Laravel/Monolog log levels to OpenTelemetry severity:

Viewing Logs in PostHog

1. Go to your PostHog dashboard
2. Navigate to Logs in the sidebar
3. Filter by service name, environment, or log level
4. Click on individual logs to see full context and attributes

Advanced Configuration

Channel-Level Overrides

Override settings per channel in config/logging.php:

'posthog' => [
    'driver' => 'posthog',
    'level' => 'warning',  // Only send warnings and above
    'service_name' => 'my-api',
    'environment' => 'staging',
],

Custom Resource Attributes

Add custom attributes to all logs via config:

// config/posthog-logs.php
'resource_attributes' => [
    'team.name' => 'backend',
    'version' => '1.3.0',
],

Disable in Tests

# .env.testing
POSTHOG_LOGS_ENABLED=false

Performance Considerations

Logs are sent to PostHog via synchronous HTTP requests. The package includes:

• Batching: Logs are batched (default: 100 per batch) to reduce HTTP overhead
• Timeouts: Short timeouts (5s request, 2s connect) to prevent blocking
• Retries: Automatic retry with exponential backoff for transient failures
• Overflow Protection: Oldest logs are dropped if the batch overflows due to send failures

For high-throughput applications, consider:

• Using a log stack with a fast local channel (e.g., single) as primary
• Adjusting batch size via POSTHOG_BATCH_MAX_SIZE
• Setting a higher minimum log level in production via POSTHOG_LOG_LEVEL

Testing

composer test

Changelog

Please see CHANGELOG for recent changes.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Robbie Kibler
• All Contributors

License

The MIT License (MIT). Please see License File for more information.