Events¶

Info

For event log usage, see Event Log.

The client records an event log of resolutions, mutations, and notices that happen in-between requests for complex queries and other operations. Typically, such events are things like CNAME and PTR resolution that happen when resolving Host or host records.

The client exposes its event log via client.events (an EventLog). The size of the log is controlled by the event_log_size argument to MregClient.

EventLog ¶

Append-only event log with querying and optional subscriber callbacks.

When max_size is set, the oldest event is evicted when the limit is reached so memory use stays bounded.

init ¶

__init__(max_size: int | None = 100) -> None

Initialise the log with an optional maximum size.

len ¶

__len__() -> int

Return the number of recorded events.

repr ¶

__repr__() -> str

Return a developer-readable representation.

clear ¶

clear() -> None

Remove all recorded events.

get ¶

get(
    subject: ObjectRef | None = None,
    kind: EventKind | None = None,
    level: EventLevel | None = None,
    min_level: EventLevel | None = None,
    where: Callable[[Event], bool] | None = None,
) -> list[Event]

Return all recorded events, optionally filtered by subject, kind, or level.

Multiple filters can be applied at once, and only events matching all provided filters will be returned.

More complex filtering can be done by providing a callable to the where parameter, which will be called with each event record, and should return True if it should be included in the results.

Parameters:

Name	Type	Description	Default
`subject`	`ObjectRef \| None`	If given, return only events where this object is the subject or involved.	`None`
`kind`	`EventKind \| None`	If given, return only events of this kind.	`None`
`level`	`EventLevel \| None`	If given, return only events with exactly this level.	`None`
`min_level`	`EventLevel \| None`	If given, return only events with this level or higher.	`None`
`where`	`Callable[[Event], bool] \| None`	A predicate function that returns True if the event should be included.	`None`

Returns:

Type	Description
`list[Event]`	A list of events matching the specified filters.

get_all ¶

get_all() -> list[Event]

Return all recorded events.

get_at_or_above ¶

get_at_or_above(level: EventLevel) -> list[Event]

Return all events at or above the given severity level.

get_by_kind ¶

get_by_kind(kind: EventKind) -> list[Event]

Return all events of the given kind.

get_by_level ¶

get_by_level(level: EventLevel) -> list[Event]

Return all events with exactly the given level.

get_for ¶

get_for(ref: ObjectRef) -> list[Event]

Return all events where ref is the subject or an involved object.

record ¶

record(event: Event) -> None

Record an event, evicting the oldest entry if max_size is reached.

Calls all registered handlers with the new event as the argument.

subscribe ¶

subscribe(handler: EventHandler) -> None

Register a callback invoked for every new event.

unsubscribe ¶

unsubscribe(handler: EventHandler) -> None

Remove a previously registered callback.

Event `dataclass` ¶

Structured record of something that happened to or around an MREG API object.

correlation_id `class-attribute` `instance-attribute` ¶

correlation_id: str = ''

Client correlation ID active at the time the event was emitted.

level `class-attribute` `instance-attribute` ¶

level: EventLevel = EventLevel.INFO

Primary object this event concerns.

message `instance-attribute` ¶

message: str

Human-readable description of the event.

related `class-attribute` `instance-attribute` ¶

related: tuple[ObjectRef, ...] = ()

Other objects involved in the event.

EventKind ¶

Bases: StrEnum

Classification of an event.

MUTATION `class-attribute` `instance-attribute` ¶

MUTATION = 'mutation'

Object was created, patched, or deleted.

NOTICE `class-attribute` `instance-attribute` ¶

NOTICE = 'notice'

General informational event.

RESOLUTION `class-attribute` `instance-attribute` ¶

RESOLUTION = 'resolution'

Object found via an alias or redirect (e.g. CNAME, PTR override).

TRUNCATION `class-attribute` `instance-attribute` ¶

TRUNCATION = 'truncation'

A query matched more objects than the limit allowed; the extra results were dropped.

EventLevel ¶

Bases: IntEnum

Severity level of an event.

Handlers can use this to filter which events to react to.

ObjectRef `dataclass` ¶

Lightweight reference to an MREG API object, used for event correlation.

type is the model class name (e.g. "Host", "MX"). value is always a string. Field values are converted to strings. field is the specific field within the object that the value pertains to.

str ¶

__str__() -> str

Return a human-readable representation of the reference.

new `classmethod` ¶

new(obj: MregModel) -> Self

Create a reference to an API object.

Uses the object's endpoint to determine the ID field to use.

Cannot fail. Logs and defaults to str(obj) for value on failure.

Events¶

EventLog ¶

__init__ ¶

__len__ ¶

__repr__ ¶