alloy-grafana-skills

1. 基本信息

项目	内容
名称	alloy-grafana-skills
作者/维护者	Grafana Labs（官方组织）
来源链接	https://github.com/grafana/skills/tree/main/skills/grafana-core/alloy
许可证	Apache-2.0（GitHub API 获取）
GitHub Stars / Forks	203 / 17（GitHub API 获取；为 grafana/skills 合集仓库整体数据，非本子技能个体热度，详见第 7 章前说明）
最新版本	无独立版本号（随合集仓库按插件组整体发布，非本子技能专属发版）
安装方式	Claude Code 插件市场一键安装，或通用命令行工具安装（见第 10 章）

2. 功能介绍与亮点

alloy 教你用 Grafana Alloy——一个 OpenTelemetry 兼容的单一二进制采集器——把指标、日志、追踪、性能剖析四种遥测信号统一收集并转发出去，替代分散维护多套采集组件的做法。核心内容：

Alloy 配置语言：block/attribute 语法、sys.env 读取环境变量、组件间引用
四条常见流水线模式：prometheus.scrape→remote_write（指标）、loki.source.file+loki.process→loki.write（日志解析过滤）、otelcol.receiver.otlp→otelcol.exporter.otlp（接收并转发 OTLP 追踪）、pyroscope.scrape（性能剖析）
Kubernetes / Docker / EC2 自动发现与 relabel 规则
模块化配置（import.file / import.git / import.http）、集群模式、Fleet Management 远程配置（remotecfg）
内建 Web UI（:12345）实时查看每个组件的健康状态与具体报错
alloy fmt / alloy validate 本地校验命令，每个工作流后都附具体的验证步骤（如查 prometheus_remote_storage_samples_total 是否在增长）
独立的故障排查段落，把“日志没进 Loki”“追踪没到 Tempo”等常见问题对应到具体要检查的指标名

技能另附三篇独立参考文档（配置语法完整参考、组件目录、端到端流水线范例），主文档保持简洁、深度内容拆到引用文件里。子目录内容除一次批量文档抓取外，还有一次由 Grafana 在职工程师专门提交的集群行为修正，非纯自动化生成。下游转发目标既可以是 Grafana Cloud，也可以是自托管的 Prometheus / Loki / Tempo / Pyroscope，不强制绑定付费云服务。

3. 适用场景

固定分类：DevOps 与基础设施

适合需要给应用或集群统一接入可观测性数据的 DevOps / SRE 工程师：从零编写一份 config.alloy 采集配置、把正在用的原生 OpenTelemetry Collector 或已停止维护的 Grafana Agent 迁移过来、给 Kubernetes 集群里的 Pod 做自动发现采集、在日志送出前做过滤脱敏、或者排查“配置好了但数据没到后端”这类采集链路故障。

4. 跨 Agent 兼容性

Claude Code：原生支持——仓库提供 .claude-plugin/marketplace.json，可通过 claude plugin marketplace add + claude plugin install 直接安装
Codex：支持——仓库同时提供 .agents-plugin/marketplace.json 供 Codex 自动发现加载
OpenClaw：未验证——README 仅笼统声明“兼容任何支持 Agent Skills 开放标准的工具”，未点名 OpenClaw
Hermes Agent：未验证——同上，未见针对性说明

5. 推荐理由

市面上关于 OpenTelemetry Collector 的资料大多停留在“这是什么”的原理层面，真正配置起来还是要在几十种组件里自己摸索。这份技能把指标/日志/追踪/性能剖析四种信号的采集配置整合成一套可复制的工作流，每一步都配了具体的校验命令和对应的排障指标名，而不是停在原则性建议。集群模式相关内容经过负责该产品线的 Grafana 工程师专门修正过，不是单纯的文档批量搬运。下游可以完全自托管，不强制要求 Grafana Cloud 订阅。

6. 评分

维度	分数	说明
受欢迎程度	7	合集仓库整体 203 stars（不代表本子技能个体热度）；子目录本身除批量文档抓取外，还有一次 Grafana 在职工程师专门提交的集群行为修正，非纯自动化批量生成
可用性	9	覆盖本地校验、日志采集、OTLP 接收转发三类完整工作流，均附具体验证命令与故障排查表；下游后端可完全自托管不依赖付费服务；子目录最近一次内容更新为近期，维护活跃
安全性	9	见下方安全检查清单

安全检查清单：

检查项	结果
① Shell 命令与权限范围	用户自行安装并运行 `alloy fmt`/`alloy validate`/`alloy run` 及 curl 校验命令，操作范围限于用户自己管理的采集配置与本机基础设施，无越权动作
② 联网外发	数据流向完全由用户在 `config.alloy` 中显式声明的下游端点决定（自建服务或 Grafana Cloud），无隐藏外发
③ 凭据存储	API key/用户名通过环境变量注入（如 `GRAFANA_API_KEY`），凭据由用户自行管理，技能本身不落盘保存
④ 可疑指令	通读 SKILL.md 全文与三篇引用文档，未发现混淆代码或隐蔽指令
⑤ 作者信誉	Grafana Labs 官方组织仓库，内容修正提交者经核实为在职工程师
⑥ License	Apache-2.0，明确
⑦ 维护时间	最近一次内容更新为近期，非弃置项目

7. 跟同类 Skills 相比的优势

方案	定位	与本技能的差异
原生 OpenTelemetry Collector（不经封装的官方 YAML 配置）	CNCF 标准采集器，厂商中立	只有原始的组件参考文档，没有针对具体信号类型的成型工作流，也没有内建的 fmt/validate 校验与故障排查表，配置正确性要靠使用者自行摸索
dd-apm-datadog-labs-agent-skills（Datadog 官方 APM 埋点技能）	应用代码层埋点，把追踪数据打进 Datadog 专有后端	定位在采集链路的上游（应用埋点）而非采集/路由层，且绑定单一商业后端；本技能处于采集器配置层，下游后端可插拔，二者是链路上下游关系而非直接竞品

8. 用户评价

该技能目前在第三方平台尚无具名用户评价。

9. 其他补充

Grafana Alloy 本身是原 Grafana Agent 的继任者，仓库文档附带官方“从 Grafana Agent 迁移”指南链接，适合仍在用旧版 Agent 的团队参考迁移路径。

10. 安装使用方式

Claude Code：
```
claude plugin marketplace add grafana/skills
claude plugin install grafana-core@grafana-skills
```
按插件组整体安装，grafana-core 组内除 alloy 外还含 dashboarding、promql、alerting-irm 等 7 个技能
通用（遵循 Agent Skills 开放标准的工具）：
```
npx skills add grafana/skills
```
Codex：通过仓库自带的 .agents-plugin/marketplace.json 自动发现加载，无需手工配置
使用前需在本机安装 alloy 命令行工具（brew install grafana/grafana/alloy、apt install alloy，或直接用 grafana/alloy Docker 镜像），技能本身只提供配置与工作流指导，不含采集器二进制

11. 注意事项

技能给出的示例配置需要一个真实的下游端点（自建 Prometheus/Loki/Tempo/Pyroscope 或 Grafana Cloud）才能验证效果，纯本地试跑无法看到完整链路
涉及 Grafana Cloud 的示例需要账号 API key，但核心采集与转发能力不强制要求该订阅
OpenClaw / Hermes Agent 兼容性未经验证，安装前建议先确认所用 agent 是否支持 Agent Skills 开放标准