Download the PHP package gilbitron/canonical-context-logging-laravel without Composer

Canonical Context Logging - Laravel Package

Laravel integration for Canonical Context Logging - structured JSON logs with one wide event per request.

Overview

This package integrates the Canonical Context Logging PHP SDK with Laravel, providing:

• Automatic request logging via HTTP middleware
• Laravel service provider for easy setup
• Configuration file for all settings
• Facade and helper functions for easy access
• W3C Trace Context support for distributed tracing
• User context automatically captured from Laravel's auth

Requirements

• PHP 8.1 or higher
• Laravel 10, 11, or 12
• Canonical Context Logging PHP SDK

Installation

The service provider will be auto-discovered by Laravel.

Quick Start

1. Publish Configuration (Optional)

This creates config/canonical-context-logging.php with all available options.

2. Configure Environment Variables

Add to your .env:

3. That's It!

The middleware is automatically registered and will start logging requests. Each request will emit one structured JSON log entry with all context.

Usage

Automatic Logging

The middleware automatically captures:

• Request method, path, URL, IP, user agent
• Response status code
• Request duration
• Authenticated user (if enabled)
• Errors/exceptions
• Trace and span IDs (from W3C Trace Context headers)

Adding Custom Context

Use the Facade:

Or use helper functions:

Accessing Context Directly

Integration with Exception Handler

The middleware automatically captures exceptions, but you can also manually set errors in your exception handler:

Configuration

Exporter Types

Console Exporter (Development)

Outputs logs to stdout/stderr:

File Exporter

Writes logs to a file in JSONL format:

OTLP Exporter (Production)

Sends logs to an OpenTelemetry collector:

Or use standard OpenTelemetry environment variables:

Logger Settings

Tail-Sampling Rules:

• Errors are always logged
• Slow requests (above threshold) are always logged
• Other requests are sampled based on sample_rate
• Set sample_rate to null to log all requests

Service Configuration

Middleware Configuration

Log Output Format

The structured log output follows this schema:

W3C Trace Context Support

The middleware automatically extracts trace and span IDs from the traceparent header if present:

This enables distributed tracing across services.

Disabling Middleware

To disable automatic request logging:

Or set environment variable:

You can still use the Facade and helpers to manually log events.

Manual Logging (Without Middleware)

If you disable the middleware, you can manually start and end contexts:

Testing

The package includes tests. Run them with:

Best Practices

1. One log per request - The middleware handles this automatically
2. Add business context - Use the Facade to add user, org, plan, feature flags, etc.
3. Structured data only - No free-text messages, use consistent keys
4. Tail-sample - Configure sampling to reduce volume while keeping errors and slow requests
5. Error handling - Exceptions are automatically captured, but you can add additional context
6. W3C Trace Context - Include traceparent headers in upstream requests for distributed tracing

License

MIT