Events and logs

Every run has a chronological event timeline. Magmell adds gateway lifecycle phases, and your handler can add logs, spans, metrics, and domain events.

Emit logs

import siloga_agent

siloga_agent.log("document loaded", document_id="doc_123", pages=18)
siloga_agent.log("low confidence", level="warning", score=0.42)

Levels are debug, default, warning, and error. Extra keyword arguments become structured data rather than text embedded in the message.

Time important work

with siloga_agent.span("model.generate"):
    response = model.generate(prompt)

The resulting span records its start and duration, including when the block exits with an error.

Record metrics and domain events

siloga_agent.metric("model.tokens", response.usage.total_tokens, model="example-model")
siloga_agent.event("review.completed", findings=len(response.findings))

Use metrics for numeric measurements and events for meaningful points in your business workflow.

Inspect a run

By human-friendly handler and run number:

magmell runs events reviewer#42

Or by globally unique run ID:

magmell runs events 8ebea6be-3b54-40ca-b8b5-5176264f2450

Filter out lower-severity entries when investigating a problem:

magmell runs events reviewer#42 --level warning

Failure behavior

Events emitted before an exception are retained and returned with the failed invocation. Events emitted at module import time or from a thread without the invocation context are ignored.

Limits

One invocation can emit up to 1,000 handler events. Magmell adds one final truncated warning if the handler exceeds that cap. Individual names and messages are capped at 4,096 characters, and an event’s serialized data is capped at 16 KiB.

Do not include credentials, authorization headers, full prompts containing sensitive information, or secret values in event data.