CSYSDIG(8)

📦
version 0.41.4 · 7 versions
, in arch rolling

💅 NAME

okay so bestie, meet csysdig — it's the ncurses user interface for sysdig, and yes that's the whole vibe. section 8 of the manual, icon behavior only.

✨ SYNOPSIS

csysdig [option]...  [filter]

🦋 DESCRIPTION

csysdig takes everything sysdig can do and serves it through an ncurses-based user interface that is, genuinely, intuitive AND powerful. not a combo you see every day, i fear.

the whole design goal is "mimic tools like top and htop" — but lowkey it does way more, including:

  • Support for both live analysis and sysdig trace files. Trace files can come from the same machine or from another machine. 🫶
  • Visibility into a broad range of metrics, including CPU, memory, disk I/O, network I/O. the full buffet.
  • Ability to observe input/output activity for processes, files, network connections and more.
  • Ability to drill down into processes, files, network connections and more to further explore their behavior. it's giving detective era 🔍
  • Full customization support.
  • Support for sysdig's filtering language.
  • Container support by design. no cap.

csysdig works on any terminal, and has support for colors and mouse input. periodt.

🎀 Views

csysdig is built on the concept of 'views' — little Lua scripts that determine how metrics are collected, processed and represented on screen. the slay part? adding a whole new visualization to csysdig doesn't require updating the program at all, it's simply a matter of adding a new view. Views rely on the sysdig processing engine, which means they can include any sysdig filter field. Views live in the sysdig chisel directory path, usually /usr/share/sysdig/chisels and ~/.chisels.

🌸 BASIC USAGE

here are some basic tips to get you started with sysdig (and by extension, your new main character):

  1. If you run csysdig without arguments, it will display live system data, updating every 2 seconds. To analyze a trace file, use the -r command line flag.
  2. You can switch to a different view by using the F2 key.
  3. You can drill down into a selection by clicking enter. You can navigate back by typing backspace.
  4. You can observe input/output for the currently selected entity by typing F5
  5. You can see sysdig events for the currently selected entity by typing F6

🔥 DRILLING DOWN

okay so this is the fun part. you drill down by selecting an element in a view and then clicking enter. once you're inside a selection, you can switch to a different view, and — plot twist — the new view gets applied in the context of the selection. for example, if you drill down into a process called foo and then switch to the Connections view, the output will include only the connections made or received by foo. iconic behavior honestly.

to drill down multiple times, keep clicking enter. for example, you can click on a container in the Containers view to get the processes running inside it, and then click on one of the processes to see its threads. it's layers, bestie. 🧅

⭐ ACTIONS AND HOTKEYS

Each view has a list of command lines that can be executed in the context of the current selection by pressing 'hotkeys'. for example, pressing k in the Processes view kills the selected process, pressing b in the Containers view opens a bash shell in the selected container. yes, really.

Each view supports different actions. you can see which actions a view supports by pressing F8. and you can customize the view's actions by editing the view's Lua file. go off. ✨

🍓 CONTAINERS SUPPORT

Starting csysdig with the -pc command line switch will cause many of the views to include additional container information. for example, the Processes will include a column showing the container the process belongs to. similarly, the Connections view will show which container each connection belongs to. container girlies stay winning.

💜 INTERACTIVE COMMANDS

🖥️ Views Window

  • Arrows, PgUP, PgDn, Home, End — Change the selection and scroll view content, both vertically and horizontally.
  • Enter — Drill down into the currently highlighted entry.
  • Backspace — Navigate back to the previous view.
  • F2 — Show the view picker. This will let you switch to another view.
  • **CTRL+F / ** — Incremental search in the list of view entries.
  • F4 — Incremental filtering of the view entries.
  • F5, e — 'echo FDs' for the selection, i.e. view FD input/output for the currently highlighted entry.
  • F6, d — 'dig' into the selection, i.e. view sysdig events for the currently highlighted entry. Refer to the sysdig man page to learn about interpreting the content of this window.
  • F7 — Show the help page for the currently displayed view.
  • F8 — Open the view's actions panel.
  • F9, > — Open the column sort panel.
  • F10, q — Quit. say bye 👋
  • DEL, c — For views that are listing elements without aggregating them by key (identifiable by yellow column headers), this command clears the view content.
  • p — Pause screen updates.
  • <shift> <1-9> — sort column <n>
  • F1, h, ? — Show the help screen.

🧚 Echo and sysdig Windows

  • Arrows, PgUP, PgDn, Home, End — Scroll the page content.
  • Backspace — Navigate back to the previous view.
  • **CTRL+F / ** — Search inside the window content.
  • F3 — Find Next.
  • F2 — Chose the output rendering format. Options are 'Dotted ASCII' (non-printable binary bytes are rendered as dots), 'Printable ASCII' (non-printable binary bytes are not included and line endings are rendered accurately) and 'Hex' (dotted ASCII representation is included together with the Hexadecimal rendering of the buffers).
  • DEL, c — Clear the screen content.
  • p — Pause screen updates.
  • CTRL+G — Go to line.

🌈 Spectrogram Window

  • F2 — Show the view picker. This will let you switch to another view.
  • p — Pause/Resume the visualization.
  • Backspace — Navigate back to the previous view.

