# Events

Events are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions.

# Pre-requisite Readings

# Events

Events are implemented in the Cosmos SDK as an alias of the ABCI Event type and take the form of: {eventType}.{eventAttribute}={value}.

Copy type Event struct { Type string `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"` Attributes []common.KVPair `protobuf:"bytes,2,rep,name=attributes,proto3" json:"attributes,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` XXX_sizecache int32 `json:"-"` }

Events contain:

  • A type, which is meant to categorize an event at a high-level (e.g. by module or action).
  • A list of attributes, which are key-value pairs that give more information about the categorized event. Copy // Attribute defines an attribute wrapper where the key and value are // strings instead of raw bytes. Attribute struct { Key string `json:"key"` Value string `json:"value,omitempty"` }

Events are returned to the underlying consensus engine in the response of the following ABCI messages:

Events, the type and attributes, are defined on a per-module basis in the module's /types/events.go file, and triggered from the module's handler via the EventManager. In addition, each module documents its events under spec/xx_events.md.

# EventManager

In Cosmos SDK applications, events are managed by an abstraction called the EventManager. Internally, the EventManager tracks a list of Events for the entire execution flow of a transaction or BeginBlock/EndBlock.

Copy // EventManager implements a simple wrapper around a slice of Event objects that // can be emitted from. type EventManager struct { events Events }

The EventManager comes with a set of useful methods to manage events. Among them, the one that is used the most by module and application developers is the EmitEvent method, which tracks an event in the EventManager.

Copy func (em *EventManager) EmitEvent(event Event) { em.events = em.events.AppendEvent(event) }

Module developers should handle event emission via the EventManager#EmitEvent in each message Handler and in each BeginBlock/EndBlock handler. The EventManager is accessed via the Context, where event emission generally follows this pattern:

Copy ctx.EventManager().EmitEvent( sdk.NewEvent(eventType, sdk.NewAttribute(attributeKey, attributeValue)), )

Module's handler function should also set a new EventManager to the context to isolate emitted events per message:

Copy func NewHandler(keeper Keeper) sdk.Handler { return func(ctx sdk.Context, msg sdk.Msg) (*sdk.Result, error) { ctx = ctx.WithEventManager(sdk.NewEventManager()) switch msg := msg.(type) {

See the Handler concept doc for a more detailed view on how to typically implement Events and use the EventManager in modules.

# Subscribing to Events

It is possible to subscribe to Events via Tendermint's Websocket. This is done by calling the subscribe RPC method via Websocket:

Copy { "jsonrpc": "2.0", "method": "subscribe", "id": "0", "params": { "query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'" } }

The main eventCategory you can subscribe to are:

  • NewBlock: Contains events triggered during BeginBlock and EndBlock.
  • Tx: Contains events triggered during DeliverTx (i.e. transaction processing).
  • ValidatorSetUpdates: Contains validator set updates for the block.

These events are triggered from the state package after a block is committed. You can get the full list of event categories here.

The type and attribute value of the query allow you to filter the specific event you are looking for. For example, a transfer transaction triggers an event of type Transfer and has Recipient and Sender as attributes (as defined in the events file of the bank module). Subscribing to this event would be done like so:

Copy { "jsonrpc": "2.0", "method": "subscribe", "id": "0", "params": { "query": "tm.event='Tx' AND transfer.sender='senderAddress'" } }

where senderAddress is an address following the AccAddress format.

# Next

Learn about SDK telemetry