Laravel Project Guide

Use this guide for Laravel services that need stable incident context across request lifecycle and queue jobs.

Architecture Scope

HTTP kernel and middleware stack.
Controllers/services/repositories.
Queue workers and scheduled jobs.

Setup

Create a service provider to initialize the SDK:

app/Providers/ObtraceServiceProvider.php

<?php
 
namespace App\Providers;
 
use Illuminate\Support\ServiceProvider;
use Obtrace\Sdk\ObtraceClient;
use Obtrace\Sdk\ObtraceConfig;
 
class ObtraceServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(ObtraceClient::class, function () {
            return new ObtraceClient(new ObtraceConfig(
                apiKey: config("services.obtrace.api_key"),
                serviceName: "order-api",
                env: app()->environment(),
                serviceVersion: config("app.version", "1.0.0"),
            ));
        });
    }
}

Create middleware for HTTP request instrumentation:

app/Http/Middleware/ObtraceMiddleware.php

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Obtrace\Sdk\ObtraceClient;
 
class ObtraceMiddleware
{
    public function __construct(private ObtraceClient $client) {}
 
    public function handle(Request $request, Closure $next)
    {
        $start = microtime(true);
        $response = $next($request);
        $durationMs = (microtime(true) - $start) * 1000;
 
        $route = $request->route()?->uri() ?? $request->getPathInfo();
        $method = $request->getMethod();
 
        $this->client->span("http.server {$method} /{$route}", attrs: [
            "http.method" => $method,
            "http.route" => "/{$route}",
            "http.status_code" => $response->getStatusCode(),
        ]);
 
        $this->client->metric("http.server.request.duration", $durationMs, "ms", [
            "http.method" => $method,
            "http.route" => "/{$route}",
            "http.status_code" => $response->getStatusCode(),
        ]);
 
        return $response;
    }
}

->withMiddleware(function ($middleware) {
    $middleware->append(\App\Http\Middleware\ObtraceMiddleware::class);
})

Environment Variables

.env

OBTRACE_API_KEY=obt_...

Add to config/services.php:

'obtrace' => [
    'api_key' => env('OBTRACE_API_KEY'),
],

Validation Checklist

Web requests emit logs and spans
Queue jobs emit telemetry with same environment tags
Failed jobs include enough context for triage
error_log() calls appear in Obtrace

Production Hardening

Keep credentials in deployment secret stores, not .env in version control.
Use queue-safe buffering settings.
Validate observability after framework upgrades.

Troubleshooting

Web data present but queue data missing: initialize SDK in worker context too.
Noisy logs: restrict low-value events.
Correlation breaks: enforce shared request/job identifiers.