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.
AttachedOverflow: One entry’s attached lines outgrew the u32 offsets addressing them.
BridgeInfo: What a bridge() argument list says about the leg it is about to create.
CodecImpl: A codec implementation the engine reports it is running, as distinct from a CodecOffer read off the wire.
CodecOffer: One codec as FreeSWITCH spells it inside a negotiation trace’s brackets.
ConferenceMembership: A session’s membership in one conference.
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.
Field: A located byte range and what it holds.
FindUuids: Iterator returned by find_uuids.
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).
MediaCodecs: What one media type’s negotiation produced for a session.
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.
RenderedEntry: An entry’s text after a rewrite, one string per render unit.
SegmentTracker: Handle for looking up which segment a line number belongs to.
SessionMedia: Codecs a session negotiated, by media type and by direction.
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).
CodecMedia: Which negotiation trace a codec token came from.
CodecParseError: Why a codec token could not be read.
ConferenceVariable: mod_conference channel variable names (the part after the variable_ prefix).
DtmfSource: Source of a DTMF event log line.
FieldKind: What a located span holds.
FieldLocation: Which of an entry’s texts a range indexes.
HangupCause: Hangup cause from switch_cause_t (Q.850 + FreeSWITCH extensions).
LineKind: Classification of a single log line’s structural format.
LogLevel: FreeSWITCH log severity level.
MessageKind: Semantic classification of a log message’s content.
ParseWarning: A parsing anomaly, attached to the entry whose lines produced it.
RenderError: Why a rewrite could not be applied.
SdpDirection: Which end of a call an SDP body belongs to.
SessionReading: A per-session reading whose value its vocabulary did not know.
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.

Constants§

LOOPBACK_PEER_UUID_VARS: mod_loopback variables whose value is another leg’s UUID. Separate from PEER_UUID_VARS only because freeswitch-types gives them their own enum.
PEER_UUID_VARS: Channel variables whose value is, or contains, a peer leg’s UUID.

Traits§

VariableName: Trait for typed channel variable name enums.

Functions§

apply_fields: Rewrite the spans of one text, returning the result.
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.
decode_log_line: Decode one raw log line: strip the terminator, classify, lossy-recover.
find_uuids: Iterate the UUIDs embedded anywhere in text, yielding each match’s byte offset and slice. Matches never overlap.
for_each_peer_uuid: Call f with every peer-leg UUID entry mentions.
for_each_peer_uuid_with: Call f with every peer-leg UUID entry mentions, treating a variable as peer-bearing when it is in PEER_UUID_VARS or extra_var accepts its name.
is_peer_uuid_var: Whether name is one of PEER_UUID_VARS or LOOPBACK_PEER_UUID_VARS. Accepts the bare variable name; strip any variable_ prefix first.
is_uuid: Whether s is exactly one canonical UUID: 8-4-4-4-12 hex digits, either case.
log_rotation_stamp: The rotation stamp encoded in a freeswitch.log.* filename, or None for the active log and for any name that does not carry one.
message_fields: Locate the fields a message carries, as ranges into msg.
normalize_entry_timestamp: Rewrite a log entry’s YYYY-MM-DD HH:MM:SS.ffffff timestamp into the stamp form, dropping the sub-second part so it compares against a filename stamp.
parse_bridge_args: Extract origination_uuid and the bridge target channel from bridge() arguments. Uses BridgeDialString from freeswitch-types for correct parsing of [], {}, | failover, and , simultaneous ring syntax.
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.