linux_kernel_panic_parser/

lib.rs

//! Lossless parsing of Linux kernel panic logs, including incomplete excerpts.
//!
//! [`parse`] accepts any [`AsRef<str>`] input and owns its result. Unknown lines,
//! architecture-specific details, whitespace, and line endings are preserved.
//! [`PanicLog`]'s display output is byte-for-byte identical to its input, so
//! `parse(log.to_string()) == log` for every valid UTF-8 input.
//!
//! ```
//! use linux_kernel_panic_parser::{parse, LineKind};
//! let log = parse("[    1.250000] Kernel panic - not syncing: fatal exception\n");
//! assert_eq!(log.panic_messages().collect::<Vec<_>>(), ["fatal exception"]);
//! assert_eq!(parse(log.to_string()), log);
//! assert!(matches!(log.lines()[0].kind(), LineKind::Panic { .. }));
//! ```
//!
//! No architecture is inferred from the machine running this library. Register
//! names and hexadecimal addresses are retained as strings with no word-size
//! limit. Recognition is best effort: this is not a validator for every kernel
//! version or log transport. Syslog/journal wrappers remain raw text; uptime
//! extraction supports the usual leading printk/dmesg `[seconds.fraction]` form
//! and `[unix_seconds][seconds.fraction]` pairs.

#![forbid(unsafe_code)]
#![warn(missing_docs)]

use jiff::{SignedDuration, Timestamp};
use std::{convert::Infallible, fmt, str::FromStr};
use winnow::{
    Parser,
    ascii::{digit1, space0, space1},
    combinator::{alt, opt, preceded},
    error::ModalResult,
    token::{take_till, take_while},
};

/// An owned, lossless log. It may contain zero, one, or multiple panics.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PanicLog {
    lines: Vec<LogLine>,
}

impl PanicLog {
    /// Parse UTF-8 text, including ordinary messages and incomplete excerpts.
    pub fn parse(input: impl AsRef<str>) -> Self {
        parse(input)
    }

    /// Lines in their original order, including blank lines.
    pub fn lines(&self) -> &[LogLine] {
        &self.lines
    }

    /// Recognized panic messages, in their original order.
    pub fn panic_messages(&self) -> impl Iterator<Item = &str> {
        self.lines.iter().filter_map(|line| match &line.kind {
            LineKind::Panic { message } => Some(message.as_str()),
            _ => None,
        })
    }

    /// Whether a `Kernel panic - not syncing:` marker was found.
    pub fn has_panic(&self) -> bool {
        self.panic_messages().next().is_some()
    }
}

impl fmt::Display for PanicLog {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for line in &self.lines {
            f.write_str(&line.raw)?;
        }
        Ok(())
    }
}

impl FromStr for PanicLog {
    type Err = Infallible;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(parse(s))
    }
}

/// One line, including its original terminator (LF, CRLF, CR, or none).
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct LogLine {
    raw: String,
    message: String,
    uptime: Option<SignedDuration>,
    timestamp: Option<Timestamp>,
    kind: LineKind,
}

impl LogLine {
    /// Original line, including its terminator.
    pub fn as_str(&self) -> &str {
        &self.raw
    }
    /// Content after recognized leading priority, wall-clock, and uptime prefixes, without
    /// its terminator. Unrecognized prefixes remain part of the message.
    pub fn message(&self) -> &str {
        &self.message
    }
    /// Elapsed time since boot, when a representable dmesg timestamp is present.
    pub fn uptime(&self) -> Option<SignedDuration> {
        self.uptime
    }
    /// Wall-clock instant from a leading `[unix_seconds][uptime]` prefix.
    pub fn timestamp(&self) -> Option<Timestamp> {
        self.timestamp
    }
    /// Best-effort structured interpretation of the message.
    pub fn kind(&self) -> &LineKind {
        &self.kind
    }
}

impl fmt::Display for LogLine {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.raw)
    }
}

