Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Observability

This page documents how to monitor, debug, and observe the Aero2 Worker in development and production.

Live Logs

Stream real-time logs from a running Worker using wrangler tail:

# QA environment
npx wrangler tail --env qa
 
# Production environment
npx wrangler tail --env production
 
# Pretty-printed output
npx wrangler tail --env production --format pretty
 
# Filter by status code
npx wrangler tail --env production --status error
 
# Filter by HTTP method
npx wrangler tail --env production --method POST
 
# Filter by search string
npx wrangler tail --env production --search "login_failed"

wrangler tail streams logs from all active Worker isolates. Each log entry includes the request URL, method, status code, and any console.log / console.error output from the Worker.

Structured Logging

In Workers, console.log() and console.error() output appears in wrangler tail. Use structured logging for machine-parseable output:

console.log(JSON.stringify({
  event: "login_success",
  user_id: user.id,
  app_id: app.id,
  idp: "github",
  timestamp: new Date().toISOString(),
}));

Logging Guidelines

  • Use console.log() for informational events (login, signup, token issuance)
  • Use console.error() for errors that need investigation
  • Never log sensitive data: passwords, tokens, secrets, full request bodies containing credentials
  • Include app_id in all log entries for filtering by application
  • Include relevant identifiers: user_id, client_id, session_id

Error Tracking

Unhandled exceptions in the Worker appear in wrangler tail as error-level entries. To catch and track errors:

  1. Check wrangler tail --status error for recent failures
  2. Look for stack traces in the log output
  3. The observability.enabled = true setting in wrangler.json enables Cloudflare's built-in request analytics

Health Checks

Aero2 exposes two health check endpoints:

Full Health Check

curl https://aero2.dev/health

Returns:

{
  "status": "healthy",
  "database": "ok",
  "version": "0.2.0"
}

This endpoint verifies:

  • Worker is running and responding
  • D1 database is accessible (runs a lightweight query)
  • Returns version information

Liveness Probe

curl https://aero2.dev/health/live

Returns:

{
  "status": "ok"
}

This is a lightweight endpoint that only verifies the Worker is running. It does not query the database. Use this for frequent health check polling.

Audit Logs

Security-relevant events are stored in the audit_logs D1 table and queryable via the API:

# Fetch recent audit logs (requires admin authentication)
curl -H "Authorization: Bearer <token>" https://aero2.dev/api/audit-logs

Audit log events include:

  • login / login_failed -- Authentication attempts
  • logout -- Session termination
  • user_created / user_updated / user_disabled -- User lifecycle
  • role_changed -- RBAC changes
  • client_created / client_updated / client_deleted -- OAuth client management
  • idp_created / idp_updated / idp_deleted -- Identity provider changes
  • session_revoked -- Session management

Each audit log entry includes:

  • user_id -- The acting user (NULL for failed logins and system events)
  • event_type -- The event category
  • event_data -- JSON with event-specific details
  • ip_address -- Client IP address
  • user_agent -- Client user agent string
  • created_at -- Timestamp

Cloudflare Dashboard

The Cloudflare dashboard provides additional observability:

  • Workers Analytics: Request counts, CPU time, errors, subrequest counts
  • D1 Analytics: Query counts, rows read/written, database size
  • Real-time Logs: Available in the Cloudflare dashboard under Workers > your-worker > Logs

Observability Configuration

In wrangler.json:

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1  // Sample 100% of requests
  }
}

Set head_sampling_rate to a value between 0 and 1 to control what percentage of requests are logged. Use 1 (100%) for development and QA, and consider lowering for high-traffic production environments.