Logging

S-Auth integrates with Better Stack for centralized log management, providing visibility into authentication requests, errors, and system events.

Log Destinations

Console Logs

All logs are written to the console and visible in:

• wrangler dev output (local development)
• Cloudflare Workers logs (production)

Better Stack

When configured, logs are also sent to Better Stack for:

• Long-term storage
• Search and filtering
• Alerting
• Dashboards

Configuration

Required Secrets

Set these Cloudflare secrets for Better Stack integration:

# Get these from Better Stack dashboard
wrangler secret put BETTER_STACK_TOKEN
wrangler secret put BETTER_STACK_HOST

BETTER_STACK_TOKEN: Your source token from Better Stack BETTER_STACK_HOST: The ingesting host (e.g., logs.betterstack.com)

Finding Your Credentials

1. Go to Better Stack Logs
2. Create or select a source
3. Copy the Source Token
4. Copy the Ingesting Host

---

Log Format

Logs are structured JSON with consistent fields:

{
  "level": "info",
  "message": "Request completed",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "service": "s-auth-oauth-provider",
  "method": "POST",
  "path": "/token",
  "status": 200,
  "duration_ms": 45,
  "cf": {
    "country": "US",
    "colo": "DFW"
  }
}

Common Fields

Field	Description
level	Log level (debug, info, warn, error)
message	Human-readable description
timestamp	ISO 8601 timestamp
service	Always s-auth-oauth-provider
method	HTTP method
path	Request path
status	HTTP response status
duration_ms	Request processing time
cf.country	User's country (from Cloudflare)
cf.colo	Cloudflare data center

Error Fields

Error logs include additional fields:

{
  "level": "error",
  "message": "Request failed",
  "error": "Invalid client credentials",
  "stack": "Error: Invalid client credentials\n    at validateClient..."
}

---

Log Levels

debug

Detailed debugging information. Not enabled by default in production.

{
  "level": "debug",
  "message": "PKCE verification started",
  "client_id": "my-app"
}

info

Normal operational events.

{
  "level": "info",
  "message": "Request completed",
  "path": "/token",
  "status": 200
}

warn

Warning conditions that don't prevent operation.

{
  "level": "warn",
  "message": "Rate limit approaching",
  "client_id": "my-app",
  "requests": 45
}

error

Error conditions that require attention.

{
  "level": "error",
  "message": "Database query failed",
  "error": "Connection timeout"
}

---

What Gets Logged

Logged Events

Event	Level	Details
Request completed	info	method, path, status, duration
Request failed	error	method, path, error, stack
Scheduled cleanup	info	timestamp
Cleanup failed	error	error message

Not Logged

For security reasons, these are NOT logged:

• Passwords (plain or hashed)
• Access tokens
• Refresh tokens
• Client secrets
• Authorization codes
• User email addresses (in most cases)

Health Check Exclusion

Health check requests (/health, /health/detailed, /metrics) are NOT logged to reduce noise.

---

Better Stack Features

Searching Logs

Use Better Stack's query language:

# Find all errors
level:error

# Find requests to token endpoint
path:/token

# Find slow requests
duration_ms:>1000

# Find requests from a specific country
cf.country:US

# Combine queries
level:error AND path:/token

Creating Alerts

1. Go to Better Stack Logs
2. Click Alerts → Create Alert
3. Configure:

Setting	Example Value
Query	level:error
Threshold	More than 10 in 5 minutes
Channel	Slack, Email, PagerDuty

Dashboard Widgets

Create dashboards with:

• Error rate over time
• Request volume by endpoint
• Response time percentiles
• Geographic distribution

---

Local Development

Viewing Logs

During local development:

cd oauth-provider
npm run dev

Logs appear in the terminal:

[INFO] Request completed { method: 'POST', path: '/token', status: 200, duration_ms: 12 }
[ERROR] Request failed { method: 'POST', path: '/token', error: 'Invalid client' }

Without Better Stack

If BETTER_STACK_TOKEN or BETTER_STACK_HOST is not set:

[Logger] Missing BETTER_STACK_TOKEN or BETTER_STACK_HOST, skipping flush

This is normal for local development. Logs still appear in the console.

---

Troubleshooting

Logs Not Appearing in Better Stack

1. Check secrets are set:

   wrangler secret list

   Should show BETTER_STACK_TOKEN and BETTER_STACK_HOST

2. Check for errors in console: Look for [Logger] Better Stack responded with... messages

3. Verify credentials:

   • Token should be from "Source Token" in Better Stack
   • Host should be the full ingesting URL

401 Unauthorized from Better Stack

[Logger] Better Stack responded with 401: {"error": "Unauthorized"}

Cause: Invalid source token

Solution:

1. Go to Better Stack Logs
2. Select your source
3. Copy the correct source token
4. Update the secret:

   wrangler secret put BETTER_STACK_TOKEN

High Log Volume

If logs are overwhelming:

1. Filter in Better Stack - Use queries to focus on important events
2. Adjust log level - Consider reducing debug logs
3. Review logged events - Ensure you're not over-logging

---

Best Practices

1. Don't log sensitive data - Never log tokens, passwords, or secrets
2. Use structured logging - Always include relevant context
3. Set up alerts - Monitor for errors and anomalies
4. Retain logs appropriately - Balance storage costs with debugging needs
5. Review logs regularly - Look for patterns and issues