Observability

给 Go 服务加指标（比如「查一次词花了多少毫秒」），代码里要选一个埋点库。常见的两个选择是 Prometheus 官方的 client_golang 和 OpenTelemetry 的 Go SDK。两者都能产出同样的 Prometheus 指标，差别在覆盖范围、配置量和对后端的绑定程度。 采集、存储、展示这一层（Alloy、Prometheus、Loki、Grafana）的对比见 可观测性工具对比。本文只讲应用代码里的埋点这一层。 埋点库在哪一层 graph LR A["应用代码埋点库：client_golang 或 OTel SDK"] --> B["采集Prometheus 抓取 / Alloy / OTel Collector"] B --> C["存储Prometheus / Mimir / Grafana Cloud"] C --> D["展示Grafana"] 埋点库决定两件事：代码里怎么记录一个数字，以及这个数字以什么格式交出去（Prometheus 的 /metrics 文本格式，或者 OTLP 协议）。它不决定数据最后存在哪。 Prometheus client_golang github.com/prometheus/client_golang 是 Prometheus 项目的官方 Go 客户端，只做指标。 工作方式是拉（pull）：应用在内存里维护计数器和直方图，通过 HTTP 暴露一个 /metrics 端点，Prometheus（或 Alloy）定期来抓。应用不知道谁来读，也不主动往外发。 四种指标类型： 类型 用途 例子 Counter 只增不减的计数 请求总数、错误总数 Gauge 可增可减的当前值 正在处理的请求数、队列长度 Histogram 按桶统计分布，服务端可算分位数 请求耗时，用来算 p95/p99 Summary 客户端直接算分位数 很少用；分位数无法跨实例聚合，一般用 Histogram 最小示例： ...

什么是 LangSmith LangSmith 是 LangChain 团队推出的 LLM 应用可观测性与评估平台，用于追踪（trace）、调试、测试和监控基于 LLM 的应用。它不要求应用一定使用 LangChain 或 LangGraph 构建——任何调用 LLM 的代码都可以接入 LangSmith，但与 LangChain / LangGraph 的集成是开箱即用的。 核心定位：LLM 应用的"生产环境可观测性 + 离线评估"工具，解决 LLM 应用调试困难、行为不透明、质量难以量化的问题。 官方仓库 / 产品：langchain-ai/langsmith-sdk（SDK 开源，平台本身为托管 SaaS，也提供自托管方案）。 为什么需要 LangSmith 传统软件的日志和监控体系（APM、ELK 等）不足以覆盖 LLM 应用的调试需求： 多步骤链路不透明：一次 Agent 调用可能包含多次 LLM 请求、工具调用、检索操作，普通日志难以还原完整调用树 Prompt 调试依赖人工：Prompt 的微小改动可能显著影响输出质量，缺乏系统化的对比手段 输出质量难以量化：LLM 输出是非确定性的自然语言，传统的断言测试不适用 成本和延迟不可见：Token 消耗、模型延迟分散在各次调用中，难以聚合分析 LangSmith 针对这些痛点提供了追踪、数据集管理、评估和监控能力。 核心功能 1. Tracing（追踪） 记录一次请求内所有 LLM 调用、工具调用、检索操作的完整调用树，包括输入、输出、耗时、Token 用量。 import os os.environ["LANGCHAIN_TRACING_V2"] = "true" os.environ["LANGCHAIN_API_KEY"] = "your-api-key" os.environ["LANGCHAIN_PROJECT"] = "my-project" # LangChain / LangGraph applications are traced automatically # once the environment variables above are set from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-4") result = llm.invoke("Explain what LangSmith does") 对于不使用 LangChain 的代码，可以用 @traceable 装饰器手动接入： ...

