PHPackages gilbitron/canonical-context-logging-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. gilbitron/canonical-context-logging-laravel ActiveLibrary[Logging & Monitoring](/categories/logging) gilbitron/canonical-context-logging-laravel =========================================== Laravel integration for Canonical Context Logging - structured JSON logs with one wide event per request 0.2.0(4mo ago)02.8k↓21.1%MITPHPPHP >=8.1CI passing Since Dec 24Pushed 4mo agoCompare [ Source](https://github.com/gilbitron/canonical-context-logging-laravel)[ Packagist](https://packagist.org/packages/gilbitron/canonical-context-logging-laravel)[ RSS](/packages/gilbitron-canonical-context-logging-laravel/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (6)Versions (4)Used By (0) Canonical Context Logging - Laravel Package =========================================== [](#canonical-context-logging---laravel-package) Laravel integration for [Canonical Context Logging](https://github.com/gilbitron/canonical-context-logging) - structured JSON logs with one wide event per request. Overview -------- [](#overview) This package integrates the [Canonical Context Logging PHP SDK](https://github.com/gilbitron/canonical-context-logging) 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 ------------ [](#requirements) - PHP 8.1 or higher - Laravel 10, 11, or 12 - [Canonical Context Logging PHP SDK](https://github.com/gilbitron/canonical-context-logging) Installation ------------ [](#installation) ``` composer require gilbitron/canonical-context-logging-laravel ``` The service provider will be auto-discovered by Laravel. Quick Start ----------- [](#quick-start) ### 1. Publish Configuration (Optional) [](#1-publish-configuration-optional) ``` php artisan vendor:publish --tag=canonical-context-logging-config ``` This creates `config/canonical-context-logging.php` with all available options. ### 2. Configure Environment Variables [](#2-configure-environment-variables) Add to your `.env`: ``` # Exporter type: console, file, or otlp CANONICAL_CONTEXT_EXPORTER_TYPE=console # For console exporter (development) CANONICAL_CONTEXT_CONSOLE_STDERR=true CANONICAL_CONTEXT_CONSOLE_PRETTY=false # For file exporter CANONICAL_CONTEXT_FILE_PATH=/var/log/app/canonical.jsonl # For OTLP exporter (or use standard OTEL env vars) CANONICAL_CONTEXT_OTLP_ENDPOINT=https://otel-collector:4318 # Or use: OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector:4318 # Logger settings CANONICAL_CONTEXT_SLOW_THRESHOLD=1.0 CANONICAL_CONTEXT_SAMPLE_RATE=0.1 # Service info (defaults to app.name and app.version) CANONICAL_CONTEXT_SERVICE_NAME=my-service CANONICAL_CONTEXT_SERVICE_VERSION=1.0.0 # Middleware settings CANONICAL_CONTEXT_MIDDLEWARE_ENABLED=true CANONICAL_CONTEXT_CAPTURE_USER=true CANONICAL_CONTEXT_CAPTURE_HEADERS=false ``` ### 3. That's It! [](#3-thats-it) The middleware is automatically registered and will start logging requests. Each request will emit one structured JSON log entry with all context. Usage ----- [](#usage) ### Automatic Logging [](#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 [](#adding-custom-context) Use the Facade: ``` use CanonicalContextLogging\Laravel\Facades\CanonicalContext; // Add single context CanonicalContext::addContext('org_id', 123); CanonicalContext::addContext('plan', 'premium'); CanonicalContext::addContext('feature_flags', ['feature_a', 'feature_b']); // Add multiple at once CanonicalContext::addContexts([ 'org_id' => 123, 'plan' => 'premium', 'feature_flags' => ['feature_a', 'feature_b'], ]); // Set error try { // ... } catch (\Exception $e) { CanonicalContext::setError($e); throw $e; } ``` Or use helper functions: ``` // Get current context $context = canonical_context(); // Add context canonical_add_context('org_id', 123); // Set error canonical_set_error($exception); ``` ### Accessing Context Directly [](#accessing-context-directly) ``` use CanonicalContextLogging\Laravel\Facades\CanonicalContext; $context = CanonicalContext::context(); if ($context !== null) { $context->addContext('custom_key', 'custom_value'); } ``` ### Integration with Exception Handler [](#integration-with-exception-handler) The middleware automatically captures exceptions, but you can also manually set errors in your exception handler: ``` // app/Exceptions/Handler.php use CanonicalContextLogging\Laravel\Facades\CanonicalContext; public function render($request, \Throwable $e) { CanonicalContext::setError($e); return parent::render($request, $e); } ``` Configuration ------------- [](#configuration) ### Exporter Types [](#exporter-types) #### Console Exporter (Development) [](#console-exporter-development) Outputs logs to stdout/stderr: ``` 'exporter' => [ 'type' => 'console', 'console' => [ 'use_stderr' => true, // Use stderr instead of stdout 'pretty_print' => false, // Pretty-print JSON ], ], ``` #### File Exporter [](#file-exporter) Writes logs to a file in JSONL format: ``` 'exporter' => [ 'type' => 'file', 'file' => [ 'path' => storage_path('logs/canonical.jsonl'), 'pretty_print' => false, ], ], ``` #### OTLP Exporter (Production) [](#otlp-exporter-production) Sends logs to an OpenTelemetry collector: ``` 'exporter' => [ 'type' => 'otlp', 'otlp' => [ 'endpoint' => 'https://otel-collector:4318', 'protocol' => 'http/protobuf', // or 'http/json' 'headers' => ['Authorization' => 'Bearer token'], 'timeout' => 10, ], ], ``` Or use standard OpenTelemetry environment variables: ``` export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector:4318 export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123" ``` ### Logger Settings [](#logger-settings) ``` 'logger' => [ 'slow_request_threshold' => 1.0, // Always log requests slower than 1 second 'sample_rate' => 0.1, // Sample 10% of normal requests ], ``` **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 [](#service-configuration) ``` 'service' => [ 'name' => 'my-service', // Defaults to config('app.name') 'version' => '1.0.0', // Defaults to config('app.version', '1.0.0') ], ``` ### Middleware Configuration [](#middleware-configuration) ``` 'middleware' => [ 'enabled' => true, // Enable/disable middleware 'capture_user' => true, // Capture authenticated user info 'capture_request_headers' => false, // Capture all request headers ], ``` Log Output Format ----------------- [](#log-output-format) The structured log output follows this schema: ``` { "timestamp": "2024-01-15T10:30:45+00:00", "trace_id": "a1b2c3d4e5f6...", "span_id": "1234567890abcdef", "service": { "name": "my-service", "version": "1.0.0" }, "status": 200, "duration": 0.123, "context": { "http.method": "GET", "http.path": "api/users", "http.url": "https://example.com/api/users", "http.ip": "192.168.1.1", "http.user_agent": "Mozilla/5.0...", "user.id": 123, "user.email": "user@example.com", "org_id": 456, "plan": "premium", "feature_flags": ["feature_a", "feature_b"] }, "error": { "type": "RuntimeException", "message": "Something went wrong", "file": "/path/to/file.php", "line": 42, "code": 0 } } ``` W3C Trace Context Support ------------------------- [](#w3c-trace-context-support) The middleware automatically extracts trace and span IDs from the `traceparent` header if present: ``` traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 ``` This enables distributed tracing across services. Disabling Middleware -------------------- [](#disabling-middleware) To disable automatic request logging: ``` // config/canonical-context-logging.php 'middleware' => [ 'enabled' => false, ], ``` Or set environment variable: ``` CANONICAL_CONTEXT_MIDDLEWARE_ENABLED=false ``` You can still use the Facade and helpers to manually log events. Manual Logging (Without Middleware) ----------------------------------- [](#manual-logging-without-middleware) If you disable the middleware, you can manually start and end contexts: ``` use CanonicalContextLogging\Laravel\Facades\CanonicalContext; use CanonicalContextLogging\Middleware\RequestMiddleware; $middleware = app(RequestMiddleware::class); // Start context $context = $middleware->start(); $context->setService('my-service', '1.0.0'); $context->addContext('user_id', 123); // ... your application logic ... // End context $context->setStatus(200); $middleware->end($context); ``` Testing ------- [](#testing) The package includes tests. Run them with: ``` ./vendor/bin/phpunit ``` Best Practices -------------- [](#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 ------- [](#license) MIT ### Health Score 37 — LowBetter than 83% of packages Maintenance74 Regular maintenance activity Popularity23 Limited adoption so far Community6 Small or concentrated contributor base Maturity35 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 3 Last Release 141d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/20011de485eeea26b5582c75daaab217937832762b5d5f551d34d07f74138bb0?d=identicon)[gilbitron](/maintainers/gilbitron) --- Top Contributors [![gilbitron](https://avatars.githubusercontent.com/u/203882?v=4)](https://github.com/gilbitron "gilbitron (5 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/gilbitron-canonical-context-logging-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/gilbitron-canonical-context-logging-laravel/health.svg)](https://phpackages.com/packages/gilbitron-canonical-context-logging-laravel) ``` ### Alternatives [spatie/laravel-health Monitor the health of a Laravel application 86910.0M83](/packages/spatie-laravel-health)[yadahan/laravel-authentication-log Laravel Authentication Log provides authentication logger and notification for Laravel. 416632.8k5](/packages/yadahan-laravel-authentication-log)[inspector-apm/inspector-laravel Code Execution Monitoring, built for developers. 2332.0M2](/packages/inspector-apm-inspector-laravel)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum)[shaffe/laravel-mail-log-channel A package to support logging via email in Laravel 1286.2k](/packages/shaffe-laravel-mail-log-channel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)