Monitoring and Observability

Baander provides several built-in endpoints and commands for monitoring system health, background jobs, and performance metrics. This page covers what is available and how to use it.

Health Checks

Baander exposes three HTTP endpoints for health probing. None of these require authentication.

These are designed for orchestration use. The /health endpoint is used by the Docker healthcheck defined in docker-compose.yml:

healthcheck:
    test: ["CMD", "php", "bin/console", "app:health:check"]
    interval: 30s
    timeout: 5s
    retries: 3
    start_period: 15s

CLI health check

You can also run the health check from the command line inside the container. It prints a table with per-component status and latency:

make exec cmd="php bin/console app:health:check"

This runs the same checks as the /health endpoint and exits with code 0 on success or 1 if any component is unhealthy. See the full command reference.

What is checked

The health check verifies four components:

Job Monitoring

Background jobs (library scans, transcoding, notifications) are tracked by a job monitoring system. All job endpoints require authentication with ROLE_ADMIN.

Status overview

Get a quick summary of all jobs grouped by status, plus a list of currently running jobs:

curl -s -H "Authorization: Bearer $TOKEN" https://baander.test/api/monitor/status | jq .

The response includes counts (jobs per status) and running (active jobs with progress).

Job list with filtering

Browse jobs with filtering, sorting, and cursor-based pagination:

# Failed jobs, sorted by creation date
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/jobs?status=failed&sort=createdAt&direction=desc&limit=20" | jq .

# Scan jobs
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/jobs?name=scan" | jq .

Available filters: status (queued, running, finished, failed, cancelled), name (partial match), queue (exact match).

Job detail

Get the full record for a specific job, including exception details for failures:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/jobs/<jobId>" | jq .

Retry and cancel

You can retry failed jobs or cancel running/queued jobs through the API:

# Retry a failed job
curl -X POST -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/jobs/<jobId>/retry" | jq .

# Cancel a running or queued job
curl -X POST -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/jobs/<jobId>/cancel" | jq .

Cancellation is cooperative -- the job handler must check for the cancellation flag at its next checkpoint. Queued jobs are flagged before the worker picks them up.

Job Analytics

The analytics endpoints provide aggregate insights into job performance over a time range. All require ROLE_ADMIN.

Summary

Status counts, job type breakdown, success rate, and throughput:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/analytics/summary?from=2026-04-20T00:00:00Z&to=2026-04-21T00:00:00Z" | jq .

Defaults to the last 24 hours if from and to are omitted. Maximum range is 90 days.

Timing

Average, median, and P95 execution times per job type, plus average queue latency:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/analytics/timing" | jq .

Failures

Top failing job types, top exception classes, retry frequency, and recent failure details:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/analytics/failures?limit=20" | jq .

Server Stats

The server stats endpoint returns a snapshot of the current worker process state. Requires ROLE_ADMIN.

curl -s -H "Authorization: Bearer $TOKEN" https://baander.test/api/debug/stats | jq .

The response includes:

Use this for lightweight debugging of memory leaks, connection exhaustion, or hangs without setting up external monitoring.

Prometheus Metrics

Baander exposes a Prometheus-compatible metrics endpoint at GET /metrics. No authentication is required.

curl -s https://baander.test/metrics

The endpoint returns metrics in Prometheus text exposition format (text/plain; version=0.0.4). Available metrics:

Prometheus scrape configuration

Point your Prometheus scrape config to the /metrics endpoint:

scrape_configs:
  - job_name: 'baander'
    scrape_interval: 15s
    static_configs:
      - targets: ['baander-app:9501']
    metrics_path: '/metrics'

Grafana dashboard setup is out of scope for this guide.

Rate Limiter Monitor

Inspect and manage configured rate limiters. Requires ROLE_ADMIN.

List all rate limiters

curl -s -H "Authorization: Bearer $TOKEN" https://baander.test/api/monitor/rate-limiters | jq .

This returns the full catalog of configured rate limiters with their policy, limit, interval, and description. It reads from a static catalog that must be kept in sync with config/packages/framework.yaml.

Clear rate limiter state

To unblock rate-limited users (for example, after a configuration change or during an incident), clear the shared rate limiter cache pool:

curl -X DELETE -s -H "Authorization: Bearer $TOKEN" \
  "https://baander.test/api/monitor/rate-limiters/auth_login_ip/clear?confirm=true" | jq .

Since all rate limiters share the same Redis-backed cache pool, this clears state for every limiter, not just the named one.

Configuration Check

Validate your application configuration from the CLI or the API.

CLI

make exec cmd="php bin/console app:config:validate"

This runs all configuration checks and prints a table of results. See the full command reference.

API

curl -s -H "Authorization: Bearer $TOKEN" https://baander.test/api/debug/config-check | jq .

The endpoint validates environment variables, key file existence, secret strength, and framework config. It returns a summary with errors, warnings, and passed counts. Rate-limited to prevent abuse.

What is checked

Logs

Container names

Makefile commands

The Makefile provides several targets for viewing logs:

The hl-* commands pipe through ./hl for colorized output. If hl is not installed, use the plain docker logs commands directly.

Direct Docker commands

# Follow app logs
docker logs -f baander-app

# Last 100 lines of postgres logs
docker logs --tail 100 baander-postgres

# Redis logs since a specific time
docker logs --since 2026-04-21T10:00:00 baander-redis

# All containers at once
docker compose logs -f

Log locations inside containers

To view nginx access logs inside the container:

make exec cmd="tail -100 /var/log/nginx/access.log"

Quick Reference

See Also

• CLI Reference: app:health:check
• CLI Reference: app:config:validate
• Troubleshooting