用 Loki 收集日志后，Grafana 提供两个查看日志的入口：Explore 和 Logs Drilldown。Explore 页面上会有提示引导用户打开 Drilldown，两者功能互补，定位不同。 Grafana Explore Explore 是 Grafana 的内置数据探索工具，内置于 Grafana 核心，无需额外安装。 主要特点： 手动编写查询语句（Loki 使用 LogQL，Prometheus 使用 PromQL） 支持所有 Grafana 数据源（Loki、Prometheus、Tempo、Elasticsearch 等） 适合有一定查询语言基础的用户做临时分析、调试 支持 Split view（左右分屏对比两个查询结果） 支持 Live tail 实时追踪日志流 可快速从 Dashboard 面板跳转过来做深入分析 Grafana Logs Drilldown Logs Drilldown（插件 ID：grafana-lokiexplore-app）是 Grafana Labs 开发的独立 App 插件，需要单独安装。 它的前身叫 “Explore Logs”（这也是 GitHub 仓库名 explore-logs 和插件 ID 中含 lokiexplore 的由来），后来作为 “Drilldown” 系列产品之一改名为 Logs Drilldown。 主要特点： 无需写查询语言，通过点击可视化界面即可过滤和钻取日志 自动为 Loki 数据生成可视化图表（按 label、field、pattern 分组） 支持按 volume（日志量）和 text pattern（文本规律）发现异常 每个面板都提供"在 Explore 中打开"的链接，方便切回手写查询 要求 Grafana ≥ 11.6，Loki ≥ 3.2 两者关系 对比维度 Grafana Explore Logs Drilldown 是否内置 内置，无需安装 App 插件，需安装 查询方式 手写 LogQL 点击界面，无需写查询 支持数据源 所有 Grafana 数据源 仅 Loki 适合场景 熟悉 LogQL 的深度调试 快速浏览、发现规律 互通 Drilldown 面板可跳转到 Explore Explore 提示打开 Drilldown 两者互为补充：Drilldown 是低门槛的起点，适合快速找到问题所在；Explore 是全功能的工具箱，适合写精确查询做深度分析。Explore 上的引导提示正是建议不熟悉 LogQL 的用户先去 Drilldown 上直观探索，找到感兴趣的范围后再回 Explore 精确查询。 ...

Grafana Alloy 是什么 Grafana Alloy 是 Grafana Labs 推出的开源可观测性采集器（collector），用于采集 metrics、logs、traces 并转发到后端存储（Prometheus、Loki、Tempo 等）。 它是 Grafana Agent 的继任产品，从 2024 年起 Grafana Agent 进入维护模式，Alloy 成为官方推荐替代。 核心能力 能力 说明 Metrics 采集 兼容 Prometheus scrape，支持 remote_write 转发 Logs 采集 支持 syslog receiver、file tail、journal、Docker 等，写入 Loki Traces 采集 接收 OTLP、Jaeger 等，写入 Tempo 统一入口 一个进程同时处理 metrics + logs + traces，替代 node_exporter + Promtail + OTel Collector 与 Promtail 的关系 Promtail 是 Grafana Labs 早期专门用于日志采集并写入 Loki 的 agent，功能单一（只做 logs）。Alloy 是它的功能超集： ...

