Crate freeswitch_log_parser

Expand description

Parser for FreeSWITCH log files.

Handles the full complexity of mod_logfile output: five distinct line formats, multi-line CHANNEL_DATA and SDP dumps, truncated buffer collisions, and per-session state tracking — no regex, a single dependency (freeswitch-types).

§Architecture

The parser is organized in three composable layers, each wrapping the previous:

Layer 1 (parse_line) — stateless, zero-allocation single-line classifier
Layer 2 (LogStream) — structural state machine that groups continuations, classifies messages, and detects multi-line blocks
Layer 3 (SessionTracker) — per-UUID state machine that propagates dialplan context, channel state, and variables across entries; extensible via SessionTracker::with_pre_hook and SessionTracker::with_post_hook for custom leg detection

See docs/design-rationale.md in the repository for the parsing strategy and why each layer exists; the line-format anatomy lives in the repository’s CLAUDE.md.

§Examples

Read lines from stdin, process through all three layers, and print enriched entries:

use std::io;
use freeswitch_log_parser::{read_log_lines, LogStream, SessionTracker};

// read_log_lines tolerates mod_logfile's truncated codepoints; the strict
// BufRead::lines() reader would panic on them.
let lines = read_log_lines(io::stdin().lock()).map(|d| d.expect("read error").text);
let stream = LogStream::new(lines);
let mut tracker = SessionTracker::new(stream);

for enriched in tracker.by_ref() {
    let e = &enriched.entry;
    println!("{} [{}] {}", e.timestamp, e.message_kind, e.message);
}

let stats = tracker.stats();
eprintln!("{} lines, {} unclassified",
    stats.lines_processed, stats.lines_unclassified);

§Feature flags

cli — enables the fslog binary with clap, xz decompression, and regex filtering

Structs§

AttachedLines: Compact storage for the raw continuation lines of a log entry.
AttachedLinesIter: Iterator over the lines of an AttachedLines.
DecodedLine: A decoded log line plus the UTF-8 verdict for its bytes.
EnrichedEntry: A LogEntry paired with the session’s state snapshot at that point in time.
LogEntry: A complete parsed log entry with all context resolved.
LogStream: Layer 2 structural state machine — groups continuation lines, classifies messages, and detects multi-line blocks (CHANNEL_DATA, SDP, codec negotiation).
ParseLevelError: Returned when a string doesn’t match any known log level.
ParseStats: Cumulative parsing statistics, updated as lines flow through the stream.
RawLine: Zero-copy result of parsing a single log line.
SegmentTracker: Handle for looking up which segment a line number belongs to.
SessionSnapshot: Immutable point-in-time copy of a session’s state, attached to each EnrichedEntry.
SessionState: Mutable per-UUID state accumulator, updated as entries are processed.
SessionTracker: Layer 3 per-session state machine — tracks per-UUID state (dialplan context, channel state, variables) across entries and yields EnrichedEntry values.
TrackedChain: Iterator that concatenates named segments and tracks which line number each segment starts at. Pair with SegmentTracker to look up which segment a given line belongs to.
UnclassifiedLine: Record of a single unclassified line, captured when tracking is enabled.

Enums§

Block: Structured data extracted from a multi-line dump that follows a primary log entry.
CallDirection: Call direction from the Call-Direction header. Wire format is lowercase.
CallState: Call state from switch_channel_callstate_t – carried in the Channel-Call-State header.
ChannelState: Channel state from switch_channel_state_t – carried in the Channel-State header as a string (CS_ROUTING) and in Channel-State-Number as an integer.
ChannelVariable: Core FreeSWITCH channel variable names (the part after the variable_ prefix).
DtmfSource: Source of a DTMF event log line.
LineKind: Classification of a single log line’s structural format.
LogLevel: FreeSWITCH log severity level.
MessageKind: Semantic classification of a log message’s content.
SdpDirection: Which end of a call an SDP body belongs to.
SipInviteDirection: Direction of a sofia SIP INVITE log line.
SofiaVariable: mod_sofia / SIP channel variable names (the part after the variable_ prefix).
UnclassifiedReason: Why a line was marked as unclassified.
UnclassifiedTracking: Controls how much detail is recorded for lines that couldn’t be fully classified.
Utf8Decode: Outcome of classifying a line’s bytes as UTF-8.

Functions§

classify_message: Classify a log message’s text into a MessageKind.
classify_utf8: Classify a line’s bytes as UTF-8, distinguishing a truncated codepoint (benign) from a genuinely invalid byte (corruption). Pure; no I/O.
parse_line: Layer 1 entry point: classify a single line and extract its fields.
read_log_lines: Read newline-delimited log lines, decoding each with the truncated-codepoint case typed distinctly from corruption.
truncate_at_char_boundary: Largest prefix of s at most max_bytes long that ends on a char boundary.