Skip to content

Latest commit

 

History

History
109 lines (82 loc) · 3.93 KB

README.md

File metadata and controls

109 lines (82 loc) · 3.93 KB
Raw

kata-log-parser

Introduction

kata-log-parser is a tool that combines logfiles generated by the various system components, sorts them by timestamp, and re-displays the log entries. A time delta is added to show how much time has elapsed between each log entry.

The tool is also able to check the validity of all log records, can re-format the logs, and output them in a different format.

For more information on the kata-log-parser tool, use the help command:

$ kata-log-parser --help

Logfile requirements

The tool reads logfiles in the logfmt structured logging format. For example, a logfile created by the golang Logrus package.

By default the tool requires that the following fields are defined for each log record:

  • Log level field (level): must be one of the Logrus LogLevel values in string format (e.g. debug, info, error).

  • Name field (name): a single word that specifies the name of the application that generates the log record (e.g. kata-runtime).

  • Process ID field (pid): the numeric process identifier for the process that generates the log record.

  • Source field (source): a single word that specifies the name of a unique part of the system (e.g. runtime).

  • Timestamp field (time): in RFC3339 format and including a nanosecond value.

Additional to the fields above, the tool also expects the following field:

  • Message field (msg): a textual message allowing log records to be disambiguated.

Note: These requirements can be ignored by using the --ignore-missing-fields flag

Component logfiles

The primary logfiles the tool reads are:

  • The runtime log.

    This log also includes virtcontainers log entries and agent best effort logs unpacking (unless --no-agent-unpack is specified).

Usage

To merge all logs:

  1. Enable full debug.
  2. Clear the systemd journal (optional): 
    $ sudo systemctl stop systemd-journald
$ sudo rm -f /var/log/journal/*/* /run/log/journal/*/*
$ sudo systemctl start systemd-journald
  3. Create a Kata container.
  4. Collect the logs (alternatively to journal clearing you may consider constraining collected logs by adding --since=<container creation time>). 
    $ sudo journalctl -q -o cat -a -t kata > ./kata.log
  5. Ensure the logs are readable: 
    $ sudo chown $USER *.log
  6. To install the program: 
    $ go get -d github.com/kata-containers/kata-containers
$ pushd $GOPATH/src/github.com/kata-containers/kata-containers/src/tools/log-parser && make install && popd
  7. To run the program: 
    $ kata-log-parser kata.log

Advanced processing using jq

jq is a command-line JSON processor which can be combined with kata-log-parser to filter and fetch specific log entries.

Examples

Get only the raw guest console output
$ kata-log-parser --ignore-missing-fields --output-format json --no-agent-unpack kata.log | jq '.Entries[] | select(.Msg=="reading guest console") | .Data.vmconsole'
Get only the agent's unpacked log entries

This example also demonstrates how to get logs from the journal directly to the parser.

$ journalctl -q -o cat -a -t kata | kata-log-parser --ignore-missing-fields --output-format json - | jq '.Entries[] | select(.Source=="agent")'
Get only certain Sandbox ID logs

These logs sourced from containerd-kata-shim-v2 and being printed along with their Msg content, Time and Container ID.

$ kata-log-parser --ignore-missing-fields --output-format json kata.log  | jq '.Entries[] | select(.Source=="containerd-kata-shim-v2" and .Sandbox=="2fa50251ccc3b9a85350e8fe6836d1875023714153b503b548360946fcec3829") | "\(.Msg) \(.Time) \(.Container)"'