{"id":13839622,"url":"https://github.com/YutaroHayakawa/ipftrace2","last_synced_at":"2025-07-11T06:31:00.434Z","repository":{"id":40612932,"uuid":"248024714","full_name":"YutaroHayakawa/ipftrace2","owner":"YutaroHayakawa","description":"A packet oriented Linux kernel function call tracer","archived":false,"fork":false,"pushed_at":"2024-04-14T02:35:14.000Z","size":17974,"stargazers_count":388,"open_issues_count":0,"forks_count":17,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-13T20:02:48.119Z","etag":null,"topics":["bpf","ebpf","linux-kernel","network","tracing"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YutaroHayakawa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-17T16:53:52.000Z","updated_at":"2024-11-09T18:11:26.000Z","dependencies_parsed_at":"2023-02-15T15:31:51.055Z","dependency_job_id":"477b2515-99ca-4bec-b9e1-fd5dfffe0b87","html_url":"https://github.com/YutaroHayakawa/ipftrace2","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YutaroHayakawa%2Fipftrace2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YutaroHayakawa%2Fipftrace2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YutaroHayakawa%2Fipftrace2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YutaroHayakawa%2Fipftrace2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YutaroHayakawa","download_url":"https://codeload.github.com/YutaroHayakawa/ipftrace2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225699949,"owners_count":17510431,"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":["bpf","ebpf","linux-kernel","network","tracing"],"created_at":"2024-08-04T17:00:31.440Z","updated_at":"2024-11-21T08:31:20.593Z","avatar_url":"https://github.com/YutaroHayakawa.png","language":"C","funding_links":[],"categories":["C","C (286)"],"sub_categories":[],"readme":"# ipftrace2\n\n`ipftrace2` is a tool which allows you to trace the journey of packets inside the Linux kernel. It is similar to `ftrace` in some sense, but you can trace **which flow has gone through which functions** inside the kernel which is usually more important information for the network people than **which functions are called** information provided by `ftrace`.\n\n![demo](img/demo.gif)\n\n## Requirements\n\n- Architecture: x86_64\n\n- Linux version: v4.17 or above\n\n- Kernel config\n\n  - CONFIG_DEBUG_INFO_BTF=y\n  - CONFIG_KPROBES=y\n  - CONFIG_PERF_EVENTS=y\n  - CONFIG_BPF=y\n  - CONFIG_BPF_SYSCALL=y\n\n  - CONFIG_DEBUG_INFO_BTF_MODULE=y (Optional)\n    - Enabling this allows ipftrace2 to trace kernel module's functions\n\n## Install\n\nipftrace2 is a single-binary application. You don't have to install any dependencies.\n\n```\ncurl -OL https://github.com/YutaroHayakawa/ipftrace2/releases/latest/download/ipftrace2_amd64.tar.gz\ntar xvf ipftrace2_amd64.tar.gz\nsudo cp ipft /usr/local/bin/ipft\n```\n\n## Basic usage\n\nRun ipftrace2\n\n```\nsudo ipft -m 0xdeadbeef\n```\n\nMark the packets you are interested in\n\n```\n# Mark packets from/to 1.1.1.1\nsudo iptables -t raw -A OUTPUT -d 1.1.1.1 -j MARK --set-mark 0xdeadbeef\nsudo iptables -t raw -A PREROUTING -s 1.1.1.1 -j MARK --set-mark 0xdeadbeef\n```\n\nMake some traffic\n\n```\ncurl https://1.1.1.1\n```\n\nTerminate `ipft` with `Ctrl-C` . Then, you should see the output.\n\n## Feature highlight\n\n#### Function tracer\n\nRecords function calls for packets. This is the default tracer.\n\n```\n$ sudo ipft -m 0xdeadbeef\n\u003cskip...\u003e\n96976848684329       000                      nf_checksum\n96976848692769       000                   nf_ip_checksum\n96976848765647       000               tcp_v4_early_demux\n96976848836855       000                 ip_local_deliver\n96976848840849       000                     nf_hook_slow\n96976848846012       000          ip_local_deliver_finish\n96976848851032       000          ip_protocol_deliver_rcu\n\u003cskip...\u003e\n```\n\n#### Function graph tracer\n\nRecords function calls as well as function returns and visualizes the call depth.\n\n```\n$ sudo ipft -m 0xdeadbeef -t function_graph\n\u003cskip...\u003e\n480959550911894      000 ip_protocol_deliver_rcu() {\n480959550913049      000   raw_local_deliver() {\n480959550914188      000   }\n480959550915380      000   tcp_v4_rcv() {\n480959550916635      000     tcp_filter() {\n480959550917812      000       sk_filter_trim_cap() {\n480959550918999      000         security_sock_rcv_skb() {\n480959550920116      000         }\n480959550921258      000       }\n480959550922397      000     }\n\u003cskip...\u003e\n```\n\n#### Raw JSON output\n\nGenerates raw tracing output to `stdout` in machine-readable JSON. You can implement your own visualizer with this feature.\n\n```\n$ sudo ipft -m 0xdeadbeef -t function_graph -o json\n\u003cskip...\u003e\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022557487,\"processor_id\":0,\"function\":\"validate_xmit_xfrm\",\"is_return\":false}\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022558860,\"processor_id\":0,\"function\":\"validate_xmit_xfrm\",\"is_return\":true}\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022560159,\"processor_id\":0,\"function\":\"validate_xmit_skb\",\"is_return\":true}\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022561440,\"processor_id\":0,\"function\":\"validate_xmit_skb_list\",\"is_return\":true}\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022572083,\"processor_id\":0,\"function\":\"dev_hard_start_xmit\",\"is_return\":false}\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022574087,\"processor_id\":0,\"function\":\"skb_clone_tx_timestamp\",\"is_return\":false}\n{\"packet_id\":\"0xffff8dee8aea9700\",\"timestamp\":25340022575519,\"processor_id\":0,\"function\":\"skb_clone_tx_timestamp\",\"is_return\":true}\n\u003cskip...\u003e\n```\n\n#### Custom tracing output\n\nYou can customize your tracing output by providing custom extension.\n\n```\n$ sudo ipft -m 0xdeadbeef -e example.c\n\u003cskip...\u003e\n96976848684329       000                      nf_checksum ( len: 2822 )\n96976848692769       000                   nf_ip_checksum ( len: 2822 )\n96976848765647       000               tcp_v4_early_demux ( len: 2822 )\n96976848836855       000                 ip_local_deliver ( len: 2822 )\n96976848840849       000                     nf_hook_slow ( len: 2822 )\n96976848846012       000          ip_local_deliver_finish ( len: 2822 )\n96976848851032       000          ip_protocol_deliver_rcu ( len: 2802 )\n\u003cskip...\u003e\n```\n\nOf course, you can use scripting together with JSON output.\n\n```\n$ sudo ipft -m 0xdeadbeef -e example.c -o json\n\u003cskip...\u003e\n{\"packet_id\":\"0xffff935007672900\",\"timestamp\":169530008921,\"processor_id\":0,\"function\":\"__ip_finish_output\",\"is_return\":false,\"len\":\"40\"}\n{\"packet_id\":\"0xffff935007672900\",\"timestamp\":169530010558,\"processor_id\":0,\"function\":\"ip_finish_output2\",\"is_return\":false,\"len\":\"40\"}\n{\"packet_id\":\"0xffff935007672900\",\"timestamp\":169530012511,\"processor_id\":0,\"function\":\"dev_queue_xmit\",\"is_return\":false,\"len\":\"54\"}\n{\"packet_id\":\"0xffff935007672900\",\"timestamp\":169530014441,\"processor_id\":0,\"function\":\"__dev_queue_xmit\",\"is_return\":false,\"len\":\"54\"}\n{\"packet_id\":\"0xffff935007672900\",\"timestamp\":169530017180,\"processor_id\":0,\"function\":\"netdev_core_pick_tx\",\"is_return\":false,\"len\":\"54\"}\n\u003cskip...\u003e\n```\n\n## Usage\n\n```\nUsage: ipft [OPTIONS]\n\nOptions:\n -b, --backend            [BACKEND]       Specify trace backend\n -e, --extension          [PATH]          Path to extension (the file name must be have .c, .o, or .lua suffix)\n     --gen                [TARGET]        Generate something\n -h, --help                               Show this text\n -l, --list                               List functions\n -m, --mark               [NUMBER]        Trace the packet marked with \u003cmark\u003e [required]\n   , --mask               [NUMBER]        Only match to the bits masked with given bitmask (default: 0xffffffff)\n   , --module-regex       [REGEX]         Filter the function to trace by regex for kernel module's name\n -o, --output             [OUTPUT-FORMAT] Specify output format\n -r, --regex              [REGEX]         Filter the function to trace with regex\n -s, --script             [PATH]          Path to extension Lua script (deprecated, use -e instead)\n -t, --tracer             [TRACER-TYPE]   Specify tracer type\n -v, --verbose                            Turn on debug message\n   , --perf-page-count    [NUMBER]        See page_count of perf_event_open(2) man page (default: 8)\n   , --perf-sample-period [NUMBER]        See sample_period of perf_event_open(2) man page (default: 1)\n   , --perf-wakeup-events [NUMBER]        See wakeup_events of perf_event_open(2) man page (default: 1)\n   , --no-set-rlimit                      Don't set rlimit\n   , --enable-probe-server                Enable probe server\n   , --probe-server-port                  Set probe server port\n\nBACKEND       := { kprobe, ftrace, kprobe-multi }\nOUTPUT-FORMAT := { aggregate, json }\nTRACER-TYPE   := { function, function_graph (experimental) }\nTARGET        := { bpf-module-skeleton, bpf-module-header }\n```\n\n## Further reading\n\n- [BPF extension manual (recommended)](docs/bpf_extension.md) gives you the guide guide to customize your tracing output\n- [Lua extension manual (deprecated)](docs/lua_extension.md) gives you the guide to customize your tracing output in legacy Lua extension\n- With [output specification](docs/output.md), you can learn how to interpret the output\n- Understanding [marking](docs/marking.md) helps you a lot for fully utilizing the power of ipftrace2\n- Please check this [doc](docs/internals.md) out if you are interested in the ipftrace2 internals\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYutaroHayakawa%2Fipftrace2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYutaroHayakawa%2Fipftrace2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYutaroHayakawa%2Fipftrace2/lists"}