or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/python-libmaas@0.6.x

docs

reference

bcache.mdblock-devices.mdbones.mdboot-resources.mdcli.mdconnection.mdcontrollers.mddevices.mdenums.mdevents.mdfiles.mdfilesystems.mdinterfaces.mdmachines.mdnetwork.mdpartitions.mdpods.mdraids.mdresources.mdsystem.mdusers.mdutilities.mdviscera.mdvolume-groups.md
index.md
tile.json

tessl/pypi-python-libmaas

tessl install tessl/pypi-python-libmaas@0.6.0

Python client library for MAAS 2.0+ with sync/async support, providing machine provisioning, network management, and storage configuration.

events.mddocs/reference/

Event Monitoring

Query and monitor system events for auditing, debugging, and tracking MAAS operations.

Capabilities

Querying Events

Retrieve events with filtering and pagination. The Events API provides a paginated interface for browsing through historical events.

client.events.query(**filters)

Filter parameters:

  • hostnames (list[str], optional): Filter by hostnames (can specify multiple)
  • domains (list[str], optional): Filter by domain names
  • zones (list[str], optional): Filter by zone names
  • macs (list[str], optional): Filter by MAC addresses
  • system_ids (list[str], optional): Filter by machine system IDs
  • agent_name (str, optional): Filter by agent name
  • level (EventLevel | int | str, optional): Filter by event level (use EventLevel enum)
  • owner (User | str, optional): Filter by owner username or User object
  • limit (int, optional): Maximum number of events to return per page
  • before (int, optional): Return events with ID before this value (for pagination)
  • after (int, optional): Return events with ID after this value (for pagination)

Note: You can specify either before or after for pagination, but not both.

from maas.client import connect
from maas.client.viscera.events import Level

client = connect('http://maas.example.com:5240/MAAS/', apikey='key')

# Query all events
events = client.events.query()
for event in events:
    print(f"{event.created}: {event.description}")

# Query events for specific machines (note: plural parameter name)
events = client.events.query(hostnames=['node1.maas', 'node2.maas'])

# Query events by system IDs
events = client.events.query(system_ids=['abc123', 'def456'])

# Query by level (use Level enum from events module)
events = client.events.query(level=Level.ERROR)

# Query by multiple criteria
events = client.events.query(
    zones=['production'],
    level=Level.WARNING,
    limit=100
)

# Query with pagination - get next page
events = client.events.query(limit=50)
next_events = await events.next()  # Get next 50 events

# Query with pagination - get previous page
prev_events = await events.prev()  # Get previous 50 events

# Query events by owner
events = client.events.query(owner='admin')

# Query events by MAC addresses
events = client.events.query(macs=['00:11:22:33:44:55'])

Event Object Structure

Event objects returned by the query have the following properties:

  • event_id (int, readonly): Unique event identifier (maps to API field 'id')
  • event_type (str, readonly): Event type description (maps to API field 'type')
  • system_id (str, readonly): Associated node system ID (maps to API field 'node')
  • hostname (str, readonly): Associated hostname
  • level (Level, readonly): Event level enum (AUDIT, DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • created (datetime, readonly): Timestamp when event occurred (UTC timezone-aware)
  • description (str, readonly): Full event description
  • description_short (str, readonly): Truncated description (first 50 characters)
  • username (str, readonly): User who triggered the event

Pagination and Iteration

The Events API returns paginated results that support iteration in both directions:

# Navigate through pages
events.next(count=None)     # Get next (newer) page of events
events.prev(count=None)     # Get previous (older) page of events

# Iterate continuously
events.forwards()   # Iterate forwards (newer events)
events.backwards()  # Iterate backwards (older events)
# Get paginated results
events = client.events.query(limit=100)

# Manually navigate pages
next_page = await events.next()  # Get next 100 events
prev_page = await events.prev()  # Get previous 100 events

# Continuous iteration backwards (older events)
async for event in events.backwards():
    print(f"{event.created}: {event.description}")
    if some_condition:
        break

# Continuous iteration forwards (newer events)
async for event in events.forwards():
    print(f"{event.created}: {event.description}")
    if some_condition:
        break

Event Levels

from maas.client.viscera.events import Level

class Level:
    """Event level enumeration (IntEnum)."""
    AUDIT = 0               # Audit events (user actions)
    DEBUG = 10              # Debug information
    INFO = 20               # Informational messages
    WARNING = 30            # Warning messages
    ERROR = 40              # Error messages
    CRITICAL = 50           # Critical errors

The Level enum corresponds to Python logging levels, making it intuitive for developers familiar with Python's logging module.

from maas.client.viscera.events import Level

# Filter by event level
audit_events = client.events.query(level=Level.AUDIT)
errors = client.events.query(level=Level.ERROR)
critical = client.events.query(level=Level.CRITICAL)

# Level can also be specified as string or int
events = client.events.query(level='ERROR')
events = client.events.query(level=40)

# Access via client.events.Level
events = client.events.query(level=client.events.Level.WARNING)