Skip to main content

Metrics

S-Auth exposes Prometheus-compatible metrics for monitoring system usage and performance.

Endpoint​

GET /metrics

Returns metrics in Prometheus text format.

Available Metrics​

sauth_users_total​

Total number of registered users.

# HELP sauth_users_total Total number of users
# TYPE sauth_users_total gauge
sauth_users_total 42

Use Cases:

  • Track user growth over time
  • Alert on unexpected changes

sauth_clients_total​

Total number of registered OAuth clients (applications).

# HELP sauth_clients_total Total number of OAuth clients
# TYPE sauth_clients_total gauge
sauth_clients_total 5

Use Cases:

  • Track application registrations
  • Capacity planning

sauth_active_sessions​

Number of active user sessions (not expired).

# HELP sauth_active_sessions Active sessions count
# TYPE sauth_active_sessions gauge
sauth_active_sessions 15

Use Cases:

  • Monitor current user activity
  • Identify usage patterns
  • Alert on unusual session counts

sauth_active_tokens​

Number of active access tokens (not expired).

# HELP sauth_active_tokens Active access tokens count
# TYPE sauth_active_tokens gauge
sauth_active_tokens 28

Use Cases:

  • Monitor API usage
  • Detect token accumulation issues
  • Capacity planning

Prometheus Integration​

Prometheus Configuration​

Add S-Auth to your prometheus.yml:

scrape_configs:
  - job_name: 's-auth'
    scrape_interval: 60s
    scheme: https
    static_configs:
      - targets: ['auth.sebbyk.net']
    metrics_path: /metrics

Scrape Interval​

Recommended: 60 seconds

The metrics endpoint queries the database, so avoid scraping too frequently.

Grafana Dashboards​

Basic Dashboard​

Create a Grafana dashboard with these panels:

User Growth​

sauth_users_total
  • Visualization: Stat or Time series
  • Shows total user count

Active Sessions​

sauth_active_sessions
  • Visualization: Gauge
  • Set thresholds based on expected usage

Active Tokens​

sauth_active_tokens
  • Visualization: Time series
  • Track token usage patterns

OAuth Clients​

sauth_clients_total
  • Visualization: Stat
  • Track registered applications

Example Dashboard JSON​

{
  "title": "S-Auth Overview",
  "panels": [
    {
      "title": "Total Users",
      "type": "stat",
      "targets": [
        {
          "expr": "sauth_users_total"
        }
      ]
    },
    {
      "title": "Active Sessions",
      "type": "gauge",
      "targets": [
        {
          "expr": "sauth_active_sessions"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "thresholds": {
            "steps": [
              { "value": 0, "color": "green" },
              { "value": 50, "color": "yellow" },
              { "value": 100, "color": "red" }
            ]
          }
        }
      }
    }
  ]
}

Alerting Rules​

Prometheus Alerting​

Create alerting rules in Prometheus:

groups:
  - name: s-auth-alerts
    rules:
      # Alert if no active sessions (possible outage)
      - alert: SAuthNoActiveSessions
        expr: sauth_active_sessions == 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "No active S-Auth sessions"
          description: "No active sessions for 10 minutes - possible auth issue"

      # Alert if session count drops significantly
      - alert: SAuthSessionDrop
        expr: |
          (sauth_active_sessions - sauth_active_sessions offset 1h)
          / sauth_active_sessions offset 1h < -0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "S-Auth session count dropped significantly"
          description: "Session count dropped by more than 50% in the last hour"

      # Alert on unusual token accumulation
      - alert: SAuthTokenAccumulation
        expr: sauth_active_tokens > 1000
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "High active token count"
          description: "More than 1000 active tokens - check for token leaks"

Best Practices​

Metric Collection​

  1. Don't scrape too frequently - 60 second intervals are sufficient
  2. Set up long-term storage - Keep metrics history for trend analysis
  3. Use labels wisely - Current metrics don't have labels; future versions may add them

Dashboard Design​

  1. Start simple - Add complexity as you learn usage patterns
  2. Set meaningful thresholds - Based on your actual usage
  3. Include time ranges - Show 24h, 7d, 30d views

Alerting​

  1. Avoid alert fatigue - Only alert on actionable conditions
  2. Use "for" clauses - Prevent flapping alerts
  3. Document runbooks - Link to troubleshooting guides

Limitations​

Current Limitations​

  • Metrics are point-in-time gauges (no histograms)
  • No request rate metrics (use Cloudflare Analytics)
  • No latency percentiles (use Better Stack logs)

Future Improvements​

Planned metrics:

  • Request rates by endpoint
  • Authentication success/failure rates
  • Token grant type distribution
  • Latency histograms

Alternative: Cloudflare Analytics​

For request-level metrics, use Cloudflare Analytics:

  1. Go to Cloudflare Dashboard
  2. Select your Workers route
  3. View:
    • Request counts
    • Error rates
    • Response times
    • Geographic distribution

This complements the application-level metrics from /metrics.