/// Recognized architecture-independent records. Unrecognized records are kept.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum LineKind {
    /// A terminal kernel panic marker.
    Panic {
        /// Reason following the panic marker.
        message: String,
    },
    /// CPU and task metadata, with the remaining kernel description retained.
    Cpu {
        /// Logical CPU identifier.
        cpu: u64,
        /// User identifier, when included by the kernel.
        uid: Option<u64>,
        /// Task identifier.
        pid: u64,
        /// Command name and remaining metadata (names can contain spaces).
        details: String,
    },
    /// A named faulting symbol, such as `RIP: 0010:function+0x1/0x20`.
    Symbol {
        /// Architecture-specific label or register name.
        label: String,
        /// Optional segment selector, preserved as hexadecimal text.
        segment: Option<String>,
        /// Symbol, offset, and size.
        frame: StackFrame,
    },
    /// A diagnostic or machine description with a known label.
    Diagnostic {
        /// Label, for example `Oops`, `BUG`, `Hardware name`, or `Code`.
        label: String,
        /// Full details after the label, without semantic interpretation.
        details: String,
    },
    /// Loaded modules, including a wrapped continuation line.
    Modules {
        /// Module names with any attached taint annotations, in order.
        modules: Vec<String>,
        /// Last unloaded module, if reported.
        last_unloaded: Option<String>,
        /// Whether this line continues a preceding module list.
        continuation: bool,
    },
    /// An announced reboot delay.
    Reboot {
        /// Delay before rebooting.
        delay: SignedDuration,
    },
    /// A call-trace section heading.
    CallTrace,
    /// A symbol with hexadecimal offset and size, optionally with an address.
    Frame(StackFrame),
    /// Register or page-table entry/value pairs without architecture restrictions.
    Registers(Vec<Register>),
    /// A line without a recognized structured interpretation.
    Unknown,
}

/// A stack symbol. Textual numbers preserve padding and support any word size.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct StackFrame {
    /// Optional bracketed address, without brackets or angle brackets.
    pub address: Option<String>,
    /// Whether the kernel marked the symbol with `?`.
    pub uncertain: bool,
    /// Symbol name.
    pub symbol: String,
    /// Hexadecimal offset, including `0x`.
    pub offset: String,
    /// Hexadecimal symbol size, including `0x`.
    pub size: String,
    /// Remaining text, for example a module name or architecture annotation.
    pub suffix: String,
}

/// A register value retained without integer-width assumptions.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Register {
    /// Register name as printed by the kernel.
    pub name: String,
    /// Value as printed, including any segment selector or parenthesized flags.
    pub value: String,
}

/// Parse any borrowed or owned string-like input into an owned log.
///
/// Accepts `&str`, `String`, `&String`, `Box<str>`, `Cow<str>`, and other
/// [`AsRef<str>`] types. Parsing never rejects unknown or truncated records.
/// Empty input yields no lines. Only valid UTF-8 is accepted by this API.
pub fn parse(input: impl AsRef<str>) -> PanicLog {
    let mut input = input.as_ref();
    let mut lines = Vec::new();
    let mut in_modules = false;
    while !input.is_empty() {
        // This grammar consumes at least one character, including blank lines.
        let remaining = input;
        let raw = match raw_line.parse_next(&mut input) {
            Ok(raw) => raw,
            Err(_) => {
                // Preserve all remaining text even if the line grammar changes
                // to reject some input in the future.
                input = "";
                remaining
            }
        };
        let content = raw.trim_end_matches(['\r', '\n']);
        let mut body = content;
        if let Ok(rest) = priority.parse_next(&mut body) {
            body = rest;
        } else {
            body = content;
        }
        let wall_clock = wall_clock_prefix.parse_next(&mut &*body).ok();
        let wall_timestamp = wall_clock.map(|(instant, rest)| {
            body = rest;
            instant
        });
        let before_time = body;
        let uptime = match timestamp.parse_next(&mut body) {
            Ok(time) => Some(time),
            Err(_) => {
                body = before_time;
                None
            }
        };
        let mut kind = classify(body);
        if in_modules
            && matches!(kind, LineKind::Unknown)
            && let Ok(value) = module_list(true).parse(body.trim())
        {
            kind = value;
        }
        in_modules = matches!(kind, LineKind::Modules { .. });
        lines.push(LogLine {
            raw: raw.to_owned(),
            message: body.to_owned(),
            uptime,
            timestamp: wall_timestamp,
            kind,
        });
    }
    PanicLog { lines }
}

fn raw_line<'a>(input: &mut &'a str) -> ModalResult<&'a str> {
    (take_till(0.., ['\r', '\n']), opt(alt(("\r\n", "\n", "\r"))))
        .take()
        .parse_next(input)
}

fn priority<'a>(input: &mut &'a str) -> ModalResult<&'a str> {
    (
        "<",
        take_while(1.., |c: char| c.is_ascii_digit()),
        ">",
        space0,
    )
        .parse_next(input)?;
    Ok(*input)
}

