Skip to main content

ack: Status from Server

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 TypeMeaning
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.

persistedData 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.

receivedAMPS 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.

Header Fields

The following table contains the header fields returned in an ack message:

FieldDescription
cmdType of message. Always ack, as encoded by the protocol.
ack_typeThe type of acknowledgment. One of completed, persisted, processed, received or stats.
cmd_id

The command ID that this ack refers to. Clients can use this field to correlate the ack returned with the command being acknowledged.

This field will not be returned for acknowledgments that are conflated (persisted acknowledgments for publish commands when AMPS has a transaction log configured).

statusThe status of the command.
reasonThe reason for the status, most often returned with a failure status to provide more detailed information about why the command failed.

logon Acknowledgment: Additional Fields

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

FieldDescription
client_nameThe name of the client provided with the command.
seqThe last message sequence number fully processed (and, if possible, safely persisted) for this client, as identified by the client_name.
bookmarkThe last bookmark from this client.
user_iduser-id to use when the status is retry.
passwordPassword to use when the status is retry.
versionThe version of the AMPS server.

publish, delta_publish: Additional Fields

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

FieldDescription
seqThe last message sequence number processed (and, if possible, safely persisted) for this client.
bookmarkThe last Bookmark persisted for this client.

delta_subscribe: Additional Fields

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

FieldDescription
sub_id

The subscription ID sent with the command, or the ID generated by AMPS if no sub_id was provided.

This field is not returned in processed acks.

opts

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.

bookmark

For a completed acknowledgment on a bookmark subscription, this indicates the point in the transaction log where the acknowledgment message was generated.

Notice that the message that corresponds to this bookmark need not be a message matched by the subscription.

unsubscribe: Additional Fields

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

sow, sow_and_subscribe, sow_and_delta_subscribe: Additional Fields

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:

FieldDescription
sub_idThe sub_id sent with the sow command.
query_idThe query_id sent with the sow command.
records_returned

The number of records returned by a SOW query.

This header field is present on stats acknowledgments.

topic_matches

The total number of records compared across all matching SOW topics.

This header field is present on stats acknowledgments.

matches

The number of records that match the topic regular expression and content filter.

This header field is present on stats acknowledgments.

sow_delete: Additional Fields

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

FieldDescription
query_idThe QueryId sent with the sow_delete command.
records_deleted

The number of records deleted by the command.

This header field is present on stats acknowledgments.

topic_matches

The total number of records compared across all matching SOW topics.

This header field is present on stats acknowledgments.

matches

The number of records that match the topic regular expression and content filter.

This header field is present on stats acknowledgments.