From 4892322e43d426ee7a702ac357efe2cf3feda425 Mon Sep 17 00:00:00 2001 From: Nick Zavaritsky Date: Fri, 3 Oct 2025 20:34:38 +0200 Subject: [PATCH] docs: promexporter and top level Signed-off-by: Nick Zavaritsky --- README.md | 14 ++++++ promexporter/README.md | 110 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 README.md create mode 100644 promexporter/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5396e0e --- /dev/null +++ b/README.md @@ -0,0 +1,14 @@ +# tech.emnify.com/go/ebpfkit + +eBPF-related technologies + +## [promexporter](promexporter) + +Package `promexporter` exposes metrics hosted in eBPF per-CPU array map to Prometheus. + +## [testing/ebpftest](testing/ebpftest) + +`ebpftest` package contains Golang utilities and helpers that simplify testing of eBPF programs from Golang userpace. + +For the first time ever, mocking meets eBPF! + diff --git a/promexporter/README.md b/promexporter/README.md new file mode 100644 index 0000000..1029c04 --- /dev/null +++ b/promexporter/README.md @@ -0,0 +1,110 @@ +# promexporter + +Package `promexporter` exposes metrics hosted in eBPF [per-CPU array map](https://docs.ebpf.io/linux/map-type/BPF_MAP_TYPE_PERCPU_ARRAY/) +to Prometheus. + +Ex: + +```c +struct metrics { + __u64 foo; + __u64 bar; +}; + +struct { + __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); + __uint(max_entries, 1); + __type(key, int); + __type(value, struct metrics); +} metrics_map SEC(".maps"); +``` + +Pass `metrics_map` as `*ebpf.Map` to `promexporter.NewMetrics` to initialize an exporter. +The exporter automatically parses eBPF typeinfo and exposes every `__u64` field +found in `struct metrics`: + +``` +foo 42 # TYPE foo untyped +bar 1337 # TYPE bar untyped +``` + +## Nested structures + +Fields found in nested structures are exposed. E.g. + +```c +struct metrics { + struct net_stats { + __u64 bytes_total; + __u64 packets_total; + } ingress, egress; +}; +``` +produces +``` +ingress_bytes_total 1240440446 # TYPE ingress_bytes_total untyped +ingress_packets_total 4801015 # TYPE ingress_packets_total untyped +egress_bytes_total 1368631333 # TYPE egress_bytes_total untyped +egress_packets_total 3585747 # TYPE egress_packets_total untyped +``` +## Fine-tuning metrics + +Prometheus supports different metric types, such as counters and gauges. +Use `PROM_TYPE("type")` macro to specify the metric type. + +`PROM_TYPE` and further macros are defined in `exporter.h` + +Note: it might be necessary to literally copy `exporter.h` into your project. +We contributed support in Cilium's `bpf2go` for pulling C headers from external Golang +packages, but unfortunately it was [rejected](https://github.com/cilium/ebpf/pull/1625). + +Pulling a header from an external Golang project should be as easy as +``` +#include +``` + +### Metric types + +```c +struct net_stats { + __u64 bytes_total; + __u64 packets_total; +} PROM_TYPE("counter"); + +struct metrics { + struct net_stats ingress, egress; +}; +``` + +`PROM_TYPE` on a structure applies to all enclosed fields. +Alternatively, one can attach `PROM_TYPE` to individual fields. +Supported types include `"counter"`, `"gauge"` and vectors (see next section). + +``` +ingress_bytes_total 1240440446 # TYPE ingress_bytes_total counter +ingress_packets_total 4801015 # TYPE ingress_packets_total counter +egress_bytes_total 1368631333 # TYPE egress_bytes_total counter +egress_packets_total 3585747 # TYPE egress_packets_total counter +``` + +### Counter and gauge vectors + +```c +struct drop_stats { + __u64 truncated; + __u64 bad_checksum; +} PROM_TYPE("counter_vec") LABEL("drop_reason"); + +struct metrics { + struct drop_stats drops_total; +}; +``` + +Vectors are convenient to group related metrics such as `drops_total`. + + +``` +# TYPE drops_total counter +drops_total{drop_reason="truncated"} 0 +drops_total{drop_reason="bad_checksum"} 0 +```