Monitoring & Logging¶

Logging¶

Arca uses the tracing framework for structured logging. The log format and level are configured at server startup.

Log Format¶

arca serve --log-format text    # Human-readable (default)
arca serve --log-format json    # Structured JSON (for log aggregation)

JSON format outputs one JSON object per line, suitable for ingestion by log aggregation tools (ELK, Loki, Datadog, etc.).

Log Level¶

Control verbosity with the ARCA_LOG environment variable:

ARCA_LOG=info     # Default — requests, startup, errors
ARCA_LOG=debug    # Detailed internal operations
ARCA_LOG=warn     # Warnings and errors only
ARCA_LOG=trace    # Maximum verbosity (very noisy)

In Docker Compose:

services:
  arca:
    environment:
      - ARCA_LOG=info

Per-Module Filtering¶

ARCA_LOG supports per-module filtering:

# Debug logging for auth, info for everything else
ARCA_LOG=info,arca_auth=debug

# Trace storage operations
ARCA_LOG=info,arca_storage=trace

Health Checks¶

Endpoint¶

GET /admin/health

No authentication required, designed for load balancer and container orchestrator probes.

Status	Code	Body	Meaning
Healthy	200	`{"status":"ok"}`	Server is running and accepting requests
Draining	503	`{"status":"draining"}`	Server received SIGTERM/SIGINT, draining in-flight connections before shutdown

During graceful shutdown, the health endpoint returns 503 for drain_timeout_seconds (default: 30), giving load balancers time to remove the instance from rotation before connections are closed.

Docker HEALTHCHECK¶

Add a health check to your Docker Compose configuration:

services:
  arca:
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9000/admin/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s

Note

The production image is built from scratch and does not include curl or wget. Use wget from the development image, or check health from a sidecar container or external probe.

Load Balancer Probes¶

Point your load balancer's health check at /admin/health:

Path: /admin/health
Expected healthy status: 200
Expected healthy body: {"status":"ok"}
Drain status: 503 with {"status":"draining"} — remove instance from rotation
Interval: 10–30 seconds (should be ≤ drain_timeout_seconds)

Server Metrics¶

Arca exposes server information and storage statistics via the Admin API. These endpoints require SigV4 authentication with admin credentials.

Server Info¶

GET /admin/info

{
    "version": "0.1.0",
    "uptime_seconds": 3600
}

Storage Stats¶

GET /admin/stats

{
    "bucket_count": 5,
    "object_count": 142,
    "total_size_bytes": 1073741824
}

Polling Example¶

Use a cron job or monitoring agent to poll stats periodically:

#!/usr/bin/env bash
# Poll Arca stats using aws-cli for SigV4 signing
aws s3api --endpoint-url http://localhost:9000 \
  list-buckets --query 'Buckets | length(@)' --output text

Or use the Admin API directly with any HTTP client that supports SigV4 signing. See the Admin API reference for the full endpoint list.