{"id":13559598,"url":"https://github.com/JakWai01/lurk","last_synced_at":"2025-04-03T15:30:39.198Z","repository":{"id":37480046,"uuid":"492468190","full_name":"JakWai01/lurk","owner":"JakWai01","description":"A pretty (simple) alternative to strace","archived":false,"fork":false,"pushed_at":"2025-02-04T14:12:00.000Z","size":552,"stargazers_count":962,"open_issues_count":13,"forks_count":32,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-02T11:11:28.720Z","etag":null,"topics":["cli","command-line-tool","rust","strace","terminal"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JakWai01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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,"publiccode":null,"codemeta":null}},"created_at":"2022-05-15T11:32:43.000Z","updated_at":"2025-03-31T19:20:37.000Z","dependencies_parsed_at":"2024-01-14T02:43:03.887Z","dependency_job_id":"9bb03cfe-7888-4b5c-9874-d4dc64cbfb88","html_url":"https://github.com/JakWai01/lurk","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakWai01%2Flurk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakWai01%2Flurk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakWai01%2Flurk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakWai01%2Flurk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JakWai01","download_url":"https://codeload.github.com/JakWai01/lurk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027677,"owners_count":20871571,"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":["cli","command-line-tool","rust","strace","terminal"],"created_at":"2024-08-01T13:00:29.744Z","updated_at":"2025-04-03T15:30:37.789Z","avatar_url":"https://github.com/JakWai01.png","language":"Rust","funding_links":[],"categories":["Rust","Dev-Utilities"],"sub_categories":[],"readme":"# lurk\n\n`lurk` is a simple and pretty alternative to `strace`. It allows the user to\ntrace system calls of a process or of a command. In contrast to `strace`,\n`lurk` focuses on a simple, yet pretty, user experience while implementing the\nmost important use cases of `strace`.\n\n## Demo\n\n![Demo](assets/screencast.svg)\n\n## Features\n\n- Supports an opinionated subset of strace flags.\n- Supports JSON output for further processing via e.g. `jq`\n- Uses colorized, formatted output ;-).\n\n## Installation\n\n### cURL\n```sh\ncurl -L -o /tmp/lurk.tar.gz \"https://github.com/JakWai01/lurk/releases/latest/download/lurk-x86_64-unknown-linux-gnu.tar.gz\"\ntar -xzf /tmp/lurk.tar.gz -C /tmp\nsudo install /tmp/lurk /usr/local/bin\n```\n\n### Cargo\n```sh\ncargo install lurk-cli\n```\n\n### Arch Linux\n```sh\npacman -S lurk\n```\n\n## Usage\n\nTo get a quick overview, you can run `lurk --help`:\n\n```\nlurk 0.2.7\n\nUSAGE:\n    lurk [OPTIONS] [command]...\n\nARGS:\n    \u003ccommand\u003e...    Trace command\n\nOPTIONS:\n    -c, --summary-only\n            Report a summary instead of the regular output\n\n    -C, --summary\n            Report a summary in addition to the regular output\n\n    -e, --expr \u003cexpr\u003e\n            A qualifying expression which modifies which events to trace or how to trace them.\n\n    -E, --env \u003cenv\u003e\n            --env var=val adds an environment variable. --env var removes an environment variable.\n\n    -f, --follow-forks\n            Trace child processes as they are created by currently traced processes.\n\n    -h, --help\n            Print help information\n\n    -j, --json\n            Display output in JSON format\n\n    -n, --syscall-number\n            Display system call numbers\n\n    -o, --file \u003cfile\u003e\n            Name of the file to print output to\n\n    -p, --attach \u003cattach\u003e\n            Attach to a running process\n\n    -s, --string-limit \u003cstring-limit\u003e\n            Maximum string size to print\n\n    -T, --syscall-times\n            Show the time spent in system calls in ms.\n\n    -u, --username \u003cusername\u003e\n            Run the command with uid, gid and supplementary groups of username.\n\n    -v, --no-abbrev\n            Print unabbreviated versions of strings\n\n    -V, --version\n            Print version information\n\n    -z, --successful-only\n            Print only syscalls that returned without an error code\n\n    -Z, --failed-only\n            Print only syscalls that returned with an error code\n```\n\n### Basic trace\n\nBasically, there are two ways of tracing system calls. You can either execute a\ncommand directly or attach to a running process by providing the process ID\n(PID) via `--attach`. In the latter case, the command has to be run with\nescalated privileges (`sudo`).\n\n#### Executing a command\n\n```\n$ lurk ls\n[54605] execve(\"\", \"\", \"\") = 0\n[54605] brk(NULL) = 0x55578000\n[54605] arch_prctl(12289, 0xffffe780) = -22\n[54605] access(\"\", 4) = -2\n[54605] openat(4294967196, \"/etc/ld.so.cache\", 524288) = 3\n[54605] newfstatat(3, \"\", 0xffffd9a0, 4096) = 0\n[54605] mmap(NULL, 92599, 1, 2, 3, 0) = 0xf7fa9000\n...\n```\n\n#### Attaching to a running process\n\n```\n$ sudo lurk --attach $PID\n[54683] epoll_wait(5, 0xd01a3c20, 8, 4294967295) = -4\n[54683] recvmsg(3, 0x4a4a0020, 0) = -11\n[54683] recvmsg(3, 0x4a4a0020, 0) = -11\n[54683] clock_gettime(1, 0x4a49df40) = 0\n[54683] clock_gettime(1, 0x4a4a0220) = 0\n[54683] recvmsg(3, 0x4a4a0050, 0) = -11\n...\n```\n\n### Filtering with `--expr`\n\nUnlike in `strace`, `lurk` only supports `--expr trace`. Since this flag\nbehaves almost exactly like in `strace`, here a short, slightly changed,\nexcerpt of the `strace`\n[manpage](https://man7.org/linux/man-pages/man1/strace.1.html) on how to use\n`lurk --expr trace`:\n\n```\n -e trace=syscall_set\n       --trace=syscall_set\n              Trace only the specified set of system calls.  syscall_set\n              is defined as [!]value[,value], and value can be one of\n              the following:\n\n              syscall\n                     Trace specific syscall, specified by its name (but\n                     see NOTES).\n\n              ?value Question mark before the syscall qualification\n                     allows suppression of error in case no syscalls\n                     matched the qualification provided.\n\n              /regex Trace only those system calls that match the regex.\n                     You can use POSIX Extended Regular Expression\n                     syntax (see regex(7)).\n\n              %file\n              file   Trace all system calls which take a file name as an\n                     argument.  You can think of this as an abbreviation\n                     for -e trace=open,stat,chmod,unlink,...  which is\n                     useful to seeing what files the process is\n                     referencing.  Furthermore, using the abbreviation\n                     will ensure that you don't accidentally forget to\n                     include a call like lstat(2) in the list.  Betchya\n                     woulda forgot that one.  The syntax without a\n                     preceding percent sign (\"-e trace=file\") is\n                     deprecated.\n\n              %process\n              process\n                     Trace system calls associated with process\n                     lifecycle (creation, exec, termination).  The\n                     syntax without a preceding percent sign (\"-e\n                     trace=process\") is deprecated.\n\n              %net\n              %network\n              network\n                     Trace all the network related system calls.  The\n                     syntax without a preceding percent sign (\"-e\n                     trace=network\") is deprecated.\n\n              %signal\n              signal Trace all signal related system calls.  The syntax\n                     without a preceding percent sign (\"-e\n                     trace=signal\") is deprecated.\n\n              %ipc\n              ipc    Trace all IPC related system calls.  The syntax\n                     without a preceding percent sign (\"-e trace=ipc\")\n                     is deprecated.\n\n              %desc\n              desc   Trace all file descriptor related system calls.\n                     The syntax without a preceding percent sign (\"-e\n                     trace=desc\") is deprecated.\n\n              %memory\n              memory Trace all memory mapping related system calls.  The\n                     syntax without a preceding percent sign (\"-e\n                     trace=memory\") is deprecated.\n\n              %creds Trace system calls that read or modify user and\n                     group identifiers or capability sets.\n\n              %stat  Trace stat syscall variants.\n\n              %lstat Trace lstat syscall variants.\n\n              %fstat Trace fstat, fstatat, and statx syscall variants.\n\n              %%stat Trace syscalls used for requesting file status\n                     (stat, lstat, fstat, fstatat, statx, and their\n                     variants).\n\n              %statfs\n                     Trace statfs, statfs64, statvfs, osf_statfs, and\n                     osf_statfs64 system calls.  The same effect can be\n                     achieved with -e trace=/^(.*_)?statv?fs regular\n                     expression.\n\n              %fstatfs\n                     Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs,\n                     and osf_fstatfs64 system calls.  The same effect\n                     can be achieved with -e trace=/fstatv?fs regular\n                     expression.\n\n              %%statfs\n                     Trace syscalls related to file system statistics\n                     (statfs-like, fstatfs-like, and ustat).  The same\n                     effect can be achieved with\n                     -e trace=/statv?fs|fsstat|ustat regular expression.\n\n              %clock Trace system calls that read or modify system\n                     clocks.\n\n              %pure  Trace syscalls that always succeed and have no\n                     arguments.  Currently, this list includes\n                     arc_gettls(2), getdtablesize(2), getegid(2),\n                     getegid32(2), geteuid(2), geteuid32(2), getgid(2),\n                     getgid32(2), getpagesize(2), getpgrp(2), getpid(2),\n                     getppid(2), get_thread_area(2) (on architectures\n                     other than x86), gettid(2), get_tls(2), getuid(2),\n                     getuid32(2), getxgid(2), getxpid(2), getxuid(2),\n                     kern_features(2), and metag_get_tls(2) syscalls.\n\n              The -c option is useful for determining which system calls\n              might be useful to trace.  For example,\n              trace=open,close,read,write means to only trace those four\n              system calls.  Be careful when making inferences about the\n              user/kernel boundary if only a subset of system calls are\n              being monitored.  The default is trace=all.\n\n```\n\n**Note**: When negating a statement with `!`, make sure to escape it (`\\!`)\nwhen using bash.\n\n#### Filtering for system calls not containing the letter `o`\n\n```\n$ lurk --expr trace=\\!/o ls\n[55155] execve(\"\", \"\", \"\") = 0\n[55155] brk(NULL) = 0x55578000\n[55155] arch_prctl(12289, 0xffffe780) = -22\n[55155] access(\"\", 4) = -2\n[55155] newfstatat(3, \"\", 0xffffd9a0, 4096) = 0\n[55155] mmap(NULL, 92599, 1, 2, 3, 0) = 0xf7fa9000\n[55155] read(3, \"\\u{7f}ELF\\u{2}\\u{1}\\u{1}\", 832) = 832\n...\n```\n\n#### Filtering only for all system calls taking a file as an argument\n\n```\n$ lurk --expr trace=%file ls\n[55121] access(\"\", 4) = -2\n[55121] openat(4294967196, \"/etc/ld.so.cache\", 524288) = 3\n[55121] newfstatat(3, \"\", 0xffffd9a0, 4096) = 0\n[55121] openat(4294967196, \"/usr/lib/libcap.so.2\", 524288) = 3\n[55121] newfstatat(3, \"\", 0xffffd9a0, 4096) = 0\n[55121] openat(4294967196, \"/usr/lib/libc.so.6\", 524288) = 3\n[55121] newfstatat(3, \"\", 0xffffd980, 4096) = 0\n...\n```\n\n#### Suppress error for `prctl` system call\n\n```\n$ lurk --expr trace=?prctl ls\n[55407] execve(\"\", \"\", \"\") = 0\n[55407] brk(NULL) = 0x55578000\n[55407] arch_prctl(12289, 0xffffe780) = -22\n[55407] access(\"\", 4) = -2\n[55407] openat(4294967196, \"/etc/ld.so.cache\", 524288) = 3\n[55407] newfstatat(3, \"\", 0xffffd9a0, 4096) = 0\n[55407] mmap(NULL, 92599, 1, 2, 3, 0) = 0xf7fa9000\n```\n\n#### Only output `openat`, `close` and `mmap` system calls\n\n```\n$ lurk --expr trace=openat,close,mmap ls\n[55440] openat(4294967196, \"/etc/ld.so.cache\", 524288) = 3\n[55440] mmap(NULL, 92599, 1, 2, 3, 0) = 0xf7fa9000\n[55440] close(3) = 0\n[55440] openat(4294967196, \"/usr/lib/libcap.so.2\", 524288) = 3\n[55440] mmap(NULL, 8192, 3, 34, 4294967295, 0) = 0xf7fa7000\n[55440] mmap(NULL, 45128, 1, 2050, 3, 0) = 0xf7f9b000\n[55440] mmap(0xf7f9e000, 20480, 5, 2066, 3, 12288) = 0xf7f9e000\n```\n\n#### Using as a Rust library\n\nSee the [tracer](examples/tracer.rs) example.\n\n## Acknowledgements\n\n- [sharkdp/fd](https://github.com/sharkdp/fd) as an inspiration on how to\n  structure a Rust CLI and its README.\n- All maintainers of the dependencies used to create lurk and all of those who\n  answered my questions regarding `ptrace`.\n\n## License\n\nlurk (c) 2022-2023 Jakob Waibel, Yuri Astrakhan, and contributors\n\nSPDX-License-Identifier: MIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJakWai01%2Flurk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJakWai01%2Flurk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJakWai01%2Flurk/lists"}