Events
Events API
Overview:
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 torchelastic.events.Event 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.
Note
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 torchelastic.events.record_event() method.
from torchelastic.events 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
record_event(event)
Another way of using the module is via
torchelastic.events.record().
from torchelastic.events 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
torchelastic.events.EventHandler class.
Example
from torchelastic.events import EventHandler
class StdoutEventHandler(EventHandler):
def record(self, event):
print(f"[{event.event_type}]: event_name: {event.name}")
event.configure(StdoutEventHandler(), event_type="stdout_events")
Now all events with event_type ‘stdout_events’ will be printed to stdout.
Classes
-
class
torchelastic.events.api.Event(name: 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.
- Parameters
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.
-
class
torchelastic.events.api.EventHandler[source] Event handler interface is responsible for capturing and recording events to the different destinations, e.g. stdout, file, etc.
-
class
torchelastic.events.api.ConsoleEventHandler[source] The event handler that prints the captured events to the console.
-
class
torchelastic.events.api.NullEventHandler[source] The default event handler that is a no-op.
Methods
-
torchelastic.events.configure(handler: torchelastic.events.api.EventHandler, 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.
- Parameters
handler – Event handler that will process the events.
event_type – Type of event.
-
torchelastic.events.record(event_name: 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.
- Parameters
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.
