Observability & Health Checks

Cbox images include infrastructure-level observability out of the box (Prometheus metrics on port 9090, process health checks). This guide adds application-level observability using three optional packages from Cbox.

Overview

All three packages are optional. Install only what you need.

Laravel Health

Application-level health checks with Kubernetes-ready probe endpoints.

• Package: cbox.dk/packages/laravel-health
• Docs: cbox.dk/packages/laravel-health/docs

Install

composer require cboxdk/laravel-health
php artisan vendor:publish --tag="health-config"

What it checks

Endpoints

Returns HTTP 200 when healthy, 503 when critical. Warnings still return 200.

Using with Cbox Init

php-fpm-nginx (HTTP health check):

The liveness endpoint at /health/ requires no authentication and works directly as a cbox-init health check. However, the default Nginx config includes a static /health location block that returns "healthy" without reaching PHP-FPM. Use the trailing-slash path to reach Laravel:

# docker-compose.yml
services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
    environment:
      LARAVEL_SCHEDULER: "true"

To use application-level health checks instead of the static Nginx response, mount a custom cbox-init.yaml with the health check URL pointing to /health/:

# custom-cbox-init.yaml (partial)
processes:
  nginx:
    health_check:
      type: http
      url: "http://127.0.0.1:80/health/"
      expected_status: 200
      period: 30
      timeout: 10

php-cli (exec health check):

For CLI workloads with no web server, use the health:check artisan command:

# custom-cbox-init.yaml (partial)
processes:
  queue-default:
    health_check:
      type: exec
      command: ["php", "artisan", "health:check", "--endpoint=readiness"]
      period: 30
      timeout: 10

This verifies DB, Redis, cache, and queue connectivity before considering the worker healthy.

Scheduler heartbeat

Add to your Laravel scheduler to enable ScheduleCheck:

// routes/console.php or app/Console/Kernel.php
Schedule::command('health:heartbeat')->everyMinute();

When LARAVEL_SCHEDULER=true, cbox-init runs schedule:work which picks this up automatically.

Laravel Queue Metrics

Production-grade queue observability with per-job performance tracking and Prometheus export.

• Package: cbox.dk/packages/laravel-queue-metrics
• Docs: cbox.dk/packages/laravel-queue-metrics/docs

Install

composer require cboxdk/laravel-queue-metrics

Zero configuration needed — the package hooks into Laravel's queue events automatically.

What it tracks

Per job class:

• Duration: avg, P50, P95, P99, max
• Memory: avg, peak, P95, P99 (real RSS via /proc, including child processes)
• CPU time per job
• Success/failure counts and rates
• Throughput (jobs/min, jobs/hour)

Per queue:

• Pending, delayed, reserved job counts
• Oldest job age (backlog staleness)
• Throughput and failure rates

Workers:

• Active/idle counts and utilization percentage
• Stale worker detection
• Horizon-aware (includes supervisor context)

Baselines & Trends:

• Automatic performance baselines with deviation detection
• Linear regression trends with forecasting

Prometheus endpoint

Exposed at /queue-metrics/prometheus. Namespace configurable via QUEUE_METRICS_PROMETHEUS_NAMESPACE (default: laravel_queue).

Combined Prometheus scrape config

Scrape both cbox-init infrastructure metrics and application metrics:

# prometheus.yml
scrape_configs:
  - job_name: cbox-init
    static_configs:
      - targets: ['app:9090']
    metrics_path: /metrics

  - job_name: laravel-health
    static_configs:
      - targets: ['app:80']
    metrics_path: /health/metrics

  - job_name: laravel-queue
    static_configs:
      - targets: ['app:80']
    metrics_path: /queue-metrics/prometheus

Environment variables

What cbox-init sees vs what queue-metrics sees

Laravel Queue Autoscale

Dynamic queue worker scaling based on real-time queue depth, arrival rates, and SLA targets.

• Package: cbox.dk/packages/laravel-queue-autoscale
• Docs: cbox.dk/packages/laravel-queue-autoscale/docs

Install

composer require cboxdk/laravel-queue-autoscale
php artisan vendor:publish --tag="queue-autoscale-config"

Requires cboxdk/laravel-queue-metrics (installed automatically as a dependency).

How it works

The autoscaler runs as a long-lived process that evaluates every 5 seconds:

1. Rate-based (Little's Law): workers = arrival_rate × avg_job_time
2. Trend-based (predictive): Applies a growth buffer (10-30%) based on trend direction
3. Backlog-based (SLA protection): Calculates workers needed to drain the queue before SLA breach
4. Takes the maximum of all three, then clamps to resource limits (CPU, memory) and configured min/max bounds

Using with Cbox Init

The autoscaler spawns its own queue:work child processes — it does not use cbox-init's scale API. When using the autoscaler, disable cbox-init's own queue workers to avoid conflicts:

# docker-compose.yml
services:
  autoscaler:
    image: ghcr.io/cboxdk/php-baseimages/php-cli:8.4-bookworm
    environment:
      CBOX_QUEUE_AUTOSCALER: "true"
      # Do NOT set LARAVEL_QUEUE or LARAVEL_QUEUE_HIGH — autoscaler manages workers itself

This runs php artisan queue:autoscale as a cbox-init managed process, which then spawns and manages its own queue workers dynamically.

Profile presets

Environment variables

Configure per-queue SLA targets in config/queue-autoscale.php. The main env vars:

Full Stack Example

Complete Laravel setup with all three packages:

services:
  # Web application with health checks
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
    ports:
      - "80:80"
      - "9090:9090"    # cbox-init Prometheus metrics
    environment:
      LARAVEL_SCHEDULER: "true"
      LARAVEL_OPTIMIZE_ENABLED: "true"

  # Queue autoscaler (manages its own workers)
  autoscaler:
    image: ghcr.io/cboxdk/php-baseimages/php-cli:8.4-bookworm
    environment:
      CBOX_QUEUE_AUTOSCALER: "true"
    volumes:
      - ./:/var/www/html
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy

  # Prometheus
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9091:9090"

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: laravel
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 5

# prometheus.yml
scrape_configs:
  - job_name: cbox-init
    static_configs:
      - targets: ['app:9090']

  - job_name: laravel-health
    static_configs:
      - targets: ['app:80']
    metrics_path: /health/metrics

  - job_name: laravel-queue
    static_configs:
      - targets: ['app:80']
    metrics_path: /queue-metrics/prometheus