Download the PHP package jftecnologia/laravel-tracing without Composer

Laravel Tracing

Lightweight, plug-and-play request tracing for Laravel applications.

Laravel Tracing automatically tracks requests across your application using correlation IDs and request IDs. It seamlessly propagates tracing context through queued jobs, HTTP requests, and external API calls — making it easy to correlate logs, debug distributed systems, and trace user sessions end-to-end.

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Usage Examples
• Custom Tracing Sources
• Troubleshooting
• Testing
• Credits
• License

Overview

In distributed and monolithic Laravel applications, tracking the origin and flow of requests is essential for debugging, monitoring, and log correlation. Without standardized tracing identifiers, it's difficult to:

• Correlate log entries across services
• Debug issues spanning multiple requests or jobs
• Track a user session end-to-end
• Trace requests through queues and external HTTP calls

Laravel Tracing solves this by automatically attaching tracing headers (correlation ID, request ID) to every request, propagating them through queued jobs, and forwarding them to external services.

Why Use Laravel Tracing?

• ✅ Simple Setup: One-time middleware registration in bootstrap/app.php
• ✅ Session Persistence: Correlation IDs survive across multiple requests from the same user
• ✅ Job Propagation: Tracing context automatically flows into queued jobs
• ✅ HTTP Client Integration: Forward tracing headers to external APIs with Http::withTracing()
• ✅ Fully Extensible: Add custom tracing sources (user ID, tenant ID, app version) without modifying package code
• ✅ Environment-Aware: Toggle features via config file and environment variables
• ✅ Lightweight: No external dependencies beyond Laravel core

Features

• Built-In Tracing:

  • Correlation ID (X-Correlation-Id): Tracks user sessions across multiple requests
  • Request ID (X-Request-Id): Uniquely identifies each HTTP request

• Session Persistence: Correlation IDs persist across requests from the same user session (via Laravel session/cookies)

• Job Propagation: Tracing values are automatically serialized with job payloads and restored during execution

• HTTP Client Integration: Opt-in support for forwarding tracing headers to external services via Http::withTracing()

• Custom Tracing Sources: Easily add custom tracings (user ID, tenant ID, app version) via config or runtime registration

• Global Accessor: Access all tracing values from anywhere in your application via the LaravelTracing facade

• Configurable: Control header names, enable/disable tracings, and customize behavior via config file and environment variables

• Fully Tested: Comprehensive test suite using PestPHP

Requirements

• PHP: 8.4 or higher
• Laravel: 12 or higher

Installation

Step 1: Install via Composer

Step 2: Register Middleware

Important: Laravel 12 does not support automatic middleware registration via package discovery. You must manually register the tracing middleware in your bootstrap/app.php file:

Important Notes:

