👁️ Topic 29: Observability

// Structured logging (JSON) - machine readable
Log::channel('stack')->info('User registered', [
    'user_id' => $user->id,
    'ip' => $request->ip(),
    'user_agent' => $request->userAgent(),
    'correlation_id' => $this->correlationId,
]);

// With context (Laravel 11+)
Log::withContext([
    'user_id' => auth()->id(),
    'correlation_id' => $this->correlationId,
    'request_id' => request()->id(),
]);

Log::info('Processing order');
Log::info('Order processed');  // Both include context

// Always include correlation ID for distributed tracing
$correlationId = request()->header('X-Correlation-ID', Str::uuid());
Log::shareContext(['correlation-id' => $correlationId]);

// Install package
composer require ssmdd/laravel-prometheus-exporter

// Create a metric
use Prometheus\Facades\Prometheus;

// Counter
Prometheus::counter('http_requests_total', 'Total HTTP requests')
    ->labels(['method' => $request->method(), 'path' => $request->path()])
    ->inc();

// Histogram (request duration)
$duration = microtime(true) - LARAVEL_START;
Prometheus::histogram('http_request_duration_seconds', 'Request duration in seconds')
    ->labels(['method' => $request->method()])
    ->observe($duration);

// Gauge (active users)
Prometheus::gauge('active_users', 'Currently active users')
    ->set(Cache::get('active_users_count', 0));

// Export metrics endpoint
Route::get('/metrics', fn() => Prometheus::render());

// Install OpenTelemetry
composer require open-telemetry/opentelemetry
composer require open-telemetry/exporter-jaeger

// app/Http/Middleware/TracingMiddleware.php
use OpenTelemetry\API\Trace\TracerInterface;
use OpenTelemetry\API\Trace\SpanKind;

class TracingMiddleware
{
    public function handle($request, $next)
    {
        $tracer = app(TracerInterface::class);
        
        $span = $tracer->spanBuilder('HTTP ' . $request->method())
            ->setSpanKind(SpanKind::KIND_SERVER)
            ->startSpan();
        
        $scope = $span->activate();
        
        $response = $next($request);
        
        $span->setAttribute('http.method', $request->method());
        $span->setAttribute('http.url', $request->fullUrl());
        $span->setAttribute('http.status_code', $response->getStatusCode());
        $span->end();
        
        $scope->detach();
        
        return $response;
    }
}

// Manual tracing in code
use OpenTelemetry\API\Trace\Span;

$span = Span::getCurrent();
$span->setAttribute('user.id', $user->id);

// Create nested span for database query
$dbSpan = $tracer->spanBuilder('DB Query')
    ->setParent($span->getContext())
    ->startSpan();

try {
    $users = DB::table('users')->get();
    $dbSpan->setAttribute('db.statement', 'SELECT * FROM users');
} finally {
    $dbSpan->end();
}

// app/Http/Middleware/CorrelationIdMiddleware.php
class CorrelationIdMiddleware
{
    public function handle($request, $next)
    {
        $correlationId = $request->header('X-Correlation-Id', (string) Str::uuid());
        
        // Share with logging
        Log::shareContext(['correlation-id' => $correlationId]);
        
        // Share with application
        app()->instance('correlation-id', $correlationId);
        
        $response = $next($request);
        
        $response->header('X-Correlation-Id', $correlationId);
        
        return $response;
    }
}

// Usage in code
$correlationId = app('correlation-id');
Log::info("Processing order {$orderId}", ['correlation-id' => $correlationId]);

// Pass to external services
Http::withHeaders([
    'X-Correlation-Id' => $correlationId
])->post('https://api.payment.com', $data);

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

// config/telescope.php
'enabled' => env('TELESCOPE_ENABLED', true),

// .env (development)
TELESCOPE_ENABLED=true

// .env (production) - use sparingly
TELESCOPE_ENABLED=false  # Never enable in high-traffic production

# docker-compose.yml
version: '3'
services:
  loki:
    image: grafana/loki:latest
  tempo:
    image: grafana/tempo:latest
  mimir:
    image: grafana/mimir:latest
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_FEATURE_TOGGLES_ENABLE=tempoLokiSearch