8. Ack Messages

AMPS provides ack messages to report the status of commands delivered to AMPS.

ack message

Description

The ack message returns status information from AMPS.

AMPS does not create ack messages unless an acknowledgment is specifically requested. The exact meaning and content of ack messages depends on the command the requests the message. AMPS supports the following types of ack messages with the general semantics described below.

ack Type Meaning
completed

An operation has completed.

For example, subscriptions that replay from the transaction log can produce a completed acknowledgment to indicate when transaction log replay has finished and further messages for the subscription are the result of new publishes.

persisted Data has been persisted.
processed AMPS has processed the command. Notice that, depending on the command, AMPS may not have executed the command when this acknowledgment is produced.
received AMPS has received the command, but has not yet processed it.
stats Statistics for the command. This acknowledgment is typically produced after the command has fully completed.

Table 8.1: Types of ack message

Common Header Fields For Ack Messages

Field Description
Command Type of message. Always ack, as encoded by the protocol.
AckType The type of acknowledgment. One of completed, persisted, processed, received or stats.
CommandId The CommandId that this ack refers to. Clients can use this field to correlate the ack returned with the command being acknowledged.
Status The status of the command.
Reason The reason for a failure status.

Table 8.2: Header fields provided in ack

Additional fields for logon

When the ack message is produced in response to a logon command, the following additional header fields may be set:

Field Description
ClientName The name of the client provided with the command.
SequenceId The last SequenceId persisted to the transaction log for this client, as identified by the ClientName.
Bookmark The last bookmark from this client.
UserId UserId to use when the status is retry.
Password Password to use when the status is retry.
Version The version of the AMPS server.

Table 8.3: Additional ack headers for logon

Additional fields for publish and delta_publish

When the ack message is produced in response to a publish or delta_publish command, the following additional header fields may be set:

Field Description
SequenceId The last SequenceId persisted for this client.
Bookmark The last Bookmark persisted for this client.

Table 8.4: Additional ack headers for publish or delta_publish

Additional fields for subscribe and delta_subscribe

When the ack message is produced in response to a subscribe or delta_subscribe command, the following additional header fields may be set:

Field Description
SubId The SubId sent with the command, or the SubId generated by AMPS if no SubId was provided. This field is not returned in processed acks.
Options

Returned when the command is a subscribe to a queue. Contains the following options:

max_backlog indicates the effective maximum backlog that the server has assigned for this subscription.

Table 8.5: Additional ack headers for subscribe or delta_subscribe

Additional fields for unsubscribe

When the ack message is produced in response to a unsubscribe, AMPS does not provide additional header fields.

Additional fields for sow, sow_and_subscribe, sow_and_delta_subscribe

When the ack message is produced in response to a sow, sow_and_subscribe, or sow_and_delta_subscribe, the following additional header fields may be set:

Field Description
SubId The SubId sent with the sow command.
QueryId The QueryId sent with the sow command.
RecordsReturned The number of records returned by a SOW query. This header field is present on stats acknowledgments.
TopicMatches The total number of records compared across all matching SOW topics. This header field is present on stats acknowledgments.
Matches The number of records returned that match the topic regular expression and content filter. This header field is present on stats acknowledgments.

Table 8.6: Additional ack headers for sow, sow_and_subscribe, sow_and_delta_subscribe

Additional fields for sow_delete

When the ack message is produced in response to a sow_delete the following additional header fields may be set:

Field Description
QueryId The QueryId sent with the sow_delete command.
RecordsDeleted The number of records deleted by the command. This header field is present on stats acknowledgments.
TopicMatches The total number of records compared across all matching SOW topics. This header field is present on stats acknowledgments.
Matches The number of records returned that match the topic regular expression and content filter. This header field is present on stats acknowledgments.

Table 8.7: Additional ack headers for sow_delete

Additional fields for stop_timer

When the ack message is produced in response to a stop_timer the following additional header fields may be set:

Field Description
Data

The content of the message body. The message body can contain the following data:

  • elapsed_time
  • mean
  • median
  • max
  • mean
  • ninetieth
  • ninety_fifth
  • ninety_ninth
  • std_deviation
  • byte_count
  • match_count
  • publish_count
TransmissionTime An ISO-8601 date-time code indicating when the message is sent by the client. Used only if set on incoming message.
TopicMatches The total number of records compared across all matching SOW topics. This header field is present on stats acknowledgments.
Matches The number of records returned that match the topic regular expression and content filter. This header field is present on stats acknowledgments.

Table 8.8: Additional ack headers for stop_timer

Data

The ack message does not contain data.