notion-observability

# Notion Observability ## Overview Instrument Notion API calls with metrics, structured logging, and alerting. Track request rates, latencies, error rates, and rate limit headroom. This skill covers a full observability stack: an instrumented client wrapper, Prometheus metrics with histogram buckets tuned for Notion's typical 200-800ms latency, structured logging via pino, health check endpoints, and Prometheus alerting rules for error rate spikes, rate limit exhaustion, high latency, and service outages. ## Prerequisites - `@notionhq/client` v2+ installed (`npm install @notionhq/client`) - Python alternative: `notion-client` (`pip install notion-client`) - Prometheus-compatible metrics backend (optional: Grafana, Datadog, or CloudWatch) - Structured logging library: `pino` (Node.js) or `structlog` (Python) ## Instructions ### Step 1: Instrumented Notion Client Wrapper Wrap every Notion API call with timing, error classification, and structured logging: ```typescript import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client'; interface NotionMetrics { requestCount: number; errorCount: number; rateLimitCount: number; totalLatencyMs: number; latencyBuckets: Map<string, number[]>; lastError: { code: string; message: string; timestamp: string } | null; } class InstrumentedNotionClient { private client: Client; private metrics: NotionMetrics = { requestCount: 0, errorCount: 0, rateLimitCount: 0, totalLatencyMs: 0, lat...