fn timestamp(input: &mut &str) -> ModalResult<SignedDuration> {
    let (_, _, seconds, fraction, _, _) = (
        "[",
        space0,
        digit1,
        opt((".", take_while(1..=9, |c: char| c.is_ascii_digit()))),
        "]",
        space0,
    )
        .parse_next(input)?;
    let seconds = seconds
        .parse::<i64>()
        .map_err(|_| winnow::error::ErrMode::Backtrack(winnow::error::ContextError::new()))?;
    let nanos = fraction.map_or(0, |(_, digits)| {
        // The grammar limits this to at most nine ASCII digits, so the
        // accumulated value and its nanosecond scaling fit in i32.
        digits
            .bytes()
            .fold(0_i32, |value, digit| value * 10 + i32::from(digit - b'0'))
            * 10_i32.pow(9 - digits.len() as u32)
    });
    Ok(SignedDuration::new(seconds, nanos))
}

fn wall_clock_prefix<'a>(input: &mut &'a str) -> ModalResult<(Timestamp, &'a str)> {
    let (_, seconds, _) = ("[", digit1, "]").parse_next(input)?;
    let instant = seconds
        .parse::<i64>()
        .ok()
        .and_then(|s| Timestamp::from_second(s).ok())
        .ok_or_else(|| winnow::error::ErrMode::Backtrack(winnow::error::ContextError::new()))?;
    // Only interpret the first bracket as wall time when followed by a valid
    // uptime. A single [seconds] bracket remains a normal dmesg prefix.
    timestamp.parse_next(&mut &**input)?;
    Ok((instant, *input))
}

fn cpu(input: &mut &str) -> ModalResult<LineKind> {
    let (_, cpu, _, uid, _, pid, _, _) = (
        "CPU:",
        preceded(space0, digit1),
        space1,
        opt(("UID:", preceded(space0, digit1), space1)),
        "PID:",
        preceded(space0, digit1),
        space1,
        "Comm:",
    )
        .parse_next(input)?;
    let number = |s: &str| {
        s.parse::<u64>()
            .map_err(|_| winnow::error::ErrMode::Backtrack(winnow::error::ContextError::new()))
    };
    Ok(LineKind::Cpu {
        cpu: number(cpu)?,
        uid: uid.map(|(_, value, _)| number(value)).transpose()?,
        pid: number(pid)?,
        details: input.trim_start().to_owned(),
    })
}

fn hex<'a>(input: &mut &'a str) -> ModalResult<&'a str> {
    ("0x", take_while(1.., |c: char| c.is_ascii_hexdigit()))
        .take()
        .parse_next(input)
}

fn frame(input: &mut &str) -> ModalResult<StackFrame> {
    space0.parse_next(input)?;
    let address = opt((
        "[<",
        take_while(1.., |c: char| c.is_ascii_hexdigit()),
        ">]",
        space0,
    ))
    .parse_next(input)?;
    let uncertain = opt(("?", space0)).parse_next(input)?.is_some();
    let (symbol, _, offset, _, size) = (
        take_while(1.., |c: char| !c.is_whitespace() && c != '+'),
        "+",
        hex,
        "/",
        hex,
    )
        .parse_next(input)?;
    // Reject partial sizes such as 0x10garbage while allowing module suffixes.
    if input.chars().next().is_some_and(|c| !c.is_whitespace()) {
        return Err(winnow::error::ErrMode::Backtrack(
            winnow::error::ContextError::new(),
        ));
    }
    Ok(StackFrame {
        address: address.map(|(_, value, _, _)| value.to_owned()),
        uncertain,
        symbol: symbol.to_owned(),
        offset: offset.to_owned(),
        size: size.to_owned(),
        suffix: input.trim_start().to_owned(),
    })
}

fn register_value<'a>(input: &mut &'a str) -> ModalResult<&'a str> {
    (
        opt("0x"),
        take_while(1.., |c: char| c.is_ascii_hexdigit()),
        opt((
            ":",
            opt("0x"),
            take_while(1.., |c: char| c.is_ascii_hexdigit()),
        )),
        opt(("(", take_while(1.., |c: char| c.is_ascii_hexdigit()), ")")),
    )
        .take()
        .parse_next(input)
}

fn named_symbol(input: &mut &str) -> ModalResult<LineKind> {
    let (label, _, _) = (
        take_while(1.., |c: char| c.is_ascii_alphanumeric() || c == '_'),
        ":",
        space0,
    )
        .parse_next(input)?;
    let segment = opt((take_while(1.., |c: char| c.is_ascii_hexdigit()), ":")).parse_next(input)?;
    Ok(LineKind::Symbol {
        label: label.to_owned(),
        segment: segment.map(|(s, _)| s.to_owned()),
        frame: frame.parse_next(input)?,
    })
}

