Events API


The event API is used to publish and process events. The module can be used to capture state transitions to debug or give insight into the execution flow. The is an object containing information about an occurrence during the execution of the program. The destination handler for events can be configured by the event type parameter.


The event type torchelastic is reserved by torchelastic for platform level events that can be produced by the agent or worker.

Record Events:

The event module resembles python’s logging framework in terms of usage and consists of two parts: handler configuration and event publishing.

The example below shows the simple event publishing mechanism via method.

from import Event, record_event

event.configure(event.NullEventHandler()) # uses event_type = "torchelastic"
event.configure(event.ConsoleEventHandler(), event_type = "foo")

def execute():
  event = Event(name="test_event", event_type="foo")
  # The code below will be processed by the ConsoleEventHandler

Another way of using the module is via

from import record

def execute():
  metadata = {'key':'value'}
  record(event_name="test", event_type="console", metadata=metadata)

Writing a Custom Event Handler:

The custom event handler can be implemented by extending class.


from import EventHandler

class StdoutEventHandler(EventHandler):
   def record(self, event):
       print(f"[{event.event_type}]: event_name: {}")

event.configure(StdoutEventHandler(), event_type="stdout_events")

Now all events with event_type ‘stdout_events’ will be printed to stdout.


class str, type: str = 'torchelastic', metadata: Dict[str, Any] = None, timestamp: int = 0)[source]

The class represents the generic event that occurs during the torchelastic job execution. The event can be any kind of meaningful action.

  • name – event name.

  • type – type of event, determines what handler will process the event.

  • metadata – additional data that is associated with the event.

  • timestamp – timestamp in milliseconds when event occured.


Event handler interface is responsible for capturing and recording events to the different destinations, e.g. stdout, file, etc.


The event handler that prints the captured events to the console.


The default event handler that is a no-op.

Methods, event_type: str = '')[source]

Sets the relation between event_type and handler. After the relation is set all events that have type event_type will be processed by the handler.

  • handler – Event handler that will process the events.

  • event_type – Type of event. str, event_type: str = 'torchelastic', metadata: Dict[str, Any] = None)[source]

Constructs and records the event to the destination configured by the event.type parameter.

  • event_name – The name of the event

  • event_type – The type of the event. Is used to determine what handler will process the event

  • metadata – Arbitrary data that is associated with the event.[source]

Records the event to the destination configured by the event.type parameter.


event (Event) – Event to be recorded


Access comprehensive developer documentation for PyTorch

View Docs


Get in-depth tutorials for beginners and advanced developers

View Tutorials


Find development resources and get your questions answered

View Resources