onnx_ir.journaling¶

Journaling system for ONNX IR operations.

The onnx_ir.journaling module provides a journaling system for tracking and debugging operations performed on ONNX IR objects. This is useful for understanding how a model is transformed, debugging unexpected behavior, or auditing changes made to a model.

Warning

This module is in alpha. The APIs can change.

Quick Start¶

Use the Journal class as a context manager to record operations:

import onnx_ir as ir
from onnx_ir.journaling import Journal

model = ir.load("model.onnx")

with Journal() as journal:
    # Perform operations on the model
    for node in model.graph:
        node.name = f"renamed_{node.name}"

# View all recorded operations
journal.display()

# Or filter by specific criteria
filtered_entries = [
    entry for entry in journal.entries
    if entry.operation == "set_name" and entry.class_name == "Node"
]
for entry in filtered_entries:
    print(f"{entry.operation} on {entry.class_name}")

The Journal class¶

The Journal class is the main interface for recording operations on the ONNX IR. It captures details about each operation including the object involved, a timestamp, and a stack trace for debugging.

class onnx_ir.journaling.Journal¶

A journaling system to record operations on the ONNX IR.

It can be used as a context manager to automatically record operations within a block.

Example:

from onnx_ir.journaling import Journal

journal = Journal()

with Journal() as journal:
    # Perform operations on the ONNX IR
    pass

for entry in journal.entries:
    print(f"Operation: {entry.operation} on {entry.class_name}")

You can also filter the entries by operation or class name using the filter method:

filtered_entries = [
    entry for entry in journal.entries
    if entry.operation == "set_name" and entry.class_name == "Node"
]
add_hook(hook)[source]¶

Add a hook that will be called whenever a new journal entry is recorded.

Parameters:

hook (Callable[[JournalEntry], None])

Return type:

None

clear_hooks()[source]¶

Clear all hooks.

Return type:

None

display()[source]¶

Display all journal entries.

Return type:

None

property entries: Sequence[JournalEntry]¶

Get all recorded journal entries.

record(obj, operation, details=None)[source]¶

Record a new journal entry.

Parameters:

  • obj (Any)

  • operation (str)

  • details (str | None)

Return type:

None

The JournalEntry class¶

Each recorded operation is stored as a JournalEntry. This dataclass contains all the information about a single operation.

class onnx_ir.journaling.JournalEntry(timestamp, operation, class_, class_name, ref, object_id, stack_trace, details)¶

A single journal entry recording an operation on the IR.

Parameters:
timestamp¶

The time at which the operation was performed.

Type:

float

operation¶

The name of the operation performed.

Type:

str

class_¶

The class of the object on which the operation was performed.

Type:

type

class_name¶

The name of the class of the object.

Type:

str

ref¶

A weak reference to the object on which the operation was performed. To access the object, call ref(). Note that ref may be None, and ref() may return None if the object has been garbage-collected.

Type:

weakref.ref | None

obj¶

The referenced object, or None if it has been garbage-collected or not recorded. This is the same as calling entry.ref() if entry.ref is not None else None.

object_id¶

The unique identifier of the object (id()).

Type:

int

stack_trace¶

The stack trace at the time of the operation.

Type:

list[traceback.FrameSummary]

details¶

Additional details about the operation.

Type:

str | None

class_: type¶
class_name: str¶
details: str | None¶
display()[source]¶

Display the journal entry in a detailed multi-line format.

Return type:

None

property obj: Any | None¶

Get the referenced object, or None if it has been garbage-collected or not recorded.

object_id: int¶
operation: str¶
ref: weakref.ref | None¶
stack_trace: list[traceback.FrameSummary]¶
timestamp: float¶

Using Hooks¶

You can add hooks to be notified whenever a new entry is recorded. This is useful for real-time monitoring or custom logging:

from onnx_ir.journaling import Journal, JournalEntry

def my_hook(entry: JournalEntry) -> None:
    print(f"Operation recorded: {entry.operation} on {entry.class_name}")

journal = Journal()
journal.add_hook(my_hook)

with journal:
    # Operations will trigger the hook as they are recorded
    ...

Inspecting Entries¶

The JournalEntry.display() method provides a detailed, multi-line view of an entry including:

  • Timestamp

  • Operation name

  • Class and object ID

  • Object representation

  • Details (if provided)

  • User code location (the first stack frame outside of onnx_ir internals)

  • Full stack trace

for entry in journal.entries:
    entry.display()  # Detailed multi-line output

The Journal.display() method provides a more compact summary of all entries, suitable for quick overview.