schrodinger.seam.logapi module¶

API for inspecting log files from a Beam pipeline executed with the SeamRunner.

Example usage:

from schrodinger.seam.logapi import LogInspector

with LogInspector('/path/to/seam_dir') as log_inspector:
    transform_names = log_inspector.getTransformNames()
    counts = log_inspector.getCountsPerTransform('MyTransform')
    events = log_inspector.getTransformLogEvents('MyTransform', only_level=logging.ERROR)

Text search¶

getTransformLogEvents supports a search_term parameter for full-text search on application log messages. For file-based logging system, this performs a substring match on log messages across worker application log files.

Examples:

# Exact term search — finds messages containing "FileNotFoundError"
events = inspector.getTransformLogEvents(search_term="FileNotFoundError")

# Prefix search — finds messages with words starting with "warn"
# (e.g. "warning", "warns")
events = inspector.getTransformLogEvents(search_term="warn*")

# Combined with other filters
events = inspector.getTransformLogEvents(
    'MyTransform', only_level=logging.ERROR, search_term="timeout")

NOTE: Search is case-insensitive across both file and DB backends. In the DB backend, the FTS5 tokenizer treats -_./:\@# as token characters, so paths like /usr/local/bin are indexed as a single token. To match partial paths, use prefix search (e.g. "/usr*").

class schrodinger.seam.logapi.LogInspector(seam_dir: str | pathlib.Path | schrodinger.seam.runners._seamdir.SeamDir)¶

Bases: object

LOG_PAGE_SIZE = 500¶

__init__(seam_dir: str | pathlib.Path | schrodinger.seam.runners._seamdir.SeamDir)¶

getTransformNames() → set[str]¶: Get the names of all transforms, both parent and leaf transforms.

getCountsPerTransform(transform_name: str = '') → Counter¶

Get the counts of log messages per log level for a given transform.

Parameters:: transform_name – The name of a transform to get counts for. If not specified, counts for all transforms will be returned.
Returns:: A Counter mapping log levels to counts.

getRunnerLogEvents(only_level: Optional[int] = None, min_level: Optional[int] = None, page: int = 0) → list[dict]¶

Get log events generated by the Beam runner itself, not by user transforms, for a given page.

If min_level is specified, only events at or above min_level will be returned. If only_level is specified, only events with that exact level will be returned. If min_level is not specified, it defaults to logging.DEBUG. If only_level is not specified, all levels will be returned.

getRunnerLogLevelCounts() → Counter¶: Get the counts of log messages per log level for logs generated by the SeamRunner.

getTransformLogEvents(transform_name: str = '', only_level: Optional[int] = None, min_level: Optional[int] = None, search_term: str = '', page: int = 0) → list[dict]¶

Get log events for a specific transform, optionally filtered by log level for a given page.

Events are ordered by stage, then worker, then timestamp.

If min_level is specified, only events at or above min_level will be returned. If only_level is specified, only events with that exact level will be returned. If min_level is not specified, it defaults to logging.DEBUG. If only_level is not specified, all levels will be returned. If transform_name is not specified, events for all transforms will be returned. If search_term is specified, only events whose message contains the search term will be returned. If the search term ends with ‘*’, it will be treated as a prefix search. (e.g. “warn*” will match messages containing words that start with “warn”)

getContextualLogEvents(log_event: dict, transform_name: str = '', min_level: Optional[int] = None, only_level: Optional[int] = None) → list[dict]¶

Get log events surrounding a specific log event for a given transform.

See getTransformLogEvents for details on the parameters.

close()¶: Close resources on the backend.