playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-observability

supabase-observability skill

/plugins/saas-packs/supabase-pack/skills/supabase-observability

This skill helps you establish comprehensive Supabase observability with metrics, traces, and alerts across services.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill supabase-observability

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.6 KB
---
name: supabase-observability
description: |
  Execute set up comprehensive observability for Supabase integrations with metrics, traces, and alerts.
  Use when implementing monitoring for Supabase operations, setting up dashboards,
  or configuring alerting for Supabase integration health.
  Trigger with phrases like "supabase monitoring", "supabase metrics",
  "supabase observability", "monitor supabase", "supabase alerts", "supabase tracing".
allowed-tools: Read, Write, Edit
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Observability

## Prerequisites
- Prometheus or compatible metrics backend
- OpenTelemetry SDK installed
- Grafana or similar dashboarding tool
- AlertManager configured

## Instructions

### Step 1: Set Up Metrics Collection
Implement Prometheus counters, histograms, and gauges for key operations.

### Step 2: Add Distributed Tracing
Integrate OpenTelemetry for end-to-end request tracing.

### Step 3: Configure Structured Logging
Set up JSON logging with consistent field names.

### Step 4: Create Alert Rules
Define Prometheus alerting rules for error rates and latency.

## Output
- Metrics collection enabled
- Distributed tracing configured
- Structured logging implemented
- Alert rules deployed

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Prometheus Best Practices](https://prometheus.io/docs/practices/naming/)
- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
- [Supabase Observability Guide](https://supabase.com/docs/observability)

Overview

This skill sets up comprehensive observability for Supabase integrations using metrics, traces, structured logs, and alerting. It provides a practical sequence: metrics instrumentation with Prometheus, distributed tracing with OpenTelemetry, JSON structured logging, and Prometheus alert rules. The result is end-to-end visibility into Supabase operation health and performance.

How this skill works

The skill instruments key Supabase operations with Prometheus counters, histograms, and gauges to capture throughput, latency, and error rates. It integrates OpenTelemetry SDK to create distributed traces across client requests and backend processing. Logs are emitted in JSON with consistent field names to correlate with traces and metrics. Finally, Prometheus alert rules and Alertmanager notifications are configured to trigger on high error rates and SLO breaches.

When to use it

  • Implementing monitoring for a new or existing Supabase integration
  • Setting up dashboards to visualize Supabase query latency and error trends
  • Adding end-to-end tracing to diagnose slow requests or service boundaries
  • Configuring alerts to detect outages or degraded performance
  • Driving SLO-based operations and incident response for Supabase services

Best practices

  • Instrument key user-facing operations and background jobs with counters and histograms
  • Use semantic metric names and labels following Prometheus naming conventions
  • Propagate trace context through API calls and background workers with OpenTelemetry
  • Emit structured JSON logs with stable fields (request_id, user_id, trace_id, status, duration)
  • Create alert rules for error rate spikes, latency SLO breaches, and missing telemetry
  • Visualize metrics and traces together in Grafana for fast root-cause analysis

Example use cases

  • Track average and p99 query latency for Supabase REST and RPC endpoints
  • Alert when 5xx error rate exceeds 1% over a 5-minute window
  • Trace a slow signup flow to find a slow third-party call or database query
  • Correlate JSON logs and traces to identify a specific failed transaction by request_id
  • Export Prometheus metrics to long-term storage and build historical dashboards

FAQ

What backends do I need?

You need a Prometheus-compatible metrics backend, an OpenTelemetry collector or SDK, Grafana or similar for dashboards, and Alertmanager for alerts.

How do I correlate logs, traces, and metrics?

Include stable identifiers like request_id and trace_id in structured logs, emit trace context with OpenTelemetry, and use the same labels in Prometheus metrics to enable cross-correlation.