{"id":13580204,"url":"https://github.com/ebpfdev/explorer","last_synced_at":"2025-04-10T11:11:48.519Z","repository":{"id":170406233,"uuid":"646518251","full_name":"ebpfdev/explorer","owner":"ebpfdev","description":"eBPF explorer is Web UI that lets you see all the maps and programs in eBPF subsystem","archived":false,"fork":false,"pushed_at":"2023-06-18T12:38:55.000Z","size":5493,"stargazers_count":85,"open_issues_count":9,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-24T10:03:46.590Z","etag":null,"topics":["ebpf"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ebpfdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-05-28T16:49:40.000Z","updated_at":"2025-03-08T16:02:43.000Z","dependencies_parsed_at":"2024-01-02T20:52:07.700Z","dependency_job_id":null,"html_url":"https://github.com/ebpfdev/explorer","commit_stats":null,"previous_names":["ebpfdev/explorer"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebpfdev%2Fexplorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebpfdev%2Fexplorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebpfdev%2Fexplorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebpfdev%2Fexplorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebpfdev","download_url":"https://codeload.github.com/ebpfdev/explorer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248208562,"owners_count":21065202,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebpf"],"created_at":"2024-08-01T15:01:48.625Z","updated_at":"2025-04-10T11:11:48.501Z","avatar_url":"https://github.com/ebpfdev.png","language":"Dockerfile","funding_links":[],"categories":["Projects Related to eBPF","Dockerfile"],"sub_categories":["Tools"],"readme":"# eBPF explorer\n\neBPF is a web UI that lets you explore eBPF subsystem of your Linux host.\n\nExplorer consists of two parts: an agent with GraphQL API, Prometheus scrape endpoint, and a web interface.\nIt is currently shipped as a single container. But you can also run them separately.\n\n* [ebpfdev/dev-agent](https://github.com/ebpfdev/dev-agent), MIT license\n* [ebpfdev/explorer-ui](https://github.com/ebpfdev/explorer-ui), MIT license\n\n## Features\n\n* view all maps and programs\n* view graph of interconnected maps and programs\n* view program's tracepoints/kprobe\n* map entries table (Hash, HashPerCPU, Array, ArrayPerCPU)\n  * view and edit in number/hex/string formats\n* expose map entries as metrics for prometheus (also other useful metrics)\n\n![map editor demo gif](docs/pics/X_004RN_mapedit.gif)\n\n## Usage\n\nRun explorer as a container:\n\n```shell\ndocker run -ti --rm -p 8070:80 \\\n  --cap-add CAP_SYS_ADMIN --pid=host \\\n  -e BPF_DIR=/sys/fs/bpf -v /sys/fs/bpf:/sys/fs/bpf \\\n  ghcr.io/ebpfdev/explorer:v0.0.7\n```\n\nPrivileges breakdown:\n\n* `--cap-add CAP_SYS_ADMIN` (**required**)\n\n  is needed for access BPF maps and programs (CAP_BPF is not yet enough)\n\n* `--pid=host` (_optional_)\n\n  is needed to determine tracepoint/kprobe attachment\n\n* `-e BPF_DIR=/sys/fs/bpf -v /sys/fs/bpf:/sys/fs/bpf` (_optional_)\n  \n  is needed to determine paths of pinned maps, it is better to keep BPF_DIR (and target mount path)\n  the same as your original eBPF FS, which can be determined with the following command:\n  ```shell\n  $ mount | grep bpf\n  bpf on /sys/fs/bpf type bpf\n  ```\n\n\nUse `--etm` option to expose map (with name `AT_`) entries values to Prometheus endpoint:\n```shell\ndocker run -ti --rm -p 8070:80 \\\n  --cap-add CAP_SYS_ADMIN --pid=host \\\n  -e BPF_DIR=/sys/fs/bpf -v /sys/fs/bpf:/sys/fs/bpf \\\n  ghcr.io/ebpfdev/explorer:v0.0.7 --etm -:AT_:string\n```\n\nIf you only need GraphQL / Prometheus without web interface, you can run [agent](https://github.com/ebpfdev/dev-agent) independently:\n```shell\ndocker run -ti --rm -p 8080:8080 \\\n  --cap-add CAP_SYS_ADMIN --pid=host \\\n  -e BPF_DIR=/sys/fs/bpf -v /sys/fs/bpf:/sys/fs/bpf \\\n  ghcr.io/ebpfdev/dev-agent:v0.0.5 server\n```\n\nLinks:\n* [http://localhost:8070](http://localhost:8070) - web interface\n* [http://localhost:8070/dev-agent](http://localhost:8070/dev-agent) - Agent's GraphQL web client\n* [http://localhost:8070/dev-agent/metrics](http://localhost:8070/dev-agent/metrics) - Prometheus scrape endpoint\n\n# Demo\n\nRun the explorer as described above and open [http://localhost:8070](http://localhost:8070) in your browser.\n\nYou should see a file tree view with a list of eBPF programs and maps:\n\n![List of maps](docs/pics/00-start.png)\n\nLet's use [bpftrace](https://github.com/iovisor/bpftrace) to track amount of data read by each process:\n```shell\n$ sudo bpftrace -e 'tracepoint:syscalls:sys_exit_read /args-\u003eret/ { @[comm] = sum(args-\u003eret); }'\nAttaching 1 probe...\n```\n\nOnce you run it, list will be automatically updated:\n\n![A list of maps containing two new maps](docs/pics/01-list-with-bpftrace.png)\n\n`...`\n\n![A list of programs with the new sys_exit_read](docs/pics/02-list-with-sys_exit_read.png)\n\nLet's examine the `sys_exit_read` program:\n\n![sys_exit_read program page](docs/pics/03-sys_exit_read-page.png)\n\nWe can see that this new program is using a new map called `AT_`.\nWhich probably means that it contains state of `@` variable of the program generated by `bpftrace`.\n\nThere is also `printf` map of type PerfEventArray. It is probably used by `printf()` invocation within `bpftrace` programs\nand created regardless of whatever you actually use it or not: out program doesnt use it therefore we also\ndon't see that is used by the program in UI.\n\nWe can proceed to the `AT_` map page:\n\n![Page of the AT map](docs/pics/04-at-map-page.png)\n\nOn the `Entries` subpage we can examine current state of the map:\n\n![Entries table of the AT map state](docs/pics/05-at-map-page-entries.png)\n\nValues are formatted as numbers by default if value size \u003c= 8 bytes. Otherwise, they are displayed as hex strings.\n\nWe can also switch `KEY` representation to `string`:\n\n![Entries table of the AT map state with string keys](docs/pics/06-at-map-page-entries-repr.png)\n\n# Prometheus scrape endpoint\n\nThere is a scrape endpoint for Prometheus available at `/metrics` path:\n```shell\n% curl http://localhost:8070/metrics\n# HELP devagent_ebpf_map_count Number of eBPF maps\n# TYPE devagent_ebpf_map_count gauge\ndevagent_ebpf_map_count{type=\"Hash\"} 5\ndevagent_ebpf_map_count{type=\"PerCPUHash\"} 1\ndevagent_ebpf_map_count{type=\"PerfEventArray\"} 1\n# HELP devagent_ebpf_map_entry_count Number of entries in an eBPF map\n# TYPE devagent_ebpf_map_entry_count gauge\ndevagent_ebpf_map_entry_count{id=\"14\",name=\"AT_\",type=\"PerCPUHash\"} 351\n# HELP devagent_ebpf_map_entry_value Value of an eBPF map entry\n# TYPE devagent_ebpf_map_entry_value gauge\ndevagent_ebpf_map_entry_value{cpu=\"0\",id=\"14\",key=\"(xtract-3)\",name=\"AT_\",type=\"PerCPUHash\"} 0\ndevagent_ebpf_map_entry_value{cpu=\"0\",id=\"14\",key=\"000resolvconf\",name=\"AT_\",type=\"PerCPUHash\"} 0\n# (...)\ndevagent_ebpf_map_entry_value{cpu=\"15\",id=\"14\",key=\"01-ifupdown\",name=\"AT_\",type=\"PerCPUHash\"} 0\n# (...)\n# HELP devagent_ebpf_prog_count Number of eBPF programs\n# TYPE devagent_ebpf_prog_count gauge\ndevagent_ebpf_prog_count{type=\"CGroupDevice\"} 19\ndevagent_ebpf_prog_count{type=\"CGroupSKB\"} 10\ndevagent_ebpf_prog_count{type=\"TracePoint\"} 1\n# HELP devagent_ebpf_prog_run_count Number of times an eBPF program has been run\n# TYPE devagent_ebpf_prog_run_count gauge\ndevagent_ebpf_prog_run_count{id=\"112\",name=\"\",tag=\"03b4eaae2f14641a\",type=\"CGroupDevice\"} 0\ndevagent_ebpf_prog_run_count{id=\"113\",name=\"\",tag=\"03b4eaae2f14641a\",type=\"CGroupDevice\"} 0\ndevagent_ebpf_prog_run_count{id=\"114\",name=\"\",tag=\"03b4eaae2f14641a\",type=\"CGroupDevice\"} 54\ndevagent_ebpf_prog_run_count{id=\"118\",name=\"sys_exit_read\",tag=\"90964a143ba6aa2c\",type=\"TracePoint\"} 2.866732e+06\ndevagent_ebpf_prog_run_count{id=\"127\",name=\"\",tag=\"3918c82a5f4c0360\",type=\"CGroupDevice\"} 7\n# (...)\n# HELP devagent_ebpf_prog_run_time Total time spent running eBPF programs\n# TYPE devagent_ebpf_prog_run_time gauge\ndevagent_ebpf_prog_run_time{id=\"112\",name=\"\",tag=\"03b4eaae2f14641a\",type=\"CGroupDevice\"} 0\ndevagent_ebpf_prog_run_time{id=\"113\",name=\"\",tag=\"03b4eaae2f14641a\",type=\"CGroupDevice\"} 0\ndevagent_ebpf_prog_run_time{id=\"114\",name=\"\",tag=\"03b4eaae2f14641a\",type=\"CGroupDevice\"} 6.857e-05\ndevagent_ebpf_prog_run_time{id=\"118\",name=\"sys_exit_read\",tag=\"90964a143ba6aa2c\",type=\"TracePoint\"} 1.405393686\ndevagent_ebpf_prog_run_time{id=\"127\",name=\"\",tag=\"3918c82a5f4c0360\",type=\"CGroupDevice\"} 2.314e-06\n# (...)\n```\n\nBy default, metrics `devagent_ebpf_map_entry_count` and `devagent_ebpf_map_entry_value` are disabled.\nTo enable them for some of the maps (Array or Hash types), use `--etm option`, for the demo above:\n```shell\ndocker run -ti --rm -p 8070:80 \\\n  --cap-add CAP_SYS_ADMIN --pid=host \\\n  -e BPF_DIR=/sys/fs/bpf -v /sys/fs/bpf:/sys/fs/bpf \\\n  ghcr.io/ebpfdev/explorer:v0.0.7 --etm -:AT_:string\n```\n\nRun with `--help` to see details of this option:\n```shell\n% docker run -ti --rm ghcr.io/ebpfdev/explorer:v0.0.7 --help               \n\n  (edited)\n\n   --entries-to-metrics value, --etm value [ --entries-to-metrics value, --etm value ]  (experimental, api may change)\n    Configure which map entries should be exposed as metrics, in the format: id_start-id_end:metric_name_regexp:key_format.\n    Example: '-:.+:string' to export any map with non-empty name while treating key as string.\n    or '10-:.*:hex' to export any map after ID 10 with key represented in HEX format\n    Available key formats: string, number, hex\n    If a map matches multiple entries, the first one is used.\n\n  (edited)\n```\n\nSome interesting visualization you could build with this data:\n\nPrograms run statistics:\n![07-grafana-ebpf.png](docs/pics/07-grafana-ebpf.png)\n\nAmount of system calls per process:\n![08-grafana-syscallnum.png](docs/pics/08-grafana-syscallnum.png)\n\n## Features\n\n- [x] list of eBPF programs + details page\n- [x] list of eBPF maps + details page\n- [x] showing bounded maps of a programs (and vice versa)\n- [ ] showing map content\n  - [x] Hash (+ per CPU)\n  - [x] Array (+ per CPU)\n  - [ ] others are planned\n- [ ] program introspection\n  - [ ] eBPF bytecode\n  - [ ] JIT disassembly\n- [ ] visualization of map's content\n\n    Like plotting a chart of values of maps keys\n- [ ] program execution profiling\n    \n    I plan to keep track of duration/number of executions of a programs provided by kernel\n    to draw nice charts\n- [ ] cluster support\n\n    To traverse over a cluster of agents within a single interface\n\nFeedback and suggestions are welcome in [GitHub Issues](https://github.com/ebpfdev/explorer/issues) or via [alex@hsslb.ch](mailto:alex@hsslb.ch)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febpfdev%2Fexplorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febpfdev%2Fexplorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febpfdev%2Fexplorer/lists"}