Skip to main content

Receiving Events

This guide covers how you can correctly receive and interpret events as part of integrating with the Reporting API.

info

The C# examples in this tutorial use the protobuf-net Nuget package.

Event Queues​

RabbitMQ supplies events via two queues.

  • rabbit.spot_queue is used for receiving spot events (and only spot events).
  • rabbit.queue is used for receiving all other types of events.
info

Note that rabbit.spot_queue is not available by default. You can enable it by contacting Spotware's service assurance team.

Structure of Events​

Each event contains the following information.

NameDefinition
PayloadThe contents of the Protobuf message as a byte array
PropertiesThe properties of the object representing the delivered message. Properties contain the following information.
  • content_type. The type of content that the message represents. The value of this property always equals application/x-protobuf.
  • content_length. The size of the message in bytes.
  • headers. The property containing message headers. The following headers are supported.
    • messageType. The message type from among those supported by the Reporting API (e.g., TraderEvent, TraderGroupEvent, etc.).
    • spotware-sequence-number. The sequence number assigned to the event. You can use it to determine whether reconciliation is needed.

In brief, accessing the contents of an event requires the following.

  1. Determining the messageType of the newly received message via the headers.messageType property.
  2. Converting the message payload into a suitable class representing the messageType received during Step 1.

If you already know the messageType of an event, you can access its contents as follows (the examples below use TraderGroupEvent).

TraderGroupEvent event = Serializer.Deserialize(TraderGroupEvent, message.Body);
info

Each queue has limits on how many events it can hold and for how long it can hold them in case of a client losing its connection with our RabbitMQ node. All events that meet these limits are stored on our side and are sent to your client as soon as connection is restored. However, events that exceed these limits will be essentially lost. If your connection to RabbitMQ is dropped, please validate all newly received events by their spotware-sequence-number and reconcile if you detect that some events have been missed.

Initiating Message Consumption​

After establishing a connection with RabbitMQ, you should be ready to receive events from rabbit.queue and, optionally, rabbit.spot_queue. To do so, perform the following actions.

  • Create a consumer object.
  • Subscribe the consumer to suitable handlers of the Received event.
  • From your channel object, call a valid method for initiating message consumption.

Here are two simple examples of how you can start receiving and processing messages.


/* the NAMESPACE string should contain all qualifiers required
to access the classes representing various Protobuf message types*/
const string NAMESPACES = ...; 

var consumer = new EventingBasicConsumer(channel);
consumer.Received += (model, ea) =>
{
    string messageType = Encoding.UTF8.GetString((byte[])ea.BasicProperties.Headers["messageType"]);
    long sequenceNumber = Convert.ToInt64(ea.BasicProperties.Headers["spotware-sequence-number"]);
    
    // the Type.GetType() method requires passing a fully qualified class name
    var message = Serializer.Deserialize(Type.GetType('{NAMESPACES}.{messageType}'), ea.Body);
    
    // additional logics depending on the message type
};

channel.BasicConsume(userName, true, consumer);