---
# System prepended metadata

title: JSON Progress Output for OSBuild

---

# JSON Progress Output for OSBuild

## Problem

When running osbuild with `--json`, the output of the entire job is collected and printed after completion (or failure) of the build as a single JSON.  This makes it difficult to know what osbuild is doing during a build and impossible for osbuild-composer to track the progress or status of a build.

## Proposal

Make osbuild emit machine-readable messages during a build that describe the task that's being executed or that just finished executing.

## Ideas

### Basic info

The following information should be contained in each log message printed by the new osbuild logger:
- Current pipeline name
- Current pipeline ID
- Current stage name
- Current stage ID
- Message output from the current (or finished) stage

### Extra info

It would be useful to osbuild-composer if the following information was also included:
- Number of current pipeline
- Number of current stage in the pipeline
- Start time and duration of current pipeline
- Start time and duration of current stage

### Example output (from very quick POC implementation)

```json
{
  "pipeline": {
    "name": "build",
    "id": "cd93456be1ecb4a3e63f2aba6058fb888409b4d3dd8f6c7aa9db5c1232b0719c",
    "stage": {
      "name": "org.osbuild.rpm",
      "id": "d9dcc18c694447ee3ed3ce213ef3ac7ee380f578368e466a19953307932d780b",
      "message": "Failed to open file \"/sys/fs/selinux/checkreqprot\": Read-only file system\n"
    }
  },
  "progress": {
    "start_time": 1632507101.9176896,
    "duration": 0.18395209312438965,
    "pipeline": 1,
    "stage": 1
  }
}
```

## Variations

### Stage output formatting

Messages printed from stages are usually the raw output of the command being run from the stage.  Stages (usually) "shell-out" to run commands and log/print the output of those commands.  Stages rarely process that output except to determine whether a command has failed and why.  We could also edit stages to make them print machine-readable output about the tasks they are running and their status.

Examples (some of these might not be possible):
- `org.osbuild.rpm`:
  - print the name (and metadata) of a package once it's installed
  - print the number and total count of packages being installed (progress counter)
  - print the current state of the RPM process (installing, running scriptlets, cleanup)
- `org.osbuild.tar`: progressive file list
- `org.osbuild.ostree.pull`

### Clock-based vs event-based logging

A new status message could be printed on a fixed frequency (e.g., `1/s`) instead of whenever a new message is emitted from a stage.  Currently, stages print messages to `stdout`, which is captured by osbuild and passed through to the log writer.  When running with the standard logger (`LogMonitor`; no `--json`), these messages are printed immediately.

A JSON progress output logger could either:
1. Print a new complete log object that contains the new message.
2. Collect all messages for a single stage and print one log object per stage with all its output in the messages.
3. Collect messages and print them at a fixed frequency.  In this case, we might still want to print a log line when a stage is done independent of (or resetting) the timer.
