.TH "" "" "" "" "" .SS NAME .PP sysdig \- the definitive system and process troubleshooting tool .SS SYNOPSIS .PP \f[B]sysdig\f[] [\f[I]option\f[]]... [\f[I]filter\f[]] .SS DESCRIPTION .PP sysdig is a tool for system troubleshooting, analysis and exploration. It can be used to capture, filter and decode system calls and other OS events. .PD 0 .P .PD sysdig can be both used to inspect live systems, or to generate trace files that can be analyzed at a later stage. .PP sysdig includes a powerul filtering language, has customizable output, and can be extended through Lua scripts, called chisels. .PP \f[B]Output format\f[] .PP By default, sysdig prints the information for each captured event on a single line, with the following format: .PP \f[C]\ \ \ \ \ \ \ \f[] .PP where: .IP \[bu] 2 evt.num is the incremental event number .PD 0 .P .PD .IP \[bu] 2 evt.time is the event timestamp .PD 0 .P .PD .IP \[bu] 2 evt.cpu is the CPU number where the event was captured .PD 0 .P .PD .IP \[bu] 2 proc.name is the name of the process that generated the event .PD 0 .P .PD .IP \[bu] 2 thread.tid id the TID that generated the event, which corresponds to the PID for single thread processes .PD 0 .P .PD .IP \[bu] 2 evt.dir is the event direction, > for enter events and < for exit events .PD 0 .P .PD .IP \[bu] 2 evt.type is the name of the event, e.g. \[aq]open\[aq] or \[aq]read\[aq] .PD 0 .P .PD .IP \[bu] 2 evt.args is the list of event arguments. .PP The output format can be customized with the \-p switch, using any of the fields listed by \[aq]sysdig \-l\[aq]. .PP \f[B]Trace Files\f[] .PP A trace file can be created using the \-w switch: .RS .PP $ sysdig \-w trace.scap .RE .PP The \-s switch can be used to specify how many bytes of each data buffer should be saved to disk. And filters can be .PD 0 .P .PD used to save only certain events to disk: .RS .PP $ sysdig \-s 2000 \-w trace.scap proc.name=cat .RE .PP Trace files can be read this using the \-r switch: .RS .PP $ sysdig \-r trace.scap .RE .PP \f[B]Filtering\f[] .PP sysdig filters are specified at the end of the command line. The simplest filter is a basic field\-value check: .RS .PP $ sysdig proc.name=cat .RE .PP The list of available fields can be obtained with \[aq]sysdig \-l\[aq]. .PD 0 .P .PD Filter expressions can use one of these comparison operators: \f[I]=\f[], \f[I]!=\f[], \f[I]<\f[], \f[I]<=\f[], \f[I]>\f[], \f[I]>=\f[] and \f[I]contains\f[]. e.g. .RS .PP $ sysdig fd.name contains /etc .RE .PP Multiple checks can be combined through brakets and the following boolean operators: \f[I]and\f[], \f[I]or\f[], \f[I]not\f[]. e.g. .RS .PP $ sysdig "not (fd.name contains /proc or fd.name contains /dev)" .RE .PP \f[B]Chisels\f[] .PP sysdig\[aq]s chisels are little scripts that analyze the sysdig event stream to perform useful actions. .PD 0 .P .PD To get the list of available chisels, type .RS .PP $ sysdig \-cl .RE .PP To get details about a specific chisel, type .RS .PP $ sysdig \-i spy_ip .RE .PP To run one of the chisels, you use the \-c flag, e.g. .RS .PP $ sysdig \-c topfiles_bytes .RE .PP If a chisel needs arguments, you specify them after the chisel name: .RS .PP $ sysdig \-c spy_ip 192.168.1.157 .RE .PP If a chisel has more than one argument, specify them after the chisel name, enclosed in quotes: .RS .PP $ sysdig \-c chisel_name "arg1 arg2 arg3" .RE .PP Chisels can be combined with filters: .RS .PP $ sysdig \-c topfiles_bytes "not fd.name contains /dev" .RE .SS OPTIONS .PP \f[B]\-A\f[], \f[B]\-\-print\-ascii\f[] .PD 0 .P .PD Only print the text portion of data buffers, and echo end\-of\-lines. This is useful to only display human\-readable data. .PP \f[B]\-b\f[], \f[B]\-\-print\-base64\f[] .PD 0 .P .PD Print data buffers in base64. This is useful for encoding binary data that needs to be used over media designed to handle textual data (i.e., terminal or json). .PP \f[B]\-c\f[] \f[I]chiselname\f[] \f[I]chiselargs\f[], \f[B]\-\-chisel\f[]=\f[I]chiselname\f[] \f[I]chiselargs\f[] .PD 0 .P .PD run the specified chisel. If the chisel require arguments, they must be specified in the command line after the name. .PP \f[B]\-cl\f[], \f[B]\-\-list\-chisels\f[] .PD 0 .P .PD lists the available chisels. Looks for chisels in ., ./chisels, ~/.chisels and /usr/share/sysdig/chisels. .PP \f[B]\-d\f[], \f[B]\-\-displayflt\f[] .PD 0 .P .PD Make the given filter a display one. Setting this option causes the events to be filtered after being parsed by the state system. Events are normally filtered before being analyzed, which is more efficient, but can cause state (e.g. FD names) to be lost. .PP \f[B]\-D\f[], \f[B]\-\-debug\f[] .PD 0 .P .PD Capture events about sysdig itself .PP \f[B]\-F\f[], \f[B]\-\-fatfile\f[] .PD 0 .P .PD Enable fatfile mode. When writing in fatfile mode, the output file will contain events that will be invisible when reading the file, but that are necessary to fully reconstruct the state. Fatfile mode is useful when saving events to disk with an aggressive filter. The filter could drop events that would the state to be updated (e.g. clone() or open()). With fatfile mode, those events are still saved to file, but \[aq]hidden\[aq] so that they won\[aq]t appear when reading the file. Be aware that using this flag might generate substantially bigger traces files. .PP \f[B]\-h\f[], \f[B]\-\-help\f[] .PD 0 .P .PD Print this page .PP \f[B]\-j\f[], \f[B]\-\-json\f[] .PD 0 .P .PD Emit output as json, data buffer encoding will depend from the print format selected. .PP \f[B]\-i \f[I]chiselname\f[]\f[], \f[B]\-\-chisel\-info=\f[]\f[I]chiselname\f[] .PD 0 .P .PD Get a longer description and the arguments associated with a chisel found in the \-cl option list. .PP \f[B]\-L\f[], \f[B]\-\-list\-events\f[] .PD 0 .P .PD List the events that the engine supports .PP \f[B]\-l\f[], \f[B]\-\-list\f[] .PD 0 .P .PD List the fields that can be used for filtering and output formatting. Use \-lv to get additional information for each field. .PP \f[B]\-n\f[] \f[I]num\f[], \f[B]\-\-numevents\f[]=\f[I]num\f[] .PD 0 .P .PD Stop capturing after \f[I]num\f[] events .PP \f[B]\-P\f[], \f[B]\-\-progress\f[] .PD 0 .P .PD Print progress on stderr while processing trace files. .PP \f[B]\-p\f[] \f[I]outputformat\f[], \f[B]\-\-print\f[]=\f[I]outputformat\f[] .PD 0 .P .PD Specify the format to be used when printing the events. See the examples section below for more info. .PP \f[B]\-q\f[], \f[B]\-\-quiet\f[] .PD 0 .P .PD Don\[aq]t print events on the screen. Useful when dumping to disk. .PP \f[B]\-r\f[] \f[I]readfile\f[], \f[B]\-\-read\f[]=\f[I]readfile\f[] .PD 0 .P .PD Read the events from \f[I]readfile\f[]. .PP \f[B]\-S\f[], \f[B]\-\-summary\f[] .PD 0 .P .PD print the event summary (i.e. the list of the top events) when the capture ends. .PP \f[B]\-s\f[] \f[I]len\f[], \f[B]\-\-snaplen\f[]=\f[I]len\f[] .PD 0 .P .PD Capture the first \f[I]len\f[] 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. .PP \f[B]\-t\f[] \f[I]timetype\f[], \f[B]\-\-timetype\f[]=\f[I]timetype\f[] .PD 0 .P .PD Change the way event time is displayed. Accepted values are \f[B]h\f[] for human\-readable string, \f[B]a\f[] for absolute timestamp from epoch, \f[B]r\f[] for relative time from the beginning of the capture, \f[B]d\f[] for delta between event enter and exit, and \f[B]D\f[] for delta from the previous event. .PP \f[B]\-v\f[], \f[B]\-\-verbose\f[] .PD 0 .P .PD Verbose output. .PP \f[B]\-\-version\f[] .PD 0 .P .PD Print version number. .PP \f[B]\-w\f[] \f[I]writefile\f[], \f[B]\-\-write\f[]=\f[I]writefile\f[] .PD 0 .P .PD Write the captured events to \f[I]writefile\f[]. .PP \f[B]\-x\f[], \f[B]\-\-print\-hex\f[] .PD 0 .P .PD Print data buffers in hex. .PP \f[B]\-X\f[], \f[B]\-\-print\-hex\-ascii\f[] .PD 0 .P .PD Print data buffers in hex and ASCII. .PP \f[B]\-z\f[], \f[B]\-\-compress\f[] .PD 0 .P .PD Used with \f[B]\-w\f[], enables compression for tracefiles. .SS EXAMPLES .PP Capture all the events from the live system and print them to screen .RS .PP $ sysdig .RE .PP Capture all the events from the live system and save them to disk .RS .PP $ sysdig \-w dumpfile.scap .RE .PP Read events from a file and print them to screen .RS .PP $ sysdig \-r dumpfile.scap .RE .PP Print all the open system calls invoked by cat .RS .PP $ sysdig proc.name=cat and evt.type=open .RE .PP Print the name of the files opened by cat .RS .PP $ sysdig \-p"%evt.arg.name" proc.name=cat and evt.type=open .RE .PP List the available chisels .RS .PP $ sysdig \-cl .RE .PP Use the spy_ip chisel to look at the data exchanged with 192.168.1.157: .RS .PP $ sysdig \-c spy_ip 192.168.1.157 .RE .SS FILES .PP \f[I]/usr/share/sysdig/chisels\f[] .PD 0 .P .PD The global chisels directory. .PP \f[I]~/.chisels\f[] .PD 0 .P .PD The personal chisels directory. .SS BUGS .IP \[bu] 2 sysdig and its chisels are designed to be used with LuaJIT in Lua 5.1 mode. While it is possible to use sysdig with LuaJIT in Lua 5.2 mode or regular Lua, some chisels may not work as expected. .SS AUTHOR .PP Draios inc. .SS SEE ALSO .PP \f[B]strace\f[](8), \f[B]tcpdump\f[](8), \f[B]lsof\f[](8)