Observability

Observability

This section covers the full observability stack for bloqr-backend, from edge-level Cloudflare native tools to application-level error tracking with Sentry.

Contents

Document	What it covers
Sentry Integration	Error tracking, performance tracing, Worker wrapper, Frontend RUM (Phase 3), environment variables
Cloudflare Native Observability	Workers Logs, Traces, Analytics Engine, Tail Worker, Logpush
Prometheus Metrics	/metrics/prometheus scrape endpoint, Analytics Engine SQL queries, Grafana
Logpush → R2	Long-term log retention via Cloudflare Logpush to R2 (Phase 1c)
Custom Providers	How to add a custom IDiagnosticsProvider backend via registerDiagnosticsProvider()

Observability layers

flowchart TD
    request["Inbound request"] --> edge["Cloudflare Edge<br/>WAF • Rate Limiting • Turnstile • Bot Score"]
    edge --> worker["Cloudflare Worker"]
    worker --> sentry["withSentryWorker() -> Sentry (error tracking)"]
    worker --> analytics["AnalyticsService -> Analytics Engine (metrics)"]
    worker --> logs["AdminLogger -> Workers Logs (structured)"]
    worker --> traces["withAdminTracing() -> CF Traces (spans)"]
    worker --> tail["Tail Worker"]
    tail --> slack["formatSlackAlert() -> Slack (critical errors)"]
    tail --> sink["forwardToLogSink() -> Logtail / Better Stack"]
    tail --> kv["TAIL_LOGS KV -> Short-term log persistence"]

Quick environment variable reference

Variable	Layer	Required	Set via
SENTRY_DSN	Worker + Tail + Frontend RUM	Optional	wrangler secret put SENTRY_DSN
SENTRY_RELEASE	Worker (deploy-time var)	Optional (source map linking)	wrangler deploy --var SENTRY_RELEASE:$(git rev-parse HEAD)
OTEL_EXPORTER_OTLP_ENDPOINT	Worker	Optional (OpenTelemetry traces)	wrangler secret put OTEL_EXPORTER_OTLP_ENDPOINT
ANALYTICS_ACCOUNT_ID	Worker	Optional (Prometheus)	wrangler secret put ANALYTICS_ACCOUNT_ID
ANALYTICS_API_TOKEN	Worker	Optional (Prometheus)	wrangler secret put ANALYTICS_API_TOKEN
SLACK_WEBHOOK_URL	Tail Worker	Optional	wrangler secret put SLACK_WEBHOOK_URL (tail worker)
LOG_SINK_URL	Tail Worker	Optional	wrangler secret put LOG_SINK_URL (tail worker)
LOG_SINK_TOKEN	Tail Worker	Optional	wrangler secret put LOG_SINK_TOKEN (tail worker)
SENTRY_AUTH_TOKEN	CI only	Optional (source maps)	gh secret set SENTRY_AUTH_TOKEN
SENTRY_ORG	CI only	Optional (source maps)	gh variable set SENTRY_ORG
SENTRY_PROJECT	CI only	Optional (source maps)	gh variable set SENTRY_PROJECT