From 525efb2de85f414e8d05d6e2fd9d885192b9f62c Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Tue, 25 Nov 2025 12:23:01 -0800 Subject: [PATCH] Claude: production observability guidance (#1725) --- CLAUDE.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index a7141f6a6..eb881cf25 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -137,6 +137,43 @@ Key recurring tasks (via `config/recurring.yml`): - Search records denormalized for performance - Models in `app/models/search/` +## Production Observability + +Grafana MCP tools provide access to production metrics and logs for performance analysis. + +### Datasources +| Name | UID | Use | +|------|-----|-----| +| Thanos (Prometheus) | `PC96415006F908B67` | Metrics, latencies | +| Loki | `e38bdfea-097e-47fa-a7ab-774fd2487741` | Application logs | + +### Key Metrics +- `rails_request_duration_seconds_bucket:rate1m:sum_by_app:quantiles{app="fizzy"}` - Request latency percentiles +- `rails_request_total:rate1m:sum_by_controller_action{app="fizzy"}` - Request rates by endpoint +- `fizzy_replica_wait_seconds` - Database replica consistency wait times + +### Loki Log Labels +Query: `{service_namespace="fizzy", deployment_environment_name="production", service_name="rails"}` + +Useful fields: `event_duration_ms`, `performance_time_db_ms`, `performance_time_cpu_ms`, `rails_endpoint`, `rails_controller` + +### Instrumentation +Yabeda-based metrics exported at `:9394/metrics`. Config in `config/initializers/yabeda.rb`. + +### Chrome MCP (Local Dev) +URL: `http://fizzy.localhost:3006` +Login: david@37signals.com (passwordless magic link auth - check rails console for link) + +Use Chrome MCP tools to interact with the running dev app for UI testing and debugging. + +### Sentry Error Tracking +Organization: `basecamp` | Project: `fizzy` | Region: `https://us.sentry.io` + +Use Sentry MCP tools to investigate production errors: +- `search_issues` - Find grouped issues by natural language query +- `get_issue_details` - Get full stacktrace and context for a specific issue +- `analyze_issue_with_seer` - AI-powered root cause analysis with code fix suggestions + ## Coding style Please read the separate file `STYLE.md` for some guidance on coding style.