Dockstat - Docker Build Log Analyzer

A high-performance Rust CLI tool for parsing and analyzing Docker build logs, with support for multi-stage builds, multi-platform builds, and interactive TUI visualization.

Features

• Auto-detection of build types (normal, multi-stage, multi-platform, or combined)
• Multi-image build support - Automatically detects and analyzes multiple Docker images in one log
• Interactive TUI - Beautiful terminal dashboard with hierarchical navigation
• Multi-stage analysis - Dependency visualization and stage grouping
• Multi-platform support - Handles linux/amd64, linux/arm64, and other platforms
• Automatic log splitting - Organizes logs by image/platform/stage in logs/ directory
• Progress bars - Shows progress for large log files (>10MB)
• Flexible grouping - 5 different strategies for organizing multi-stage builds
• JSON export - Export parsed data for external processing
• Filtering - Filter by platform, stage name, or both
• Performance analysis - Identify slowest stages and bottlenecks

Quick Start

Installation

# Build the optimized release binary
cargo build --release

# Binary will be available at: ./target/release/dockstat

Run with Docker

You can also run Dockstat without installing Rust by using Docker:

# Build the image
docker build -t dockstat .

# Run analysis (mount your logs directory)
docker run --rm -v "$(pwd):/logs" dockstat /logs/docker.log

# Run interactive TUI (requires -it flags)
docker run --rm -it -v "$(pwd):/logs" dockstat /logs/docker.log --tui

Basic Usage

# Analyze a Docker build log
./target/release/dockstat docker.log

# Launch interactive TUI
./target/release/dockstat docker.log --tui

# Show comprehensive summary
./target/release/dockstat docker.log --summary

# Export to JSON
./target/release/dockstat docker.log --json analysis.json

# Show help and all options
./target/release/dockstat --help

Usage Examples

Interactive TUI Mode

# Launch the interactive terminal UI
dockstat docker.log --tui

Navigation Controls:

• Tab / Shift+Tab - Switch between panels (Images → Platforms → Stages → Steps → Logs)
• ↑ / ↓ or j / k - Navigate lists
• d / u - Scroll log viewer down/up (works from any panel)
• Mouse wheel—Scroll log viewer (works from any panel)
• q or Ctrl+C - Exit

Basic Analysis

# Auto-detects build type and shows appropriate output
dockstat docker.log

# The tool automatically detects:
# - Normal builds: Single-stage, single-platform
# - Multi-stage builds: Multiple named stages (builder, base, final)
# - Multi-platform builds: Multiple architectures (linux/amd64, linux/arm64)
# - Multi-image builds: Multiple Docker images in one log

Summary Mode

# Show comprehensive summary
dockstat docker.log --summary

# Summary includes:
# - Build type detection
# - Platform breakdown with stage counts and durations
# - Build stages with per-platform details
# - Stage dependencies
# - Top 5 longest running stages

Grouping Strategies

For multi-stage builds, you can organize the output using different grouping strategies:

# Chronological (default) - Shows stages in completion order
dockstat docker.log --group-by chronological

# Group by stage name
dockstat docker.log --group-by stage

# Group by platform
dockstat docker.log --group-by platform

# Group by stage, then platform (nested)
dockstat docker.log --group-by stage-platform

# Group by platform, then stage (nested)
dockstat docker.log --group-by platform-stage

Filtering

# Filter by platform
dockstat docker.log --platform linux/amd64
dockstat docker.log --platform linux/arm64

# Filter by stage name (for multi-stage builds)
dockstat docker.log --stage builder
dockstat docker.log --stage base

# Combine filters
dockstat docker.log --platform linux/amd64 --stage builder

# Use filters with summary
dockstat docker.log --platform linux/arm64 --summary
dockstat docker.log --stage builder --full-command

Listing Information

# List all platforms found in the log
dockstat docker.log --list-platforms

# Output shows:
# - Platform names (e.g., linux/amd64, linux/arm64)
# - Number of stages per platform
# - Total build time per platform

# List all build stages with dependencies
dockstat docker.log --list-stages

