PHPackages                             tracekit/laravel-apm - 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. tracekit/laravel-apm

ActiveLibrary[Logging & Monitoring](/categories/logging)

tracekit/laravel-apm
====================

TraceKit APM for Laravel - Zero-config distributed tracing and code monitoring

1.4.2(1mo ago)614MITPHPPHP ^8.1

Since Nov 8Pushed 1mo agoCompare

[ Source](https://github.com/Tracekit-Dev/laravel-apm)[ Packagist](https://packagist.org/packages/tracekit/laravel-apm)[ RSS](/packages/tracekit-laravel-apm/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (19)Versions (11)Used By (0)

TraceKit APM for Laravel
========================

[](#tracekit-apm-for-laravel)

Zero-config distributed tracing and performance monitoring for Laravel applications.

[![Latest Version](https://camo.githubusercontent.com/815957de82677e0fba09308227bee444fb34b7671d00893e9ea644bc4e80f7e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74726163656b69742f6c61726176656c2d61706d2e737667)](https://packagist.org/packages/tracekit/laravel-apm)[![Total Downloads](https://camo.githubusercontent.com/2f2db583b676741e31d8855cc40f1f017a2b14f62e44c5cc04208b75a93b9499/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f74726163656b69742f6c61726176656c2d61706d2e737667)](https://packagist.org/packages/tracekit/laravel-apm)[![License](https://camo.githubusercontent.com/9e1d8f5df3963a3c09f0121ef688f0a8efdd5772a2f261418317315902bbca37/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74726163656b69742f6c61726176656c2d61706d2e737667)](https://packagist.org/packages/tracekit/laravel-apm)

Features
--------

[](#features)

- **Zero Configuration** - Works out of the box with sensible defaults
- **Automatic Instrumentation** - No code changes needed
- **HTTP Request Tracing** - Track every request, route, and middleware
- **Database Query Monitoring** - See every query with actual SQL and bindings
- **Queue Job Tracking** - Monitor Laravel jobs and queues
- **Slow Query Detection** - Automatically highlight slow database queries
- **Error Tracking** - Capture exceptions with full context
- **Code Monitoring** - Live debugging with breakpoints and variable inspection
- **Metrics API** - Counter, Gauge, and Histogram metrics with automatic OTLP export
- **Low Overhead** - < 5% performance impact

Installation
------------

[](#installation)

```
composer require tracekit/laravel-apm
```

Quick Start
-----------

[](#quick-start)

### 1. Install the package

[](#1-install-the-package)

```
php artisan tracekit:install
```

### 2. Add your API key to `.env`

[](#2-add-your-api-key-to-env)

```
TRACEKIT_API_KEY=your-api-key-here
TRACEKIT_SERVICE_NAME=my-laravel-app

# Optional: Custom endpoint (defaults to https://app.tracekit.dev/v1/traces)
# TRACEKIT_ENDPOINT=https://your-custom-endpoint.com/v1/traces
```

Get your API key at

### 3. Done!

[](#3-done)

Your Laravel app is now automatically traced. Visit your TraceKit dashboard to see your traces.

Local Development
-----------------

[](#local-development)

Debug your Laravel application locally without creating a cloud account using TraceKit Local UI.

### Quick Start

[](#quick-start-1)

```
# Install Local UI globally
npm install -g @tracekit/local-ui

# Start it
tracekit-local
```

The Local UI will start at `http://localhost:9999` and automatically open in your browser.

### How It Works

[](#how-it-works)

When running in `local` or `development` environment (Laravel's `APP_ENV`), the SDK automatically:

1. Detects if Local UI is running at `http://localhost:9999`
2. Sends traces to both Local UI and cloud (if API key is present)
3. Falls back gracefully if Local UI is not available

**No code changes needed!** Just set your `.env`:

```
APP_ENV=local
TRACEKIT_API_KEY=your-key  # Optional - works without it!
```

Then run your app:

```
php artisan serve
```

You'll see traces appear in real-time at `http://localhost:9999`.

### Features

[](#features-1)

- Real-time trace viewing in your browser
- Works completely offline
- No cloud account required
- Zero configuration
- Automatic cleanup (1000 traces max, 1 hour retention)

### Local-Only Development

[](#local-only-development)

To use Local UI without cloud sending:

```
APP_ENV=local
# Don't set TRACEKIT_API_KEY
```

Traces will only go to Local UI.

### Disabling Local UI

[](#disabling-local-ui)

To disable automatic Local UI detection:

```
APP_ENV=production
# or don't run Local UI
```

### Learn More

[](#learn-more)

- GitHub:
- npm: [@tracekit/local-ui](https://www.npmjs.com/package/@tracekit/local-ui)

Configuration
-------------

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=tracekit-config
```

This creates `config/tracekit.php` where you can customize:

### Laravel 12 Setup

[](#laravel-12-setup)

Laravel 12 changed how middleware is registered. TraceKit attempts to register middleware automatically for all Laravel versions (10, 11, and 12).

**If automatic registration doesn't work**, you can manually add the TraceKit middleware to your `bootstrap/app.php`:

```
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use TraceKit\Laravel\Middleware\TracekitMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            TracekitMiddleware::class,
        ]);
        $middleware->api(append: [
            TracekitMiddleware::class,
        ]);
    })
    // ... rest of your configuration
    ->create();
```

For most cases, the automatic registration via the service provider should work without any manual configuration.

### Configuration Options

[](#configuration-options)

```
return [
    // Enable/disable tracing
    'enabled' => env('TRACEKIT_ENABLED', env('APP_ENV') !== 'local'),

    // Your TraceKit API key
    'api_key' => env('TRACEKIT_API_KEY', ''),

    // OTLP endpoint for sending traces
    'endpoint' => env('TRACEKIT_ENDPOINT', 'https://app.tracekit.dev/v1/traces'),

    // Service name as it appears in TraceKit
    'service_name' => env('TRACEKIT_SERVICE_NAME', env('APP_NAME', 'laravel-app')),

    // Sample rate (0.0 to 1.0)
    'sample_rate' => env('TRACEKIT_SAMPLE_RATE', 1.0),

    // Enable/disable specific features
    'features' => [
        'http' => env('TRACEKIT_HTTP_ENABLED', true),
        'database' => env('TRACEKIT_DATABASE_ENABLED', true),
        'cache' => env('TRACEKIT_CACHE_ENABLED', true),      // Coming soon
        'queue' => env('TRACEKIT_QUEUE_ENABLED', true),
        'redis' => env('TRACEKIT_REDIS_ENABLED', true),      // Coming soon
    ],

    // Routes to ignore
    'ignored_routes' => [
        '/health',
        '/up',
        '/_healthz',
    ],

    // Slow query threshold (ms)
    'slow_query_threshold' => env('TRACEKIT_SLOW_QUERY_MS', 100),

    // Include query bindings in traces
    'include_query_bindings' => env('TRACEKIT_INCLUDE_BINDINGS', true),

    // Map hostnames to service names for service graph
    'service_name_mappings' => [
        'localhost:8082' => 'payment-service',
        'localhost:8083' => 'user-service',
    ],
];
```

Code Monitoring (Live Debugging)
--------------------------------

[](#code-monitoring-live-debugging)

TraceKit includes production-safe code monitoring for live debugging without redeployment.

### Enable Code Monitoring

[](#enable-code-monitoring)

Add to your `.env` file:

```
TRACEKIT_CODE_MONITORING_ENABLED=true
TRACEKIT_CODE_MONITORING_POLL_INTERVAL=30  # How often to check for breakpoints (seconds)
                                            # Supported: 1, 5, 10, 15, 30, 60, 300, 600
                                            # Lower = faster updates, higher load
TRACEKIT_CODE_MONITORING_MAX_DEPTH=3       # Nested array/object inspection depth
TRACEKIT_CODE_MONITORING_MAX_STRING=1000   # Max length for captured strings
```

**Configuration Options:**

- **`enabled`**: Master switch for code monitoring (default: `false`)
- **`poll_interval`**: Background polling frequency in seconds (default: `30`)
    - `1` = Every second (highest load, instant updates)
    - `5` = Every 5 seconds (high load, very fast updates)
    - `10` = Every 10 seconds (moderate load, fast updates)
    - `30` = Every 30 seconds (recommended for production)
    - `60` = Every minute (low load, slower updates)
    - `300+` = Every 5+ minutes (very low load, periodic checks)
- **`max_variable_depth`**: How deep to inspect nested structures (default: `3`)
- **`max_string_length`**: Maximum string length to capture (default: `1000`)

### Add Debug Points

[](#add-debug-points)

Add checkpoints anywhere in your code to capture variable state and stack traces:

```