尧图网页设计 
Cilium 数据面流量指标查询指南cilium-dbg bpf metrics list 详解【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文以 Cilium 的cilium-dbg bpf metrics list命令为核心讲解如何直接从内核 eBPF 数据面读取流量转发与丢包统计信息。该命令面向需要深入排查数据面行为的开发者与运维人员相比 Prometheus/metrics端点它能输出包含源码行号、文件名等细粒度定位信息的完整指标。读完本文你将掌握该命令的完整语法、输出字段含义、底层 BPF 指标映射cilium_metrics的数据结构与计数机制以及 JSON/YAML 等结构化输出在自动化巡检中的用法。命令概览cilium-dbg bpf metrics list用于列出 Cilium 数据面datapath的 BPF 流量指标是cilium-dbg bpf metrics命令族详见 cilium-dbg_bpf_metrics.md下的子命令同族还包括 flush清空指标仅供测试。cilium-dbg bpf metrics list [flags]命令的Short描述为 List BPF datapath traffic metrics。从源码看该命令定义在 bpf_metrics_list.govar bpfMetricsListCmd cobra.Command{ Use: list, Short: List BPF datapath traffic metrics, Run: func(cmd *cobra.Command, args []string) { common.RequireRootPrivilege(cilium bpf metrics list) mm, err : metricsmap.LoadMetricsMap(log) if err ! nil { fmt.Fprintf(os.Stderr, error loading BPF metrics map: %v\n, err) os.Exit(1) } listMetrics(mm) }, }可见该命令有两个显著特征需要 root 权限命令入口首先调用common.RequireRootPrivilege因为访问 BPF 映射需要足够的权限直接读取 BPF 映射通过metricsmap.LoadMetricsMap加载名为cilium_metrics的 eBPF 映射映射初始化由 Cilium Agent 完成见 metricsmap.go不经过 API Server因此必须在本机或能访问到该映射的环境执行。可用选项Options-h, --help help for list -o, --output string json| yaml| jsonpath{}选项类型说明-h, --helpbool显示帮助信息-o, --output stringstring指定输出格式json、yaml或jsonpath{}不指定时输出人类可读的表格该选项由command.AddOutputOption(bpfMetricsListCmd)注册见 bpf_metrics_list.go底层复用pkg/command的统一输出框架。父命令继承的全局选项以下选项继承自cilium-dbg根命令--config string Config file (default is $HOME/.cilium.yaml) -D, --debug Enable debug messages -H, --host string URI to server-side API --log-driver strings Logging endpoints to use (example: syslog) --log-opt map Log driver options (example: formatjson)选项说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug开启调试日志-H, --host string服务端 API 的 URI--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson输出字段与示例人类可读的表格输出不指定-o时命令通过text/tabwriter输出对齐的文本表格见 bpf_metrics_list.go表头如下REASON DIRECTION PACKETS BYTES LINE FILE列含义REASON丢包原因或转发原因例如Success、Drop类原因码对应的可读字符串DIRECTION流量方向INGRESS、EGRESS、SERVICE或UNKNOWNPACKETS累计处理的数据包数量BYTES累计处理的字节数LINE触发该计数语句的 BPF 源码行号__MAGIC_LINE__FILE触发该计数的 BPF 源文件名__MAGIC_FILE__输出会按六列字典序整体排序便于阅读。表头的常量定义于 bpf_metrics_list.goconst ( reasonTitle REASON directionTitle DIRECTION packetsTitle PACKETS bytesTitle BYTES lineTitle LINE fileTitle FILE )结构化输出-o json时输出每条指标的 JSON 对象字段结构定义在 bpf_metrics_list.gotype jsonMetric struct { Reason string json:reason Direction string json:direction Packets uint64 json:packets Bytes uint64 json:bytes Line uint16 json:line File string json:file }示例-o json[ { reason: Success, direction: ingress, packets: 100, bytes: 1000, line: 0, file: } ]注意两点细节DIRECTION在表格输出中为大写INGRESS而在 JSON 输出中经strings.ToLower转为小写ingressREASON通过monitorAPI.DropReason解析为可读字符串具体映射见 pkg/monitor/api/drop.go 附近。关键兼容性逻辑相同 key 计数合并源码中对 JSON 输出做了特殊处理由于 Cilium 1.16 起在映射 key 中启用了line、file字段此前为保留位新版本写入的指标在旧版本 Agent 看来会呈现为重复的条目。为避免重复展示listJSONMetrics将reason direction line file相同的行合并并把packets、bytes相加见 bpf_metrics_list.go。该行为有对应的单元测试佐证bpf_metrics_list_test.go 中的TestDumpMetrics构造了一个含重复key 的 mock 映射Key{Reason: 132, Dir: 2}出现两次断言最终 JSON 中该条目的Packets为301 300 1、Bytes为3001 3000 1。底层实现原理eBPF 指标映射cilium_metricscilium-dbg bpf metrics list读取的映射定义于 BPF 侧 bpf/lib/metrics.hstruct metrics_key { __u8 reason; /* 0: forwarded, 0 dropped */ __u8 dir:2, /* 1: ingress 2: egress */ pad:6; __u16 line; /* __MAGIC_LINE__ */ __u8 file; /* __MAGIC_FILE__, needs to fit __id_for_file */ __u8 reserved[3]; /* reserved for future extension */ }; struct metrics_value { __u64 count; __u64 bytes; }; struct { __uint(type, BPF_MAP_TYPE_PERCPU_HASH); __type(key, struct metrics_key); __type(value, struct metrics_value); __uint(pinning, LIBBPF_PIN_BY_NAME); __uint(max_entries, METRICS_MAP_SIZE); __uint(map_flags, CONDITIONAL_PREALLOC); } cilium_metrics __section_maps_btf;要点映射类型为BPF_MAP_TYPE_PERCPU_HASHPer-CPU 哈希表每个 CPU 各自累加计数避免跨 CPU 锁竞争dir只占用 2 bit取值范围为1: ingress、2: egress另有3: serviceNodePort/ClusterIP 服务流量reason为 0 表示转发大于 0 表示丢包原因码映射支持 pinningLIBBPF_PIN_BY_NAME因此用户态工具可以在 Agent 初始化后按名加载。Go 侧的对应结构定义在 pkg/maps/metricsmap/metricsmap.go并注释要求与bpf/lib/metrics.h保持同步type Key struct { Reason uint8 align:reason Dir uint8 align:dir Line uint16 align:line File uint8 align:file Reserved [3]uint8 align:reserved } type Value struct { Count uint64 align:count Bytes uint64 align:bytes }数据面如何写入指标BPF 侧通过update_metrics宏在每个计数点更新映射见 bpf/lib/metrics.h该宏自动注入__MAGIC_LINE__触发计数语句所在行号与__MAGIC_FILE__源文件 ID这正是list输出中LINE、FILE两列的来源#define update_metrics(bytes, direction, reason) \ _update_metrics(bytes, direction, reason, __MAGIC_LINE__, __MAGIC_FILE__)方向还提供ct_to_metrics_dir将连接跟踪方向CT_INGRESS/CT_EGRESS/CT_SERVICE转换为指标方向bpf/lib/metrics.h。用户态如何读出指标命令加载映射后调用metricsmap.LoadMetricsMap随后listMetrics通过IterateWithCallback遍历全部 key/value见 bpf_metrics_list.go并借助extractRow将原始 key/value 转成可读行bpf_metrics_list.gofunc extractRow(key *metricsmap.Key, values *metricsmap.Values) *metricsRow { return metricsRow{ key.Reason, key.DropForwardReason(), // 丢包/转发原因字符串 key.Direction(), // INGRESS/EGRESS/SERVICE/UNKNOWN values.Count(), // 所有 per-CPU 计数求和 values.Bytes(), // 所有 per-CPU 字节求和 key.Line, key.FileName(), } }由于映射是 Per-CPU 结构Count()与Bytes()会对所有 CPU 上的值求和见 metricsmap.go。与 Prometheus 指标的关系同一个cilium_metrics映射也驱动 Agent 的 Prometheus 采集器metricsmapCollector见 pkg/maps/metricsmap/metricsmap.go对外暴露cilium_drop_bytes_total、cilium_drop_count_total、cilium_forward_count_total、cilium_forward_bytes_total、cilium_mtu_error_message_total、cilium_fragmented_count_total等指标。二者的定位差异值得注意为控制基数、避免破坏既有查询与告警规则Prometheus/metrics端点不暴露line/file标签而cilium-dbg bpf metrics list始终输出全部属性且结果会包含在 sysdump 中是定位数据面计数语句出处具体到 BPF 源码行的最佳途径。这也解释了line/file字段在 key 中的存在意义——它们是专为排障设计的埋点坐标。使用场景与实战示例1. 查看完整数据面转发/丢包统计在运行 Cilium Agent 的节点上需 root 权限sudo cilium-dbg bpf metrics list输出示例表格格式REASON DIRECTION PACKETS BYTES LINE FILE Success ingress 123456 8192000 420 bpf_lxc.c Drop egress 12 960 1337 bpf_host.c2. 结构化输出用于脚本与自动化巡检cilium-dbg bpf metrics list -o json cilium-dbg bpf metrics list -o yaml cilium-dbg bpf metrics list -o jsonpath{range .items[*]}{.reason} {.direction} {.packets}{\n}{end}JSON 输出可直接通过jq过滤例如只查看丢包条目cilium-dbg bpf metrics list -o json | jq .[] | select(.reason ! Success)jsonpath模板语法遵循pkg/command的输出框架约定可按需定制字段。3. 结合 flush 做差分测试flush子命令可清空映射仅用于测试见 bpf_metrics_flush.go常用于sudo cilium-dbg bpf metrics flush # 清零 # …执行需要观测的流量… sudo cilium-dbg bpf metrics list -o json # 只看到本次观测窗口内的计数4. 通过 LINE/FILE 字段定位计数点当发现某个方向的丢包异常时利用输出中的LINE与FILE列可直接定位到对应的 BPF 源文件如bpf_lxc.c、bpf_host.c、bpf_overlay.c等与具体行号对照 bpf/ 目录下的源码即可找到触发该计数语句的代码路径。使用限制与注意事项权限要求读取 BPF 映射需要 root 权限命令内部会调用common.RequireRootPrivilege普通用户直接执行会失败依赖 Agent 初始化LoadMetricsMap依赖 Cilium Agent 已初始化并 pin 好cilium_metrics映射若映射不存在会报错error loading BPF metrics map本机执行该命令直接操作本地 BPF 映射不依赖 API Server因此-H等继承选项在此子命令中的实际作用有限计数器语义reason为 0 表示转发成功大于等于DropMin130见 pkg/monitor/api/drop.go为丢包原因码DIRECTION涵盖INGRESS、EGRESS、SERVICE与UNKNOWN四种取值见 metricsmap.go。相关参考命令族总览Documentation/cmdref/cilium-dbg_bpf_metrics.md清空指标Documentation/cmdref/cilium-dbg_bpf_metrics_flush.md命令源码cilium-dbg/cmd/bpf_metrics_list.go、cilium-dbg/cmd/bpf_metrics_flush.go单元测试cilium-dbg/cmd/bpf_metrics_list_test.go映射定义与采集器pkg/maps/metricsmap/metricsmap.go、pkg/maps/metricsmap/doc.goBPF 侧计数实现bpf/lib/metrics.h原因码与文件名解析pkg/monitor/api/drop.go、pkg/monitor/api/files.go【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium 数据面流量指标查询指南：cilium-dbg bpf metrics list 详解
Cilium 数据面流量指标查询指南cilium-dbg bpf metrics list 详解【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文以 Cilium 的cilium-dbg bpf metrics list命令为核心讲解如何直接从内核 eBPF 数据面读取流量转发与丢包统计信息。该命令面向需要深入排查数据面行为的开发者与运维人员相比 Prometheus/metrics端点它能输出包含源码行号、文件名等细粒度定位信息的完整指标。读完本文你将掌握该命令的完整语法、输出字段含义、底层 BPF 指标映射cilium_metrics的数据结构与计数机制以及 JSON/YAML 等结构化输出在自动化巡检中的用法。命令概览cilium-dbg bpf metrics list用于列出 Cilium 数据面datapath的 BPF 流量指标是cilium-dbg bpf metrics命令族详见 cilium-dbg_bpf_metrics.md下的子命令同族还包括 flush清空指标仅供测试。cilium-dbg bpf metrics list [flags]命令的Short描述为 List BPF datapath traffic metrics。从源码看该命令定义在 bpf_metrics_list.govar bpfMetricsListCmd cobra.Command{ Use: list, Short: List BPF datapath traffic metrics, Run: func(cmd *cobra.Command, args []string) { common.RequireRootPrivilege(cilium bpf metrics list) mm, err : metricsmap.LoadMetricsMap(log) if err ! nil { fmt.Fprintf(os.Stderr, error loading BPF metrics map: %v\n, err) os.Exit(1) } listMetrics(mm) }, }可见该命令有两个显著特征需要 root 权限命令入口首先调用common.RequireRootPrivilege因为访问 BPF 映射需要足够的权限直接读取 BPF 映射通过metricsmap.LoadMetricsMap加载名为cilium_metrics的 eBPF 映射映射初始化由 Cilium Agent 完成见 metricsmap.go不经过 API Server因此必须在本机或能访问到该映射的环境执行。可用选项Options-h, --help help for list -o, --output string json| yaml| jsonpath{}选项类型说明-h, --helpbool显示帮助信息-o, --output stringstring指定输出格式json、yaml或jsonpath{}不指定时输出人类可读的表格该选项由command.AddOutputOption(bpfMetricsListCmd)注册见 bpf_metrics_list.go底层复用pkg/command的统一输出框架。父命令继承的全局选项以下选项继承自cilium-dbg根命令--config string Config file (default is $HOME/.cilium.yaml) -D, --debug Enable debug messages -H, --host string URI to server-side API --log-driver strings Logging endpoints to use (example: syslog) --log-opt map Log driver options (example: formatjson)选项说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug开启调试日志-H, --host string服务端 API 的 URI--log-driver strings日志输出端点例如syslog--log-opt map日志驱动选项例如formatjson输出字段与示例人类可读的表格输出不指定-o时命令通过text/tabwriter输出对齐的文本表格见 bpf_metrics_list.go表头如下REASON DIRECTION PACKETS BYTES LINE FILE列含义REASON丢包原因或转发原因例如Success、Drop类原因码对应的可读字符串DIRECTION流量方向INGRESS、EGRESS、SERVICE或UNKNOWNPACKETS累计处理的数据包数量BYTES累计处理的字节数LINE触发该计数语句的 BPF 源码行号__MAGIC_LINE__FILE触发该计数的 BPF 源文件名__MAGIC_FILE__输出会按六列字典序整体排序便于阅读。表头的常量定义于 bpf_metrics_list.goconst ( reasonTitle REASON directionTitle DIRECTION packetsTitle PACKETS bytesTitle BYTES lineTitle LINE fileTitle FILE )结构化输出-o json时输出每条指标的 JSON 对象字段结构定义在 bpf_metrics_list.gotype jsonMetric struct { Reason string json:reason Direction string json:direction Packets uint64 json:packets Bytes uint64 json:bytes Line uint16 json:line File string json:file }示例-o json[ { reason: Success, direction: ingress, packets: 100, bytes: 1000, line: 0, file: } ]注意两点细节DIRECTION在表格输出中为大写INGRESS而在 JSON 输出中经strings.ToLower转为小写ingressREASON通过monitorAPI.DropReason解析为可读字符串具体映射见 pkg/monitor/api/drop.go 附近。关键兼容性逻辑相同 key 计数合并源码中对 JSON 输出做了特殊处理由于 Cilium 1.16 起在映射 key 中启用了line、file字段此前为保留位新版本写入的指标在旧版本 Agent 看来会呈现为重复的条目。为避免重复展示listJSONMetrics将reason direction line file相同的行合并并把packets、bytes相加见 bpf_metrics_list.go。该行为有对应的单元测试佐证bpf_metrics_list_test.go 中的TestDumpMetrics构造了一个含重复key 的 mock 映射Key{Reason: 132, Dir: 2}出现两次断言最终 JSON 中该条目的Packets为301 300 1、Bytes为3001 3000 1。底层实现原理eBPF 指标映射cilium_metricscilium-dbg bpf metrics list读取的映射定义于 BPF 侧 bpf/lib/metrics.hstruct metrics_key { __u8 reason; /* 0: forwarded, 0 dropped */ __u8 dir:2, /* 1: ingress 2: egress */ pad:6; __u16 line; /* __MAGIC_LINE__ */ __u8 file; /* __MAGIC_FILE__, needs to fit __id_for_file */ __u8 reserved[3]; /* reserved for future extension */ }; struct metrics_value { __u64 count; __u64 bytes; }; struct { __uint(type, BPF_MAP_TYPE_PERCPU_HASH); __type(key, struct metrics_key); __type(value, struct metrics_value); __uint(pinning, LIBBPF_PIN_BY_NAME); __uint(max_entries, METRICS_MAP_SIZE); __uint(map_flags, CONDITIONAL_PREALLOC); } cilium_metrics __section_maps_btf;要点映射类型为BPF_MAP_TYPE_PERCPU_HASHPer-CPU 哈希表每个 CPU 各自累加计数避免跨 CPU 锁竞争dir只占用 2 bit取值范围为1: ingress、2: egress另有3: serviceNodePort/ClusterIP 服务流量reason为 0 表示转发大于 0 表示丢包原因码映射支持 pinningLIBBPF_PIN_BY_NAME因此用户态工具可以在 Agent 初始化后按名加载。Go 侧的对应结构定义在 pkg/maps/metricsmap/metricsmap.go并注释要求与bpf/lib/metrics.h保持同步type Key struct { Reason uint8 align:reason Dir uint8 align:dir Line uint16 align:line File uint8 align:file Reserved [3]uint8 align:reserved } type Value struct { Count uint64 align:count Bytes uint64 align:bytes }数据面如何写入指标BPF 侧通过update_metrics宏在每个计数点更新映射见 bpf/lib/metrics.h该宏自动注入__MAGIC_LINE__触发计数语句所在行号与__MAGIC_FILE__源文件 ID这正是list输出中LINE、FILE两列的来源#define update_metrics(bytes, direction, reason) \ _update_metrics(bytes, direction, reason, __MAGIC_LINE__, __MAGIC_FILE__)方向还提供ct_to_metrics_dir将连接跟踪方向CT_INGRESS/CT_EGRESS/CT_SERVICE转换为指标方向bpf/lib/metrics.h。用户态如何读出指标命令加载映射后调用metricsmap.LoadMetricsMap随后listMetrics通过IterateWithCallback遍历全部 key/value见 bpf_metrics_list.go并借助extractRow将原始 key/value 转成可读行bpf_metrics_list.gofunc extractRow(key *metricsmap.Key, values *metricsmap.Values) *metricsRow { return metricsRow{ key.Reason, key.DropForwardReason(), // 丢包/转发原因字符串 key.Direction(), // INGRESS/EGRESS/SERVICE/UNKNOWN values.Count(), // 所有 per-CPU 计数求和 values.Bytes(), // 所有 per-CPU 字节求和 key.Line, key.FileName(), } }由于映射是 Per-CPU 结构Count()与Bytes()会对所有 CPU 上的值求和见 metricsmap.go。与 Prometheus 指标的关系同一个cilium_metrics映射也驱动 Agent 的 Prometheus 采集器metricsmapCollector见 pkg/maps/metricsmap/metricsmap.go对外暴露cilium_drop_bytes_total、cilium_drop_count_total、cilium_forward_count_total、cilium_forward_bytes_total、cilium_mtu_error_message_total、cilium_fragmented_count_total等指标。二者的定位差异值得注意为控制基数、避免破坏既有查询与告警规则Prometheus/metrics端点不暴露line/file标签而cilium-dbg bpf metrics list始终输出全部属性且结果会包含在 sysdump 中是定位数据面计数语句出处具体到 BPF 源码行的最佳途径。这也解释了line/file字段在 key 中的存在意义——它们是专为排障设计的埋点坐标。使用场景与实战示例1. 查看完整数据面转发/丢包统计在运行 Cilium Agent 的节点上需 root 权限sudo cilium-dbg bpf metrics list输出示例表格格式REASON DIRECTION PACKETS BYTES LINE FILE Success ingress 123456 8192000 420 bpf_lxc.c Drop egress 12 960 1337 bpf_host.c2. 结构化输出用于脚本与自动化巡检cilium-dbg bpf metrics list -o json cilium-dbg bpf metrics list -o yaml cilium-dbg bpf metrics list -o jsonpath{range .items[*]}{.reason} {.direction} {.packets}{\n}{end}JSON 输出可直接通过jq过滤例如只查看丢包条目cilium-dbg bpf metrics list -o json | jq .[] | select(.reason ! Success)jsonpath模板语法遵循pkg/command的输出框架约定可按需定制字段。3. 结合 flush 做差分测试flush子命令可清空映射仅用于测试见 bpf_metrics_flush.go常用于sudo cilium-dbg bpf metrics flush # 清零 # …执行需要观测的流量… sudo cilium-dbg bpf metrics list -o json # 只看到本次观测窗口内的计数4. 通过 LINE/FILE 字段定位计数点当发现某个方向的丢包异常时利用输出中的LINE与FILE列可直接定位到对应的 BPF 源文件如bpf_lxc.c、bpf_host.c、bpf_overlay.c等与具体行号对照 bpf/ 目录下的源码即可找到触发该计数语句的代码路径。使用限制与注意事项权限要求读取 BPF 映射需要 root 权限命令内部会调用common.RequireRootPrivilege普通用户直接执行会失败依赖 Agent 初始化LoadMetricsMap依赖 Cilium Agent 已初始化并 pin 好cilium_metrics映射若映射不存在会报错error loading BPF metrics map本机执行该命令直接操作本地 BPF 映射不依赖 API Server因此-H等继承选项在此子命令中的实际作用有限计数器语义reason为 0 表示转发成功大于等于DropMin130见 pkg/monitor/api/drop.go为丢包原因码DIRECTION涵盖INGRESS、EGRESS、SERVICE与UNKNOWN四种取值见 metricsmap.go。相关参考命令族总览Documentation/cmdref/cilium-dbg_bpf_metrics.md清空指标Documentation/cmdref/cilium-dbg_bpf_metrics_flush.md命令源码cilium-dbg/cmd/bpf_metrics_list.go、cilium-dbg/cmd/bpf_metrics_flush.go单元测试cilium-dbg/cmd/bpf_metrics_list_test.go映射定义与采集器pkg/maps/metricsmap/metricsmap.go、pkg/maps/metricsmap/doc.goBPF 侧计数实现bpf/lib/metrics.h原因码与文件名解析pkg/monitor/api/drop.go、pkg/monitor/api/files.go【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考