用途:为 NodeJS-Starter-V1 提供数据库后端的可观测性指标埋点规范,基于 Supabase/PostgreSQL,适配 Vercel/无服务器架构,无需 Prometheus 抓取。
主要能力:定义三种指标类型——计数器(每事件 INSERT,COUNT 求和)、仪表(UPSERT,取最新值)、直方图(每观测 INSERT,可算分位数);统一命名规范 {domain}{entity}{measurement}[_{unit}];提供时间序列分桶聚合与 p50/p90/p95/p99 分位数查询;可选 OpenTelemetry 桥接(仅当配置 OTEL_EXPORTER_OTLP_ENDPOINT 时启用)。
使用方式:通过 MetricsRegistry 单例的 increment()、observe()、set_gauge() 记录指标;计数器与直方图写入 metrics_events 表,仪表写入 metrics_gauges 表;用中间件在请求上记录 api_request_total 与 api_request_duration_ms;暴露 /metrics/summary 端点返回计数器、仪表与直方图分位数;前端沿用现有代理路由与 MetricTile 组件,按 30 秒轮询。
表结构:metrics_events(metric_name、metric_type、value、labels、recorded_at)与 metrics_gauges(metric_name、label_key、labels、value、recorded_at,主键为 metric_name+label_key)。
限制与维护:无服务器环境不可用内存计数器与 Prometheus 抓取端点;不支持用无结构日志记录指标;建议通过 cron 任务 /api/cron/metrics-cleanup 执行 90 天保留清理;原始事件直查仪表盘在大数据量下较慢,建议预聚合或时间分桶。指标写入失败不得中断请求。时区按 en-AU 处理,存储用 UTC,展示转 AEST/AEDT;llm_cost_usd 以美元存储,展示可转澳元。