🐭 MOUSE USAGE

  • Clicking on column headers lets you sort the table.
  • Double clicking on row entries performs a drill down.
  • Clicking on the filter string at the top of the screen (the text after 'Filter:') lets you change the sysdig filter and customize the view content.
  • You can use the mouse on the entries in the menu at the bottom of the screen to perform their respective actions.

mouse girlies, this one's for you 🫶

👑 COMMAND LINE OPTIONS

  • -d period, --delay=period — Set the delay between updates, in milliseconds (by default = 2000). This works similarly to the -d option in top.
  • -E, --exclude-users — Don't create the user/group tables by querying the OS when sysdig starts. This also means that no user or group info will be written to the tracefile by the -w flag. The user/group tables are necessary to use filter fields like user.name or group.name. However, creating them can increase sysdig's startup time.
  • --force-term-compat — Try to configure simple terminal settings (xterm-1002) that work better with terminals like putty. Try to use this flag if you experience terminal issues like the mouse not working. (putty girlies, this is your moment)
  • -h, --help — Print this page
  • -k, --k8s-api — Enable Kubernetes support by connecting to the API server specified as argument. E.g. "http://admin:password@127.0.0.1:8080". The API server can also be specified via the environment variable SYSDIG_K8S_API.
  • **-K btfile | certfile:keyfile[#password][:cacertfile], --k8s-api-cert=_btfile | certfile:keyfile[#password][:cacertfile]_ — Use the provided files names to authenticate user and (optionally) verify the K8S API server identity. Each entry must specify full (absolute, or relative to the current directory) path to the respective file. Private key password is optional (needed only if key is password protected). CA certificate is optional. For all files, only PEM file format is supported. Specifying CA certificate only is obsoleted — when single entry is provided for this option, it will be interpreted as the name of a file containing bearer token. Note that the format of this command-line option prohibits use of files whose names contain ':' or '#' characters in the file name. Option can also be provided via the environment variable SYSDIG_K8S_API_CERT.
  • -l, --list — List all the fields that can be used in views.
  • --logfile file — Print program logs into the given file.
  • **-m url[,marathon-url], --mesos-api=_url[,marathon-url]_ — Enable Mesos support by connecting to the API server specified as argument (e.g. http://admin:password@127.0.0.1:5050). Mesos url is required. Marathon url is optional, defaulting to auto-follow — if Marathon API server is not provided, csysdig will attempt to retrieve (and subsequently follow, if it migrates) the location of Marathon API server from the Mesos master. Note that, with auto-follow, csysdig will likely receive a cluster internal IP address for Marathon API server, so running csysdig with Marathon auto-follow from a node that is not part of Mesos cluster may not work. Additionally, running csysdig with Mesos support on a node that has no containers managed by Mesos is of limited use because, although cluster metadata will be collected, there will be no Mesos/Marathon filtering capability. The API servers can also be specified via the environment variable SYSDIG_MESOS_API.
  • -n num, --numevents=num — Stop capturing after num events
  • --page-faults — Capture user/kernel major/minor page faults
  • -pc, -pcontainers — Instruct csysdig to use a container-friendly format in its views. This will cause several of the views to contain additional container-related columns.
  • -R, --resolve-ports — Resolve port numbers to names.
  • -r readfile, --read=readfile — Read the events from readfile.
  • -s len, --snaplen=len — Capture the first len bytes of each I/O buffer. By default, the first 80 bytes are captured. Use this option with caution, it can generate huge trace files.
  • -T, --force-tracers-capture — Tell the driver to make sure full buffers are captured from /dev/null, to make sure that tracers are completely captured. Note that sysdig will enable extended /dev/null capture by itself after detecting that tracers are written there, but that could result in the truncation of some tracers at the beginning of the capture. This option allows preventing that.
  • -v view_id, --views=view_id — Run the view with the given ID when csysdig starts. View IDs can be found in the view documentation pages in csysdig. Combine this option with a command line filter for complete output customization.
  • --version — Print version number.

🔍 FILTERING

Similarly to what you do with sysdig, you can specify a filter on the command line to restrict the events that csysdig processes. to modify the filter while the program is running, or to add a filter at runtime, click on the filter text in the UI with the mouse. yup, that's it. 💅

✨ CUSTOMIZING CSYSDIG ✨

Okay bestie, this is the part where it gets good. csysdig is completely customizable, which means you can literally go in and modify any of the csysdig views — and yes, you can absolutely cook up your own views from scratch too. No cap. 👑

So here's the tea: just like sysdig chisels, csysdig views are Lua scripts. That's the whole vibe. 💅

The full rundown lives at this github wiki page, and you're gonna want to bookmark it:

https://github.com/draios/sysdig/wiki/csysdig-View-Format-Reference

🎀 FILES 🎀

  • /usr/share/sysdig/chisels — the global views directory. This is where the shared, everybody-gets-these views hang out. 🌍
  • ~/.chisels — the personal views directory. Your own private stash, just for you. 🫶

👑 AUTHOR 👑

Draios Inc. (dba Sysdig) — info@sysdig.com 💌

🌈 SEE ALSO 🌈

sysdig(8), strace(8), tcpdump(8), lsof(8)

✨ and that's the whole page, bestie ✨ — the source/version and date on this one are literally just () (iconic minimalism, honestly 🎀), so consider this your official cute sign-off. Now go forth and customize some views, you absolute legend. 💖🦋🌸

📦 where this page comes from