fn module_list(continuation: bool) -> impl FnMut(&mut &str) -> ModalResult<LineKind> {
    move |input| {
        let mut modules = Vec::new();
        let mut last_unloaded = None;
        while !input.is_empty() {
            if input.starts_with("[last unloaded:") {
                let (_, _, name, _, _) = (
                    "[last unloaded:",
                    space0,
                    take_while(1.., |c: char| {
                        c.is_ascii_alphanumeric() || "_-+.".contains(c)
                    }),
                    "]",
                    space0,
                )
                    .parse_next(input)?;
                last_unloaded = Some(name.to_owned());
                break;
            }
            let (name, separator) = (
                (
                    take_while(1.., |c: char| {
                        c.is_ascii_alphanumeric() || "_-+.".contains(c)
                    }),
                    opt(("(", take_while(1.., |c: char| c.is_ascii_alphabetic()), ")")),
                )
                    .take(),
                space0,
            )
                .parse_next(input)?;
            if separator.is_empty() && !input.is_empty() {
                return Err(winnow::error::ErrMode::Backtrack(
                    winnow::error::ContextError::new(),
                ));
            }
            modules.push(name.to_owned());
        }
        if continuation && modules.is_empty() && last_unloaded.is_none() {
            return Err(winnow::error::ErrMode::Backtrack(
                winnow::error::ContextError::new(),
            ));
        }
        Ok(LineKind::Modules {
            modules,
            last_unloaded,
            continuation,
        })
    }
}

fn reboot(input: &mut &str) -> ModalResult<LineKind> {
    let (_, seconds, _, _) =
        ("Rebooting in ", digit1, " seconds", alt(("..", ".", ""))).parse_next(input)?;
    let seconds = seconds
        .parse::<i64>()
        .map_err(|_| winnow::error::ErrMode::Backtrack(winnow::error::ContextError::new()))?;
    Ok(LineKind::Reboot {
        delay: SignedDuration::from_secs(seconds),
    })
}

fn registers(input: &mut &str) -> ModalResult<Vec<Register>> {
    let mut values = Vec::new();
    while !input.is_empty() {
        let (name, _, value, separator) = (
            take_while(1.., |c: char| c.is_ascii_alphanumeric() || c == '_'),
            alt((preceded(":", space0), space1)),
            register_value,
            space0,
        )
            .parse_next(input)?;
        if separator.is_empty() && !input.is_empty() {
            return Err(winnow::error::ErrMode::Backtrack(
                winnow::error::ContextError::new(),
            ));
        }
        values.push(Register {
            name: name.to_owned(),
            value: value.to_owned(),
        });
    }
    if values.is_empty() {
        return Err(winnow::error::ErrMode::Backtrack(
            winnow::error::ContextError::new(),
        ));
    }
    Ok(values)
}

fn classify(body: &str) -> LineKind {
    let body = body.trim();
    // Searching also recognizes panic markers inside syslog/journal wrappers.
    if let Some((_, message)) = body.split_once("Kernel panic - not syncing:") {
        return LineKind::Panic {
            message: message.trim_start().to_owned(),
        };
    }
    if matches!(
        body,
        "Call Trace:" | "Call trace:" | "Backtrace:" | "Stack backtrace:"
    ) {
        return LineKind::CallTrace;
    }
    if let Ok(value) = cpu.parse_next(&mut &*body) {
        return value;
    }
    if let Ok(value) = named_symbol.parse_next(&mut &*body) {
        return value;
    }
    if let Some(modules) = body.strip_prefix("Modules linked in:")
        && let Ok(value) = module_list(false).parse(modules.trim())
    {
        return value;
    }
    if let Ok(value) = reboot.parse(body) {
        return value;
    }
    for label in [
        "Oops",
        "BUG",
        "#PF",
        "Tainted",
        "Hardware name",
        "Workqueue",
        "Code",
        "Kernel Offset",
    ] {
        if let Some(details) = body
            .strip_prefix(label)
            .and_then(|rest| rest.strip_prefix(':'))
        {
            return LineKind::Diagnostic {
                label: label.to_owned(),
                details: details.trim_start().to_owned(),
            };
        }
    }
    if let Ok(value) = frame.parse_next(&mut &*body) {
        return LineKind::Frame(value);
    }
    if let Ok(value) = registers.parse(body) {
        return LineKind::Registers(value);
    }
    LineKind::Unknown
}