beyla-grafana-skills

1. 基本信息

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

2. 功能介绍与亮点

beyla 教你用 Grafana Beyla——一个基于 eBPF 的零代码自动埋点工具——给现有服务接入分布式追踪与指标，全程不改一行应用代码、不引入 SDK、不用重启进程。核心内容：

前置条件核对：Linux 内核 5.8+ 且启用 BTF、root 或 CAP_SYS_ADMIN 权限、x86_64/ARM64、可达的 OTLP 接收端
三种常见工作流：用 Docker 对单个二进制做零代码埋点并验证指标/追踪是否送达；以 Kubernetes DaemonSet 形式集群级铺开（完整 RBAC/YAML 见引用文档）；经 Alloy 转发到 Grafana Cloud
支持的语言矩阵覆盖 Go/Java/Python/Ruby/Node/.NET/Rust/C++/PHP，自动产出 OTLP 追踪 + Prometheus 的 RED（请求量/错误率/耗时）指标
路由聚合（cardinality 控制）、采样配置、Kubernetes 元数据自动发现
每个工作流步骤都配具体的校验命令（如查 /metrics 是否出现对应指标、查 DaemonSet 日志是否有 BTF/权限报错），另有独立故障排查段落对应常见报错
两篇独立参考文档（完整配置项/环境变量表，K8s DaemonSet + RBAC + Helm 部署清单），主文档保持简洁

Beyla 项目本身已被 Grafana Labs 捐赠给 OpenTelemetry 基金会，以 “OpenTelemetry eBPF Instrumentation” 的名义继续在 CNCF 生态下发展，Grafana 维持自己的发行版本。

3. 适用场景

固定分类：DevOps 与基础设施

适合需要给无法改代码的服务（遗留系统、闭源二进制、第三方组件）快速补上可观测性的 DevOps / SRE 工程师：给一个“黑盒”服务接入 RED 指标和分布式追踪、以 DaemonSet 形式一次性覆盖整个 Kubernetes 集群、或是评估“零 SDK 埋点”是否能满足当前的可观测性需求。

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. 推荐理由

给已经在跑、又不方便改代码的服务补可观测性，一直是运维里的老大难——手动 SDK 埋点要求侵入代码、重新构建、重启进程,遇到闭源组件或“没人敢动”的遗留服务基本行不通。这份技能把 eBPF 零代码埋点从“单个二进制怎么试”到“整个集群怎么铺”完整地串成了工作流，每一步都配了具体的验证命令而不是停留在原理介绍,还专门列出了内核版本、权限等容易踩坑的前置条件。两位独立技术博主分别验证过 Beyla 的自动埋点效果并公开撰文分享经验,说明它不只是文档漂亮,实际用起来确实能跑通。

6. 评分

维度	分数	说明
受欢迎程度	7	合集仓库整体 205 stars（不代表本子技能个体热度）；子目录自身提交记录均为批量文档抓取/质量校验，未发现针对该子目录的专门维护提交或仓库内 issue/PR 讨论
可用性	8	三类工作流均附具体验证命令与独立故障排查表；前置条件（内核版本/BTF/权限）说明清晰，避免用户裸试才发现环境不满足；子目录随合集仓库近日仍在更新，维护活跃
安全性	8	见下方安全检查清单

安全检查清单：

检查项	结果
① Shell 命令与权限范围	需要 root 或 `CAP_SYS_ADMIN`（或 K8s 中 `privileged: true` + `hostPID: true`）——eBPF 挂载内核探针的必需权限，SKILL.md 已明确说明用途与来由，非来历不明的越权索取
② 联网外发	数据流向完全由用户在配置中显式声明的 OTLP 接收端决定（自建 Tempo/Alloy/Collector 或 Grafana Cloud），无隐藏外发
③ 凭据存储	本技能自身不要求凭据；涉及 Grafana Cloud 时的鉴权由下游 Alloy/Collector 配置承担，不在本技能范围内
④ 可疑指令	通读 SKILL.md 全文与两篇引用文档，未发现混淆代码或隐蔽指令
⑤ 作者信誉	Grafana Labs 官方组织仓库
⑥ License	Apache-2.0，明确
⑦ 维护时间	合集仓库近日仍有提交，非弃置项目

7. 跟同类 Skills 相比的优势

方案	定位	与本技能的差异
手动 OpenTelemetry SDK 埋点	应用代码层显式埋点，社区资料最多的传统路线	需要改代码、引入依赖库、重新构建部署；对闭源二进制或“没人敢动”的遗留服务无法使用
Odigos（CNCF 开源可观测控制面）	同样用 eBPF 自动化 OTel 埋点，聚焦 Kubernetes 场景	定位更偏“控制面”，完整的 Go 语言自动埋点能力需要企业版授权；本技能聚焦单机/集群两种部署路径的实操步骤，且核心能力保持开源
Pixie（Kubernetes 原生 eBPF 可观测）	面向 K8s 集群的系统级流量与资源可视化	更偏“看清集群内谁在跟谁通信、资源花在哪”的排查视角，产出格式非标准 OpenTelemetry；本技能产出标准 OTLP 追踪与 Prometheus 指标，可直接接入既有可观测性后端

8. 用户评价

Adam Anderson（Medium 独立技术博主）：称 Beyla 是简化应用可观测性的“精密工具”，认为 eBPF 让它能够“无需侵入性代码修改就提供深入的应用性能洞察”，并特别认可其 RED 指标对衡量服务健康度的实用价值。
Sergei Jeldoshev（Scoro 工程团队）：评价“只需添加几行配置即可开始使用 Beyla”，认可其自动传播 W3C traceparent 头实现无缝分布式追踪的能力，同时提醒演示配置本身并非生产就绪，生产环境还需额外做性能优化、指标过滤与采样配置。

9. 其他补充

Beyla 项目已被 Grafana Labs 捐赠给 OpenTelemetry 基金会，更名为 “OpenTelemetry eBPF Instrumentation” 在 CNCF 生态下继续发展，Grafana 方面维持自己的发行版；同时 Beyla 能力已整合进 Grafana Alloy，Kubernetes 部署不再强制要求单独的 DaemonSet。

10. 安装使用方式

Claude Code：
```
claude plugin marketplace add grafana/skills
claude plugin install grafana-core@grafana-skills
```
按插件组整体安装，grafana-core 组内除 beyla 外还含 alloy、opentelemetry、promql 等 7 个技能
通用（遵循 Agent Skills 开放标准的工具）：
```
npx skills add grafana/skills
```
Codex：通过仓库自带的 .agents-plugin/marketplace.json 自动发现加载，无需手工配置
使用前需目标主机满足 Linux 内核 5.8+/BTF 前置条件，并准备好可达的 OTLP 接收端（自建或 Grafana Cloud）；技能本身只提供配置与工作流指导，Beyla 探针以 Docker 镜像或 DaemonSet 形式独立运行

11. 注意事项

依赖 root/CAP_SYS_ADMIN 等系统级权限运行 eBPF 探针，容器化部署需显式打开 privileged/hostPID，安装前需确认所在环境（尤其是托管 Kubernetes）允许此类权限
内核版本或 BTF 支持不满足时会直接报错拒绝运行，技能已给出对应排障步骤但仍需使用者自行核实主机内核版本
OpenClaw / Hermes Agent 兼容性未经验证，安装前建议先确认所用 agent 是否支持 Agent Skills 开放标准