# Output shows:
# - Stage names with step counts and durations
# - Platforms for each stage (if multi-platform)
# - Commands used in each stage
# - Stage dependencies (e.g., "final → builder")

JSON Export

# Export parsed data to JSON file
dockstat docker.log --json analysis.json

# JSON includes:
# - All parsed stages with metadata
# - Image information (names, SHAs, push stages)
# - Platform and build stage details
# - Log file paths for each stage

Additional Options

# Show full commands in the report without truncation
dockstat docker.log --full-command

# Enable verbose output for debugging
dockstat docker.log --verbose

# This will show full commands and show summary for linux/amd64 builder stage
dockstat docker.log --platform linux/amd64 --stage builder --full-command --summary

Features Breakdown

Auto-Detection

The tool automatically detects the type of Docker build:

• Normal Build: Single-stage, single-platform

  • Shows a standard stage table with timing
  • Summary statistics with top 5 longest stages

• Multi-Stage Build: Multiple named stages (builder, base, final, etc.)

  • Detailed stage breakdown with dependencies
  • Per-stage duration and step counts
  • Command distribution analysis

• Multi-Platform Build: Multiple architectures (linux/amd64, linux/arm64, etc.)

  • Separate analysis per platform
  • Platform comparison views
  • Per-platform statistics

• Multi-Stage Multi-Platform: Combined complexity

  • Complete breakdown by stage and platform
  • Cross-platform stage comparison
  • Dependency visualization

• Multi-Image Build: Multiple Docker images in one log

  • Automatically detects image boundaries
  • Separate analysis for each image
  • Organized log output per image

Automatic Log Splitting

The tool automatically captures and organizes logs during parsing:

logs/
├── image1_20250117_abc123/
│   ├── linux_amd64_builder_1_1-6.log
│   ├── linux_amd64_builder_2_2-6.log
│   └── ...
└── image2_20250117_abc123/
    ├── linux_arm64_base_1_1-4.log
    └── ...

• Logs are split by image, platform, stage, and step
• Session ID includes timestamp and process ID
• Each step's log is stored separately for easy viewing
• Log paths are displayed at startup

Interactive TUI

The interactive terminal UI provides:

• Hierarchical navigation: Browse images → platforms → stages → steps
• Real-time log viewing: View individual step logs with scrolling
• Summary panel: Quick overview of selected image/platform
• Keyboard and mouse support: Full navigation with both input methods
• Responsive layout: Adapts to terminal size

Multi-Stage Analysis

Automatically detects and analyzes multi-stage Docker builds:

• Groups stages by build stage name
• Calculates total duration per stage
• Shows command distribution
• Identifies dependencies between stages (COPY --from=, FROM stage AS)
• Works with named stages (e.g., builder, base, final)

Performance Analysis

Identify build bottlenecks:

• Top 5 longest-running stages (shown in summary)
• Per-platform timing comparison
• Stage-by-stage duration breakdown
• Total build time calculation

CLI Reference

Required Arguments

Argument	Description
LOG_FILE	Path to the Docker build log file

Flags

Flag	Short	Description
--summary		Show comprehensive summary with top slowest stages
--tui		Launch interactive terminal UI
--list-platforms		List all platforms and exit
--list-stages		List all stages with dependencies and exit
--full-command		Show full commands without truncation
--verbose	-v	Enable debug output

Options

Option	Description	Example
--platform <PLATFORM>	Filter by specific platform	--platform linux/amd64
--stage <STAGE>	Filter by stage name	--stage builder
--group-by <MODE>	Grouping strategy	--group-by chronological
--json <FILE>	Export to JSON file	--json output.json

Grouping Modes

Mode	Description
chronological	Order stages by completion time (default)
stage	Group by stage name
platform	Group by platform
stage-platform	Group by stage, then platform
platform-stage	Group by platform, then stage

Development

Building

# Debug build (faster compilation, slower execution)
cargo build

# Release build (optimized, recommended)
cargo build --release

# The binary will be at: ./target/release/dockstat

Code Quality

# Run clippy linter
cargo clippy

# Format code
cargo fmt

# Check without building
cargo check

License

MIT