Grafana Faro logo

Grafana Faro

Grafana 开源前端可观测 SDK，将浏览器日志、错误、性能与 Web Vitals 送入 Grafana/Loki/Tempo/Mimir 统一栈。

错误监控RUM开源Grafana

Grafana Faro 是开源前端可观测性 Web SDK，将浏览器端日志、异常、性能 trace 与 Core Web Vitals 发送到 Grafana 生态后端，适合已采用 LGTM 栈的团队以较低供应商锁定扩展前端信号。

访问官网

Grafana Faro

Grafana 开源前端可观测 SDK，将浏览器日志、错误、性能与 Web Vitals 送入 Grafana/Loki/Tempo/Mimir 统一栈。

技术简介说明

Grafana Faro（Frontend Application Remote Observability）是 Grafana Labs 推出的开源前端可观测性 Web SDK，旨在将浏览器端的日志、异常、性能 trace 与 Core Web Vitals 数据发送到 Grafana 生态后端（Loki 存日志、Tempo 存 trace、Prometheus/Mimir 存指标），并在 Grafana 仪表板中统一可视化。

与 Sentry、Datadog 等一站式 SaaS 不同，Faro 的定位是可观测数据管道 + SDK：你保留对存储与查询栈的控制权，适合已采用 Grafana Cloud 或自建 LGTM（Loki-Grafana-Tempo-Mimir）栈的团队，以较低供应商锁定扩展前端信号。

基本信息

快速上手

安装

npm install @grafana/faro-web-sdk

可选分布式追踪：

npm install @grafana/faro-web-tracing

最小示例

import { initializeFaro } from '@grafana/faro-web-sdk'
 
initializeFaro({
  url: 'https://faro-collector.example.com/collect',
  app: {
    name: 'my-frontend',
    version: '1.0.0',
    environment: 'production',
  },
  instrumentations: [
    // 默认包含 console、errors、web vitals 等
  ],
})

Grafana Cloud Frontend Observability

使用 Grafana Cloud 时，控制台会生成 collector URL 与 app key，配置类似：

initializeFaro({
  url: 'https://faro-collector-prod-us-east-0.grafana.net/collect/...',
  app: { name: 'my-app', version: '1.0.0', environment: 'production' },
})

自定义日志与测量

import { faro } from '@grafana/faro-web-sdk'
 
faro.api.pushLog(['User completed checkout'], { level: 'info' })
faro.api.pushMeasurement({
  type: 'custom',
  values: { cart_value: 99.9 },
})

核心特性

  • 开源 SDK：Apache-2.0，可审计与扩展。
  • Web Vitals 自动采集：LCP、INP、CLS 等送入 Grafana。
  • 错误与 Console 捕获：未处理异常、console 输出。
  • OpenTelemetry 兼容 tracing：@grafana/faro-web-tracing 与 Tempo 关联。
  • Grafana 仪表板：Frontend Observability 预置面板（Cloud/自建）。
  • 可插拔 Instrumentation：按需启用/禁用采集器。
  • 与 Alloy 集成：Grafana Alloy 作为 collector 路由到 Loki/Tempo/Mimir。

适用场景

  • 已使用 Grafana Stack（Loki、Tempo、Prometheus）监控后端。
  • 希望前端信号进入同一 Grafana 而非新增 SaaS 供应商。
  • 开源/自建可观测平台，需标准化浏览器 telemetry 接入。
  • 对 vendor lock-in 敏感，愿意自行运维 collector 与存储。
  • Grafana Cloud 用户扩展 Frontend Observability 模块。

技术亮点

  • LGTM 栈原生：日志、指标、trace、vitals 统一查询语言（LogQL、PromQL、TraceQL）。
  • 完全开源路径：从 SDK 到 collector 可自建。
  • OTel 方向：tracing 模块与 OpenTelemetry 生态对齐。
  • 轻量可组合：相比重型 APM SaaS，按需启用 instrumentations。
  • Grafana Labs 背书：与 Grafana 9+ 可观测战略一致。

核心概念与架构

@grafana/faro-web-sdk（浏览器）
      ↓
 Faro Collector / Grafana Alloy / Grafana Cloud
      ↓
 Loki（logs） / Tempo（traces） / Mimir（metrics）
      ↓
 Grafana Dashboards & Alerts

核心概念

  • Faro Agent：浏览器内嵌的采集运行时。
  • Instrumentation：可插拔采集模块（errors、vitals、console 等）。
  • Collector URL：数据接收端点。
  • App Meta：name、version、environment 标签维度。

技术局限与边界

  • 非开箱即用 Issue 管理：无 Sentry 式 Issue 去重、分配工作流，需自行在 Grafana 配置。
  • Session Replay 无：不提供 LogRocket 类回放（截至主流版本）。
  • 自建复杂度高：需部署 collector、存储与仪表板，运维成本明显高于 SaaS。
  • 生态较新：相比 Sentry decade 积累，社区案例与最佳实践仍在增长。
  • 错误聚合弱：需借助 Loki/Tempo 查询自行构建告警规则。

生态地图

  • SDK：@grafana/faro-web-sdk、@grafana/faro-react、@grafana/faro-web-tracing
  • Collector：Grafana Faro Collector、Grafana Alloy
  • 存储：Loki、Tempo、Mimir、Grafana Cloud
  • 对比：Sentry、Datadog RUM、Elastic RUM、Highlight.io

生态集成

  • React：@grafana/faro-react 提供 ErrorBoundary 与 hooks。
  • Grafana Cloud：Frontend Observability 一键配置 collector。
  • OpenTelemetry：trace 导出至 Tempo，与后端 OTel trace 关联。
  • web-vitals：Faro 内置 vitals instrumentation，避免重复上报。
  • Alerting：Grafana Alert 对 LCP 阈值、错误日志 rate 告警。

开发与工程化

  • 分环境 collector URL：staging/production 分离。
  • 版本标签：每次部署更新 app.version。
  • 采样：高流量站点在 collector 或 SDK 层配置采样（视部署方案）。
  • 仪表板模板：导入官方 Frontend Observability 仪表盘。
  • PII 过滤：在 collector 或 Loki pipeline 脱敏手机号、邮箱。

性能与安全

  • 性能：异步批量发送；默认可关闭不必要 instrumentations 减负。
  • 安全：collector URL 可公开但应配 rate limit；敏感日志勿 pushLog 明文密码。
  • 合规：自建栈数据驻留自控；Grafana Cloud 选区域。
  • HTTPS 必须：禁止明文 collector 端点。

技术对比

维度Grafana FaroSentryDatadog RUM
开源是部分否
Replay无有有
Issue 工作流弱极强中
Grafana 集成原生需导出需导出
自建强可弱
适合Grafana 栈用户工程排障企业统一观测

最佳实践

  1. 已用 Grafana 后端时优先 Faro，避免另购 RUM SaaS。
  2. 启用 web vitals + tracing，发挥 LGTM 关联查询优势。
  3. 导入官方仪表盘，减少从零配置 LogQL/TraceQL。
  4. 对错误日志设 Loki 告警，弥补无 Issue 系统的不足。
  5. 评估 Cloud vs 自建：中小团队 Grafana Cloud Frontend Observability 更省事。
  6. 勿与 web-vitals 重复上报，使用 Faro 内置 instrumentation。

学习与社区资源