Skip to content

Python API

Jump to bottom
sat edited this page Jun 26, 2026 · 1 revision

Python API

The public surface of log2seq. This page is the reference; for how the pieces fit together see Building a Parser.

Top level (import log2seq)

Name Kind Summary
LogParser class the parser; binds header rules to a statement parser
init_parser function build the default parser, or override one stage
KEY_TIMESTAMP str result key 'timestamp'
KEY_STATEMENT str result key 'message'
KEY_WORDS str result key 'words'
KEY_SYMBOLS str result key 'symbols'
ParserDefinitionError exception raised while building a parser
LogParseFailure exception raised while parsing a line
__version__ str e.g. '0.4.0'

LogParser(header_parsers, statement_parser, ignore_failure=False)

  • header_parsers — a HeaderParser or a list of them (tried in order, first match wins).
  • statement_parser — a StatementParser.
  • ignore_failure — if True, process_line returns None instead of raising on an unparsable line.

Methods:

  • process_line(line, verbose=False) -> dict | None — run both stages.
  • process_header(line, verbose=False) -> dict — header stage only.
  • process_statement(message) -> (words, symbols) — statement stage only.

init_parser(header_parsers=None, statement_parser=None) -> LogParser

With no arguments, identical to preset.default(). Pass one argument to keep the default for the other stage — e.g. init_parser(header_parsers=[my_hp]) reuses the default statement parser.

The result dict

process_line returns a plain dict:

  • Always present: 'timestamp', 'message', 'words', 'symbols' (the KEY_* constants above). len(symbols) == len(words) + 1.
  • Header fields are named by the rule: an item named host adds a 'host' key; there is no fixed host constant. Timestamp-component items are folded into 'timestamp'.
  • An optional item that did not match is omitted — the key is absent, not None. Test with key in result.

Exceptions

  • ParserDefinitionError — a parser was built incorrectly (e.g. a rule with no Statement, or a malformed item pattern). Raised at construction time.
  • LogParseFailure — a line matched no header rule (or a stage failed) and ignore_failure is False. Carries the offending line in its message.
import log2seq
try:
    d = log2seq.init_parser().process_line("not a log line")
except log2seq.LogParseFailure as e:
    ...

Submodules

  • log2seq.header — HeaderParser and the Item classes (Date, Time, MonthAbbreviation, Digit, Hostname, String, UserItem, ItemGroup, Statement, UnixTime, TimeZone, …). Defines __all__, so from log2seq.header import * brings only these public names — not the stdlib modules it uses. See Header Rules.
  • log2seq.statement — StatementParser and the Action classes (Split, Fix, FixIP, FixParenthesis, FixPartial, Remove, RemovePartial, ConditionalSplit). Also defines __all__. See Statement Rules.
  • log2seq.preset — ready-made parsers: default(), init-equivalent default_header_parsers() / default_statement_parser(), and apache_errorlog_parser(). See Presets.

See also

Clone this wiki locally