• The middleware must be registered to the web middleware group (or after Laravel's StartSession middleware) to ensure session persistence for correlation IDs
• If registered globally or before StartSession, correlation IDs will not persist across requests
• Unlike Laravel 11 and earlier versions, Laravel 12 does not support automatic middleware registration through package discovery

Alternative: Route-Specific Registration

If you prefer to apply tracing only to specific routes:

Step 3: Publish Configuration (Optional)

To customize tracing behavior (header names, enable/disable features, add custom tracings), publish the configuration file:

This creates config/laravel-tracing.php where you can customize all package settings.

Verification

Make a request to your application and check the response headers:

You should see:

Quick Start

Basic Usage

Access tracing values from anywhere in your application:

Use in Log Context

Log output:

Tracing in Queued Jobs

Tracing values are automatically propagated to queued jobs:

Forward Tracing to External APIs

The external service receives:

Configuration

Configuration File Structure

After publishing the config (php artisan vendor:publish --tag=laravel-tracing-config), you'll have access to config/laravel-tracing.php:

Configuration Options

Global Settings

Environment Variables:

• LARAVEL_TRACING_ENABLED - Enable/disable package globally
• LARAVEL_TRACING_ACCEPT_EXTERNAL_HEADERS - Accept external headers

Per-Tracing Settings

Each entry in the tracings array supports:

Built-In Tracings:

• correlation_id: Session-level identifier (persists across multiple requests from the same user)

  • Default header: X-Correlation-Id
  • Environment variable: LARAVEL_TRACING_CORRELATION_ID_HEADER
• request_id: Request-level identifier (unique per HTTP request)
  • Default header: X-Request-Id
  • Environment variable: LARAVEL_TRACING_REQUEST_ID_HEADER

HTTP Client Settings

Environment Variable:

• LARAVEL_TRACING_HTTP_CLIENT_ENABLED

Configuration Examples

Disable Tracing in Local Environment

Customize Header Names

Disable External Header Acceptance (Security)

If your application is publicly exposed and you don't want to accept correlation IDs from untrusted sources:

Security Note: When accept_external_headers is true, the package will use correlation/request IDs sent by clients. Only enable this if you trust your upstream services (API gateways, load balancers, internal services).

Enable HTTP Client Tracing Globally

When enabled, all HTTP requests automatically include tracing headers without calling withTracing():

Usage Examples

Example 1: Accessing Tracing Values in Controllers

Example 2: Using Tracings in Log Context

Log output:

Example 3: Session Persistence (Same Correlation ID Across Requests)

Request 1:

Response:

Request 2 (same session):

Response:

The correlation ID persists across requests from the same session, enabling you to trace all actions from a single user.

Example 4: Tracing in Queued Jobs

Result: All logs from the job execution include the same correlation ID as the dispatching request, making it easy to trace the entire flow.

Example 5: Multiple Jobs Share Correlation ID

All dispatched jobs (ProcessOrder, SendInvoice, UpdateInventory) will share the same correlation ID, allowing you to filter logs by correlation ID to see all related job executions.

Example 6: Forwarding Tracings to External APIs

HTTP request sent to external service:

The external service can now log requests with the same correlation ID, enabling distributed tracing across services.

Custom Tracing Sources

Laravel Tracing is fully extensible. You can add custom tracing sources to track additional context like:

• User ID
• Tenant ID (for multi-tenant applications)
• Application version
• Custom business identifiers

Quick Example: Add User ID Tracing

Step 1: Create Custom Source Class

Step 2: Register in Configuration

Step 3: Use in Your Application

HTTP response headers now include:

Alternative: Runtime Registration

Register custom tracings programmatically in a service provider:

Complete Documentation

For comprehensive documentation on custom tracing sources, including:

• Implementing the TracingSource contract
• Replacing built-in sources
• Complete working examples (User ID, Tenant ID, App Version)
• Best practices and testing strategies

See: Extension Architecture Documentation

Troubleshooting

Tracing Headers Not Appearing in Response

Symptoms:

• Response headers don't include X-Correlation-Id or X-Request-Id

Possible Causes & Solutions:

1. Package disabled via environment variable

2. Middleware not registered

   • Verify that you manually registered the middleware in bootstrap/app.php (required for Laravel 12)
   • Ensure the middleware is added to the correct middleware group (web for session-based apps)
   • Check that no conflicting middleware is interfering
3. Response is a redirect or exception
   • Tracing middleware runs on normal responses. If the response is an exception or early redirect, middleware may not execute.

Debugging Steps:

Tracings Not Accessible in Jobs

Symptoms:

• LaravelTracing::all() returns empty array inside job handler

Possible Causes & Solutions:

1. Queue connection doesn't support serialization

   • Ensure your queue driver supports serialization (database, redis, sqs)
   • sync driver works but processes immediately (no async execution)

2. Job implements custom serialization

   • If your job implements SerializesModels or custom serialization, ensure you're not interfering with the package's job listeners
3. Package disabled

Debugging Steps:

Custom Tracing Source Not Loaded

Symptoms:

• Custom tracing doesn't appear in LaravelTracing::all()
• Custom header not attached to responses

Possible Causes & Solutions:

1. Config not published or cache issue

2. Custom source class not found

   • Ensure the class exists at the path specified in config
   • Check namespace matches config entry
   • Run composer dump-autoload to refresh autoloader

3. Custom tracing disabled in config

4. TracingSource contract not implemented correctly
   • Verify your custom source implements all three methods:
     • resolve(Request $request): string
     • headerName(): string
     • restoreFromJob(string $value): string

Debugging Steps:

External Headers Not Accepted

Symptoms:

• Sending X-Correlation-Id header with request, but server generates new ID instead

Solution:

Check the accept_external_headers configuration:

When false, the package ignores external headers and always generates fresh values.

Session Correlation ID Not Persisting

Symptoms:

• Each request gets a new correlation ID, even from the same session

Possible Causes & Solutions:

1. Session driver not configured

   • Ensure SESSION_DRIVER is set in .env (cookie, file, redis, etc.)
   • array driver doesn't persist sessions across requests

2. Session middleware not running

   • Check app/Http/Kernel.php includes \Illuminate\Session\Middleware\StartSession::class
3. Browser not sending cookies
   • Check Set-Cookie header is included in response
   • Ensure browser accepts cookies (not in incognito/privacy mode)

Debugging Steps:

Frequently Asked Questions

Why use correlation ID vs request ID?

• Correlation ID: Represents a user session or business transaction. Persists across multiple requests from the same user. Useful for tracing an entire user journey (e.g., browse → add to cart → checkout → payment).

• Request ID: Represents a single HTTP request. Unique per request, even within the same session. Useful for identifying specific requests in logs.

Example:

• User visits /products → Correlation ID: abc123, Request ID: req1
• User visits /cart (same session) → Correlation ID: abc123, Request ID: req2
• User visits /checkout (same session) → Correlation ID: abc123, Request ID: req3

All three requests share the same correlation ID, allowing you to trace the entire session.

Can I use this with stateless APIs?

Yes. For stateless APIs (no session), correlation IDs are still useful when forwarded from upstream services:

1. Client sends request with correlation ID:

2. Your API accepts and uses it (if accept_external_headers is true):

3. Your API forwards it to downstream services:

This enables end-to-end tracing across multiple stateless services.

How do I integrate with logging?

Laravel Tracing provides tracing values — you add them to your log context:

For automatic integration, create a custom log processor:

Now all logs automatically include tracing context.

Testing

Run the test suite:

Run with coverage:

Credits

• Junior Fontenele
• All Contributors

License

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