Event Logger¶
consortium.framework._core.event_logging.event_logger.EventLogger(event_log, system_logger=None, mirror_to_logger=True)
¶
Public interface for recording structured events against a component's event log.
An event logger wraps an internal event log and exposes typed methods (success, failure, info, warning, error, artifact) for recording client-facing events, along with progress reporting (update_progress, clear_progress). Each recorded event is optionally mirrored to a system logger (loguru), so events surface both in the client-facing event log and in the server's log stream.
Framework components (agent tasks, listeners, agent generators, plugins, and event
hooks) each expose an event logger as self.event_logger for reporting their
activity. Related sub-components can share a single underlying event log through
create_child_logger so their events appear together in one consolidated log.
Wrap an event log and, optionally, a system logger to mirror entries to.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_log
|
EventLog
|
The underlying event log that recorded events are appended to. |
required |
system_logger
|
Any
|
Optional loguru logger that recorded events are mirrored to at the mapped severity level. If None, events are recorded to the event log only. |
None
|
mirror_to_logger
|
bool
|
Whether to mirror events to the system logger by default. Individual logging calls can override this per call via their own mirror_to_logger argument. |
True
|
mirror_to_logger = mirror_to_logger
instance-attribute
¶
subject_id
property
¶
current_progress
property
¶
The most recently reported progress update, if any.
Returns:
| Type | Description |
|---|---|
CurrentProgressModel | None
|
The most recently reported progress update, or None if none has been |
CurrentProgressModel | None
|
reported. |
total_count
property
¶
Total number of entries in the wrapped log.
Returns:
| Type | Description |
|---|---|
int
|
The total number of entries recorded in the wrapped event log. |
log_event(event_type, message, data=None, mirror_to_logger=None)
¶
Log an event of any type to the event log and optionally mirror it to the system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type
|
EventLogEntryType
|
The type of event to log. |
required |
message
|
str
|
Human-readable message to record. |
required |
data
|
dict[str, Any] | None
|
Optional structured data to include with the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
success(message, data=None, mirror_to_logger=None)
¶
Log a SUCCESS event to the event log and optionally mirror it to the system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable description of the successful action or result. |
required |
data
|
dict[str, Any] | None
|
Optional structured data to include with the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
failure(message, data=None, mirror_to_logger=None)
¶
Log a FAILURE event to the event log and optionally mirror it to the system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable description of the failure condition. |
required |
data
|
dict[str, Any] | None
|
Optional structured diagnostic data to include with the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
info(message, data=None, mirror_to_logger=None)
¶
Log an INFO event to the event log and optionally mirror it to the system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable informational message to record. |
required |
data
|
dict[str, Any] | None
|
Optional structured data to include with the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
warning(message, data=None, mirror_to_logger=None)
¶
Log a WARNING event to the event log and optionally mirror it to the system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable warning message to record. |
required |
data
|
dict[str, Any] | None
|
Optional structured data to include with the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
artifact(message, data=None, mirror_to_logger=None)
¶
Log an ARTIFACT event to the event log and optionally mirror it to the system logger.
Used to signal that a file, binary blob, or other collectible output was produced.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable description or filename of the artifact. |
required |
data
|
dict[str, Any] | None
|
Optional structured metadata to attach to the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
error(message, data=None, mirror_to_logger=None)
¶
Log an ERROR event to the event log and optionally mirror it to the system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error message to record. |
required |
data
|
dict[str, Any] | None
|
Optional structured data to include with the event. |
None
|
mirror_to_logger
|
bool | None
|
Overrides the instance default for this call. |
None
|
update_progress(percent_complete=0, message=None, data=None)
¶
Report a partial progress update on the event log.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
percent_complete
|
float
|
Completion percentage as a value from 0.0 to 100.0. |
0
|
message
|
str | None
|
Optional human-readable status message to accompany the update. |
None
|
data
|
dict[str, Any] | None
|
Optional structured data to include with the progress update. |
None
|
clear_progress()
¶
Clear the current progress update on the event log.
create_child_logger(system_logger=None, mirror_to_logger=None)
¶
Create a new event logger that shares this logger's underlying event log.
The returned logger writes into the same event log as this one, so entries recorded through either logger appear together in a single consolidated log. The child mirrors its entries to its own provided system logger, allowing sub-components (such as an agent generator's build steps) to report into one shared event log while still attributing their mirrored log lines to their own system logger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
system_logger
|
Any
|
System logger the child mirrors its entries to. If None, the child records to the shared event log without mirroring. |
None
|
mirror_to_logger
|
bool | None
|
Default mirroring behaviour for the child. If None, the parent's current default is inherited. |
None
|
Returns:
| Type | Description |
|---|---|
EventLogger
|
A new event logger backed by this logger's event log, mirroring to the |
EventLogger
|
provided system logger. |
get_events(limit=10, offset=None)
¶
Retrieve events from the event log.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit
|
int
|
Maximum number of event log entries to return. |
10
|
offset
|
int | None
|
Sequence offset to start from |
None
|
Returns:
| Type | Description |
|---|---|
list[EventLogEntryModel]
|
The selected window of event log entries, ordered by sequence. |
to_json(limit=10, offset=None, include_entries=True)
¶
Serialize the wrapped log to a JSON-compatible dict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit
|
int
|
Maximum number of entries to include. |
10
|
offset
|
int | None
|
Sequence offset to start from; see :class: |
None
|
include_entries
|
bool
|
When False, the entries list is omitted (serialized as an empty list) while current progress and total count are still reported. Used by collection endpoints to keep responses bounded regardless of how many resources they return. |
True
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A JSON-compatible dict with the current progress, total entry count, and |
dict[str, Any]
|
the selected window of entries. |