Linear Observability
Overview
Production monitoring for Linear integrations using Prometheus metrics, structured logging with pino, health checks, and alerting rules. Track API latency, error rates, rate limit headroom, and webhook throughput.
Prerequisites
- Linear integration deployed
- Prometheus or Datadog for metrics
- Structured logging (pino, winston)
- Alerting system (PagerDuty, OpsGenie, Slack)
Instructions
Step 1: Define Metrics
// src/metrics/linear-metrics.ts
import { Counter, Histogram, Gauge, register } from "prom-client";
export const metrics = {
// API request tracking
apiRequests: new Counter({
name: "linear_api_requests_total",
help: "Total Linear API requests",
labelNames: ["operation", "status"],
}),
// Request duration
apiLatency: new Histogram({
name: "linear_api_request_duration_seconds",
help: "Linear API request duration",
labelNames: ["operation"],
buckets: [0.1, 0.25, 0.5, 1, 2, 5, 10],
}),
// Rate limit headroom
rateLimitRemaining: new Gauge({
name: "linear_rate_limit_remaining",
help: "Remaining rate limit budget",
labelNames: ["type"], // "requests" or "complexity"
}),
// Webhook tracking
webhooksReceived: new Counter({
name: "linear_webhooks_received_total",
help: "Total webhooks received",
labelNames: ["type", "action"],
}),
webhookProcessingDuration: new Histogram({
name: "linear_webhook_processing_seconds",
help: "Webhook processing duration",
labelNames: ["type"],
buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
}),
// Cache effectiveness
cacheHits: new Counter({
name: "linear_cache_hits_total",
help: "Cache hit count",
labelNames: ["key"],
}),
cacheMisses: new Counter({
name: "linear_cache_misses_total",
help: "Cache miss count",
labelNames: ["key"],
}),
};
// Expose metrics endpoint
app.get("/metrics", async (req, res) => {
res.set("Content-Type", register.contentType);
res.end(await register.metrics());
});