可观测性（Observability）通常分三个信号：Metrics（指标）、Logs（日志）、Traces（链路追踪）。每个信号都有对应的采集工具和存储后端，本文整理常见工具并说明相互关系。 技术栈全景 graph TD A["采集 / AgentAlloy · Promtail · node_exporterTelegraf · Filebeat · OTel Collector"] A -->|push / pull| B["Prometheus(Metrics)"] A -->|push / pull| C["Loki(Logs)"] A -->|push / pull| D["Tempo(Traces)"] B --> E["Grafana(展示 / 查询)"] C --> E D --> E 采集工具对比 Metrics 采集 工具 归属 定位 日志能力 Traces 能力 node_exporter Prometheus / CNCF Linux 主机 metrics 暴露 ✗ ✗ Telegraf InfluxData 通用 metrics 采集（300+ 插件） 弱（有 tail/syslog 插件，非主要定位） ✗ Grafana Alloy Grafana Labs 统一采集（metrics + logs + traces） ✅ ✅ node_exporter：轻量，只暴露 /metrics 端点供 Prometheus scrape，不主动推送。几乎每个 Linux 节点标配。 Telegraf：InfluxDB 生态的核心 agent，插件丰富，适合往 InfluxDB / Prometheus 写数据。如果需要完整日志采集需另加工具（如 Filebeat）。 Alloy：Grafana 2024 年推出的统一 agent，一个进程替代 node_exporter + Promtail + OTel Collector，是 Grafana Agent 的继任者。 Logs 采集 工具 归属 定位 写入目标 维护状态 Promtail Grafana Labs 专用日志 agent（Loki 配套） Loki only 维护模式（停止新功能） Filebeat Elastic 日志采集（ELK 配套） Elasticsearch / Logstash 主动开发 Fluentd / Fluent Bit CNCF 通用日志管道 Elasticsearch、Loki、Kafka 等 主动开发 Grafana Alloy Grafana Labs 统一采集 Loki / Prometheus / Tempo 主动开发 Promtail：已进入维护模式，官方建议迁移到 Alloy。详见 Promtail 介绍。 Filebeat：Elastic 全家桶（ELK）的配套工具，不属于 Grafana 技术栈。 Fluent Bit：比 Fluentd 更轻量，K8s 中常用于节点级日志采集，输出目标灵活（可写 Loki 或 Elasticsearch）。 Alloy：同时支持 logs，是 Grafana 技术栈里的推荐选项。 Traces 采集 工具 归属 定位 OpenTelemetry Collector CNCF 标准链路追踪采集，支持 OTLP / Jaeger / Zipkin Grafana Alloy Grafana Labs 内置 OTel receiver，可替代 OTel Collector Jaeger Agent CNCF Jaeger 专用采集，逐步被 OTel 替代 存储后端对比 工具 信号类型 归属 查询语言 典型搭配 Prometheus Metrics CNCF PromQL Grafana + Alloy/node_exporter Loki Logs Grafana Labs LogQL Grafana + Alloy/Promtail Tempo Traces Grafana Labs TraceQL Grafana + Alloy/OTel Collector InfluxDB Metrics（时序） InfluxData Flux / InfluxQL Grafana + Telegraf Elasticsearch Logs（也可做 metrics） Elastic Lucene / EQL Kibana + Filebeat VictoriaMetrics Metrics VictoriaMetrics PromQL 兼容 可替换 Prometheus，更省内存 展示工具 工具 特点 Grafana 支持所有主流数据源（Prometheus、Loki、Tempo、InfluxDB、Elasticsearch 等），最通用 Kibana Elastic 专用，深度集成 Elasticsearch，日志搜索体验强 InfluxDB UI InfluxDB 内置，适合 InfluxDB 用户 两大技术栈总结 Grafana 技术栈（推荐用于 self-hosted / homelab） graph TD A["Grafana Alloy（一个 agent 全搞定）"] A --> B[Prometheus] A --> C[Loki] A --> D[Tempo] B --> E[Grafana] C --> E D --> E Elastic 技术栈（ELK） graph TD A["Filebeat / Logstash"] --> B[Elasticsearch] B --> C[Kibana] 选型建议 homelab / 个人项目：Grafana 全家桶（Prometheus + Loki + Grafana + Alloy），资源占用合理，开箱即用。 已有 InfluxDB：继续用 Telegraf，不必迁移；如果想要日志需额外引入 Fluent Bit → Loki。 企业 K8s 日志：Fluent Bit（DaemonSet）→ Loki 或 Elasticsearch，视现有技术栈决定。 新项目要全套可观测性：OpenTelemetry（采集 SDK）+ OTel Collector / Alloy → Prometheus + Loki + Tempo + Grafana。

Promtail 是什么 Promtail 是 Grafana Labs 开发的日志采集 agent，专门用于从各种来源采集日志并将其发送到 Loki 存储。名称来源于"Prometheus tail"——受 Prometheus 的 pull 模式启发，但针对日志场景做了适配。 主要功能 文件 tail：监控本地文件（如 /var/log/*.log），实时采集新增内容 systemd journal：采集 journald 日志 syslog 接收：作为 syslog server，接收远端设备通过 UDP/TCP 推送的日志 Docker/Kubernetes：采集容器日志 Label 打标：通过 pipeline stages 对日志打 label、做正则提取、过滤等 与 Loki 的关系 Promtail 是 Loki 的配套 agent： 日志源（文件 / syslog / journal） ↓ Promtail（采集、打标、转发） ↓ Loki（存储） ↓ Grafana（查询） 三者组合构成 Grafana 的日志技术栈（类比 Prometheus + node_exporter + Grafana 的 metrics 技术栈）。 ...