Unreal Engine Log Parser

Unreal Engine Log Parser is a Rust-based command-line tool designed to parse and filter Unreal Engine log files. It leverages the pest parser for efficient log parsing and clap for a user-friendly CLI interface.

https://crates.io/crates/unreal_log_parser

https://docs.rs/unreal_log_parser/latest/unreal_log_parser/

Features

• Parse Unreal Engine Logs: Extracts structured information from log files, including timestamps, frame numbers, categories, verbosity levels, and messages.
• Filter Logs: Allows filtering based on verbosity levels and specific log categories.
• Command-Line Interface: Easy-to-use commands for parsing logs and viewing credits.
• Error Handling: Robust error handling to manage invalid log entries and parsing issues.

Installation

Ensure you have Rust installed. Then, clone the repository and build the project:

git clone https://github.com/KyrylSydorov/unreal_log_parser.git
cd unreal_log_parser
cargo build --release

The executable will be available in the target/release directory.

Usage

unreal_log_parser [COMMAND]

Commands

help: Display the help message.

unreal_log_parser help

credits: Display the program credits.

unreal_log_parser credits

parse: Parse an Unreal Engine log file with optional filters.

unreal_log_parser parse -i <input_file> -o <output_file> [OPTIONS]

Options:

-i, --input <input_file>: Path to the input log file (required).

-o, --output <output_file>: Path to the output file (required).

-v, --verbosity : Verbosity level to include (e.g., Fatal, Error, Warning, Display, Log, Verbose, VeryVerbose).

-c, --category : Filter logs by a specific category.

Examples

Parse Logs with Verbosity Warning:

unreal_log_parser parse -i game.log -o warnings.log -v Warning

Parse Logs for a Specific Category:

unreal_log_parser parse -i game.log -o core_errors.log -c LogCore

Parse Logs with Verbosity and Category Filters:

unreal_log_parser parse -i game.log -o filtered.log -v Error -c LogAI

Grammar Specification

The Unreal Engine Log Parser utilizes a PEG (Parsing Expression Grammar) defined using the pest parser generator. Below is a detailed breakdown of the grammar rules used to parse Unreal Engine log files.

Overview

A typical Unreal Engine log line follows this structure:

[2024.04.27-12.34.56:789][  1]LogTemp: Warning: This is a warning message.

This line consists of:

1. Timestamp: [2024.04.27-12.34.56:789]
2. Frame Number: [ 1]
3. Category: LogTemp:
4. Verbosity: Warning:
5. Message: This is a warning message.

Grammar Rules

1. Whitespace and Newline

WHITESPACE: Defines what constitutes whitespace in the log file. It includes spaces, tabs, and newlines.

WHITESPACE = _{ " " | "\t" | NEWLINE }

NEWLINE: Recognizes both Unix (\n) and Windows (\r\n) newline characters.

NEWLINE = _{ "\n" | "\r\n" }

2. File Structure

file: Represents the entire log file. It starts at the beginning of the input (SOI) and consists of zero or more line entries, ending at the end of the input (EOI).

file = { SOI ~ line* ~ EOI }

3. Log Line Structure

line: Defines a single log entry. Each line may optionally start with a timestamp and frame_num, followed by mandatory category, optional verbosity, and the message. An optional newline may follow.

line = { timestamp? ~ frame_num? ~ category ~ verbosity? ~ message ~ NEWLINE? }

4. Timestamp Parsing

timestamp: Enclosed in square brackets, it contains the datetime.

timestamp = { "[" ~ datetime ~ "]" }

datetime: Breaks down the timestamp into its constituent parts: year, month, day, hour, minute, second, and millisecond.

datetime = { year ~ "." ~ month ~ "." ~ day ~ "-" ~ hour ~ "." ~ minute ~ "." ~ second ~ ":" ~ millisecond }

Individual Components:

year: Exactly four digits.

year = @{ ASCII_DIGIT{4} }

month, day, hour, minute, second: Exactly two digits each.

month = @{ ASCII_DIGIT{2} }
day = @{ ASCII_DIGIT{2} }
hour = @{ ASCII_DIGIT{2} }
minute = @{ ASCII_DIGIT{2} }
second = @{ ASCII_DIGIT{2} }

millisecond: Exactly three digits.

millisecond = @{ ASCII_DIGIT{3} }

5. Frame Number Parsing

frame_num: Enclosed in square brackets, it contains the frame_number.

frame_num = { "[" ~ frame_number ~ "]" }

frame_number: Consists of one or more digits, potentially followed by spaces or tabs. Leading and trailing whitespace is allowed.

frame_number = @{ ws? ~ ws? ~ ASCII_DIGIT+ }

Example Matches:

[1] → 1
[ 123 ] → 123
[1 2 3] → 123

6. Category Parsing

category: An identifier followed by a colon and optional whitespace.

category = { identifier ~ ":" ~ ws }

identifier: Consists of one or more alphanumeric characters, underscores, or forward slashes.

identifier = @{ (ASCII_ALPHANUMERIC | "_" | "/")+ }

Example Matches:

LogTemp:
LogRender:

7. Verbosity Parsing

verbosity: A predefined verbosity string followed by a colon and optional whitespace.

verbosity = { verbosity_str ~ ":" ~ ws }

verbosity_str: Enumerates the allowed verbosity levels.

verbosity_str = { "Verbose" | "VeryVerbose" | "Display" | "Log" | "Warning" | "Error" | "Fatal" }

Allowed Values:

• Verbose
• VeryVerbose
• Display
• Log
• Warning
• Error
• Fatal

8. Message Parsing message: Captures the rest of the line as the log message. It includes any character except for a newline.

Credits

Made by Kyryl Sydorov. Visit my GitHub.

License

This project is licensed under the MIT License.