| name | notion-observability |
| description | Set up observability for Notion integrations with metrics, traces, and alerts.
Use when implementing monitoring for Notion API calls, setting up dashboards,
or configuring alerting for Notion integration health.
Trigger with phrases like "notion monitoring", "notion metrics",
"notion observability", "monitor notion", "notion alerts", "notion tracing".
|
| allowed-tools | Read, Write, Edit |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
Notion Observability
Overview
Instrument Notion API calls with metrics, structured logging, and alerting. Track request rates, latencies, error rates, and rate limit headroom across a full observability stack: an instrumented client wrapper, Prometheus metrics, structured logging via pino, health check endpoints, and alerting rules.
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)
Authentication
All snippets read the integration token from the NOTION_TOKEN environment variable (never hard-code it) and pass it as auth to the Notion client constructor. Store it in your secret manager and inject it at runtime. The health check and metrics endpoints below expose no secrets — only aggregate counters and status.
Instructions
The workflow layers three pieces. Build them in order; each is self-contained. Full code for every step lives in references/implementation.md.
Step 1: Instrumented client wrapper
Wrap every Notion call so timing, error classification, rate-limit detection, and structured logging happen automatically. The wrapper accumulates per-operation latency buckets and exposes getMetrics() for avg/p95. Skeleton:
class InstrumentedNotionClient {
async call<T>(operation: string, fn: (c: Client) => Promise<T>): Promise<T> {
const start = performance.now();
try {
const result = await fn(this.);
.(operation, .(performance.() - start));
result;
} (error) {
((error) && error. === .) {
..++;
}
error;
}
}
}
