app-observability

Grafana Cloud 应用可观测性

文档：https://grafana.com/docs/grafana-cloud/monitor-applications/

三款产品共用相同的 OTLP + Mimir / Loki / Tempo / Pyroscope 数据链路：

1. 应用可观测性 — 基于 OTel spanmetrics 的 APM
2. 前端可观测性 — Faro Web SDK、RUM + 会话回放
3. AI 可观测性 — 通过 OpenLIT 监控 LLM / 向量数据库

前提条件

• Grafana Cloud 堆栈 + OTLP 端点 + 数字实例 ID + 拥有 MetricsPublisher + LogsPublisher + TracesPublisher 权限的 API 密钥
• APM：应用已通过 OTel SDK 完成插桩；前端：Web 应用 + Faro 应用密钥；AI：Python ≥ 3.10
• Grafana Alloy 作为本地 OTLP 接收器（推荐）

常见工作流

1. 搭建 APM — Alloy 接收器 → Grafana Cloud + 验证

# 1. Set Cloud creds + start Alloy with config from references/apm.md
export GRAFANA_CLOUD_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export GRAFANA_CLOUD_INSTANCE_ID=123456
export GRAFANA_CLOUD_API_KEY=glc_eyJ...
alloy fmt /etc/alloy/config.alloy   # syntax check
alloy run /etc/alloy/config.alloy

# 2. Verify Alloy is receiving + forwarding
curl -s http://localhost:12345/api/v0/web/components \
  | jq '.[] | select(.id|test("otelcol\\.exporter\\.otlphttp"))
        | {id, health:.health.state}'
# Expect health.state == "healthy"
curl -s http://localhost:12345/metrics \
  | grep -E 'otelcol_(receiver_accepted_spans|exporter_sent_spans)'

# 3. Point your app at Alloy (with required attributes!)
export OTEL_SERVICE_NAME="my-api"
export OTEL_RESOURCE_ATTRIBUTES="service.namespace=myteam,deployment.environment=production"
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# 4. Verify spans landed in Tempo + spanmetrics generated
#    Tempo (TraceQL):  { resource.service.name = "my-api" }
#    Mimir (PromQL):   sum by (job) (rate(traces_spanmetrics_calls_total{service_name="my-api"}[5m]))
#    Expect > 0 within ~1 minute.

# 5. Verify it's wired to App Observability
#    Grafana → Application → Service Inventory: "my-api" should appear with RED metrics
#    Click into it → Service Map edges visible (requires span.kind on outbound calls)

完整的 Alloy 配置块 + 必需的资源属性 + spanmetric 名称 + 关联链接：references/apm.md。

2. 使用 Faro 为 React 前端添加插桩

# 1. Install
npm install @grafana/faro-react @grafana/faro-web-tracing

// 2. initializeFaro with TracingInstrumentation + ReactIntegration (see references/faro.md)
//    Push a smoketest event so we have a known signal:
faro.api.pushEvent('faro_smoketest', { ts: Date.now().toString() });

# 3. Verify in DevTools Network — POST to /collect returns 202
#    (401 → wrong app key; 404 → wrong url region)

# 4. Verify in Grafana Cloud
#    - Frontend Observability → your app → Sessions: your session appears
#    - LogQL on Loki: {kind="event"} |= "faro_smoketest"
#    - With TracingInstrumentation: open the session → the trace ID links to Tempo

完整的 React 示例、CDN 设置、会话配置：references/faro.md。

3. 添加 AI / LLM 可观测性

pip install openlit==1.42.0

# At app startup
import openlit
openlit.init(application_name="my-ai-app", environment="production")
# Your existing OpenAI / Anthropic / Cohere calls now emit OTel spans + metrics.

# Env (same OTLP endpoint as APM)
export OTEL_SERVICE_NAME="my-ai-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-<region>.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic $(echo -n $ID:$KEY | base64)"

# Verify after a few LLM calls:
#   PromQL: sum by (gen_ai_request_model) (rate(gen_ai_usage_input_tokens_total[5m]))
#   Dashboard: Grafana → AI Observability → "GenAI Observability" auto-populates

完整的 OpenLIT 安装、评估/防护、GenAI 指标列表、仪表板名称：references/ai-observability.md。

全栈关联速查表

信号	产品	存储	查询
RED 指标	应用可观测性	Mimir	PromQL
链路追踪	Tempo	Tempo	TraceQL
日志	Loki	Loki	LogQL
性能剖析	Pyroscope	Pyroscope	ProfileQL
浏览器 RUM	前端可观测性	Loki + Tempo	LogQL / TraceQL
LLM 指标	AI 可观测性	Mimir	PromQL

关联键：service.name 用于关联所有信号；链路追踪示例会将链路追踪 ID 嵌入指标点；日志中的 traceID 和 Faro 注入的 traceparent 用于前端 → 后端关联。

故障排查

• 服务未显示在 Service Inventory 中 → 缺少 service.namespace（job 标签）或 deployment.environment 资源属性
• Service Map 缺少边 → 出站调用未设置 span.kind（必须为 CLIENT），或入站调用未设置（必须为 SERVER）
• Faro /collect 返回 401 → 应用密钥错误；返回 404 → URL 中的区域与 Faro 应用不匹配
• 没有 GenAI 指标 → 确认 OpenLIT 版本与 Cloud 预期的 OTel semantic-conv 版本匹配；按照工作流 #3 中的方式使用 curl 验证身份验证

参考资料

• references/apm.md — APM 基础：RED 指标的生成方式、必需的 OTel 资源属性、Alloy 配置、关联链接
• references/apm-setup.md — 深入了解：各语言完整的 OTel SDK 设置（Node / Python / Java / Go）、span-metrics 选项、完整 Alloy 配置
• references/faro.md — Faro 基础：SDK 初始化、插桩、会话回放
• references/frontend-observability.md — 深入了解：完整的 Faro SDK 参考、React/Vue/Angular 集成、自定义事件、源映射
• references/ai-observability.md — OpenLIT 自动插桩，适用于 OpenAI / Anthropic / Bedrock / Vertex AI

资源

• 应用可观测性文档
• 前端可观测性文档
• Faro Web SDK
• AI 可观测性文档
• OpenLIT