micsapp Linear Observability
Contents
Overview
Comprehensive monitoring, logging, and alerting for Linear integrations using Prometheus metrics, structured logging, and health checks.
Prerequisites
- Linear integration deployed
- Metrics infrastructure (Prometheus, Datadog, etc.)
- Logging infrastructure (ELK, CloudWatch, etc.)
- Alerting system configured
Instructions
Step 1: Define Key Metrics
| Metric | Type | Purpose |
|---|---|---|
linear_api_requests_total |
Counter | Track request volume by operation/status |
linear_api_request_duration_seconds |
Histogram | Measure API latency |
linear_rate_limit_remaining |
Gauge | Monitor rate limit headroom |
linear_webhooks_received_total |
Counter | Track webhook volume |
linear_cache_hits_total |
Counter | Measure cache effectiveness |
Step 2: Instrument the Client
Wrap the Linear SDK's fetch layer to capture metrics on every API call including operation name, duration, status, and rate limit headers.
Step 3: Add Structured Logging
Use pino/winston with JSON output, component tags, and correlation IDs for API calls, webhooks, and errors.
Step 4: Create Health Check Endpoint
Verify API connectivity, cache status, and rate limit headroom. Return healthy, degraded, or unhealthy status.
Step 5: Configure Alerting Rules
- High error rate (>5% over 5 min)
- Rate limit low (<100 remaining)
- Slow responses (p95 > 2s)
- Webhook processing errors
Step 6: Build Grafana Dashboard
Panels for request rate, latency p95, rate limit remaining, and webhook distribution.
See detailed implementation for full Prometheus metrics, instrumented client, logger, health check, alert rules, and Grafana dashboard JSON.
Output
- Prometheus metrics collecting on all Linear API calls
- Structured JSON logging for API calls and webhooks
- Health check endpoint returning system status
- Alerting rules for error rate, rate limits, and latency
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Metrics not collecting | Missing instrumentation | Wrap client with instrumented fetch |
| Alerts not firing | Wrong threshold | Adjust alert thresholds to match traffic |
| Missing labels | Logger misconfigured | Check logger base config and child loggers |
Examples
Quick Health Check
set -euo pipefail
curl http://localhost:3000/health/linear | jq # 3000: 3 seconds in ms
# { "status": "healthy", "checks": { "linear_api": { "status": "healthy", "latency_ms": 150 } } }
Resources
Next Steps
Create incident runbooks with linear-incident-runbook.