# `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`](https://brandur.org/logfmt) structured
logging format. For example, a logfile created by the golang
[Logrus](https://godoc.org/github.com/sirupsen/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](https://tools.ietf.org/html/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](../../runtime) log.

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

## Usage

To merge all logs:

1. [Enable full debug](../../../docs/Developer-Guide.md#enable-full-debug).
1. Clear the systemd journal (optional):
   ```
   $ sudo systemctl stop systemd-journald
   $ sudo rm -f /var/log/journal/*/* /run/log/journal/*/*
   $ sudo systemctl start systemd-journald   
   ```
1. Create a Kata container.
1. 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
   ```
1. Ensure the logs are readable:
   ```
   $ sudo chown $USER *.log
   ```
1. 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
   ```
1. To run the program:
   ```
   $ kata-log-parser kata.log
   ```

### Advanced processing using jq

[jq](https://stedolan.github.io/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)"'
```