LogoLogo
AMPS Server Documentation 5.3.4
AMPS Server Documentation 5.3.4
  • Welcome to AMPS 5.3.4
  • Introduction to AMPS
    • Overview of AMPS
    • Getting Started With AMPS
      • Installing AMPS
      • Starting AMPS
      • JSON Messages - A Quick Primer
      • spark: the AMPS command-line client
      • Evaluating AMPS on Windows or MacOS
      • Galvanometer and RESTful Statistics
    • AMPS Basics: Subscribe and Publish to Topics
    • State of the World (SOW): The Message Database
      • When Should I Store a Topic in the SOW?
      • How Does the SOW Work?
      • Configuration
      • Queries
      • Atomic Query and Subscribe
      • Advanced Messaging and the SOW
    • Record and Replay Messages with the AMPS Transaction Log
    • Message Queues
    • Scenario and Feature Reference
      • Recovery Strategies
    • Getting Support
    • Advanced Topics
    • Next Steps
  • AMPS Evaluation Guide
    • Introduction
    • Evaluation and Development with AMPS
    • Tips on Measuring Performance
    • Next Steps
  • AMPS User Guide
    • Introduction
      • Product Overview
      • Requirements
      • Organization of this Guide
        • Documentation Conventions
      • Technical Support
    • Installing and Starting AMPS
      • Installing AMPS
      • Starting AMPS
      • Production Configuration
    • Subscribe and Publish
      • Topics
      • Filtering Subscriptions by Content
      • Conflated Subscriptions
      • Replacing Subscriptions
      • Messages in AMPS
      • Message Ordering
      • Retrieving Part of a Message
    • AMPS Expressions
      • Syntax
      • Identifiers
      • AMPS Data Types
      • Grouping and Order of Evaluation
      • Logical Operators
      • Arithmetic Operators
      • Comparison Operators
      • LIKE Operator
      • Conditional Operators
      • Working with Arrays
      • Regular Expressions
      • Performance Considerations
    • AMPS Functions
      • AMPS Function Overview
      • String Comparison Functions
      • Concatenating Strings
      • Managing String Case
      • Replacing Text in Strings
      • String Manipulation Functions
      • Date and Time Functions
      • Array Reduce Functions
      • Geospatial Functions
      • Numeric Functions
      • CRC Functions
      • Message Functions
      • Client Functions
      • Coalesce Function
      • AMPS Information Functions
      • Typed Value Creation
      • Constructing Fields
      • Aggregate Functions
    • State of the World (SOW) Topics
      • How Does the SOW Work?
      • Using the State of the World
      • Understanding SOW Keys
      • Indexing SOW Topics
      • Programmatically Deleting Records from the Topic State
      • SOW Maintenance
        • Creating a Maintenance Schedule for a Topic
        • Setting Per-Message Lifetime
      • Storing Multiple Logical Topics in One Physical Topic
    • Querying the State of the World (SOW)
      • Overview of SOW Queries
      • Query and Subscribe
      • Historical SOW Topic Queries
      • Managing Result Sets
      • Batching Query Results
    • Out-of-Focus Messages (OOF)
    • State of the World Message Enrichment
    • Incremental Message Updates
      • Using Delta Publish
      • Understanding Delta Publish
      • Delta Publish Support
    • Receiving Only Updated Fields
      • Using Delta Subscribe
      • Identifying Changed Records
      • Conflated Subscriptions and Delta Subscribe
      • Select List and Delta Subscribe
      • Options for Delta Subscribe
    • Conflated Topics
    • Aggregation and Analytics
      • Understanding Views
      • Defining Views and Aggregations
      • Constructing Field Contents
      • Best Practices for Views
      • View Examples
      • Aggregated Subscriptions
    • Record and Replay Messages
      • Using the Transaction Log and Bookmark Subscriptions
      • Understanding Message Persistence
      • Configuring a Transaction Log
      • Replaying Messages with Bookmark Subscription
      • Managing Journal Files
      • Using amps-grep to Search the Journal
    • Message Queues
      • Getting Started with AMPS Queues
      • Understanding AMPS Queuing
      • Advanced Messaging and Queues
      • Replacing Queue Subscriptions
      • Handling Unprocessed Messages
      • Advanced Queue Configuration
      • Queue Subscriptions Compared to Bookmark Replays
    • Message Types
      • Default Message Types
      • BFlat Messages
      • MessagePack Messages
      • Composite Messages
      • Protobuf Message Types
      • Struct Message Types
    • Command Acknowledgment
      • Requesting Acknowledgments
      • Receiving Acknowledgments
      • Bookmark Subscriptions and Completed Acknowledgments
      • Bookmark Subscriptions and Persisted Acknowledgments
      • Acknowledgment Conflation and Publish Acknowledgements
    • Transports
      • Client Connections
      • Replication Connections
      • Transport Filters
    • Running AMPS as a Linux Service
      • Installing the Service
      • Configuring the Service
      • Managing the Service
      • Uninstalling the Service
    • Logging
      • Configuring Logging
      • Log Message Format
      • Message Levels
      • Message Categories
      • Logging to a File
      • Logging to a Compressed File
      • Logging to Syslog
      • Logging to the Console
      • Looking up Errors with ampserr
    • Event Topics
      • Client Status Events
      • SOW Statistics Events
      • Persisting Event Topics
    • Utilities
      • Command-Line Basic Client
      • Dump clients.ack File
      • Dump journal File
      • Dump queues.ack File
      • Dump SOW File
      • Dump Journal Topic Index File
      • Find Bookmark or Transaction ID in Transaction Log
      • Find Information in Error Log or Transaction Log
      • Identify Type of AMPS File
      • List/Explain Error Codes
      • Query Statistics Database
      • Statistics Database Report
      • Storage Performance Testing
      • Submit Minidump to 60East
      • Obsolete Utility: Upgrade File Formats
    • Monitoring AMPS
      • Statistics Collection
        • Time Range Selection
        • Output Formatting
      • Galvanometer
      • Configuring Monitoring
    • Automating AMPS with Actions
    • Replicating Messages Between Instances
      • Replication Basics
      • Configuring Replication
      • Replication Configuration Validation
      • Replication Resynchronization
      • Replication Compression
      • Destination Server Failover
      • Two-Way Replication
      • PassThrough Replication
      • Guarantees on Ordering
      • Replication Security
      • Understanding Replication Message Routing
      • Replicated Queues
      • Replication Best Practices
    • Highly Available AMPS Installations
      • Overview of High Availability
        • Example: Pair of Instances for Failover
        • Example: Regional Distribution
        • Example: Regional Distribution with HA
        • Example: Hub and Spoke / Expandable Mesh
      • Details of High Availability
      • Slow Client Management and Capacity Limits
      • Message Ordering Considerations
    • Operation and Deployment
      • Capacity Planning
      • Linux OS Settings
      • Upgrading AMPS
      • Using AMPS with a Proxy
      • Operations Best Practices
    • Securing AMPS
      • Authentication
      • Entitlement
      • Providing an Identity for Outbound Connections
      • Protecting Data in Transit Using TLS/SSL
    • Troubleshooting AMPS
      • Planning for Troubleshooting
      • Diagnostic Utilities
      • Finding Information in the Log
      • Reading Replication Log Messages
      • Troubleshooting Disconnected Clients
      • Troubleshooting Regular Expression Subscriptions
    • AMPS Distribution Layout
    • Optionally-Loaded Modules
      • Optional Functions
        • Legacy Messaging Functions
        • Special-Purpose Functions
      • Optional SOW Key Generator
        • Chaining Key Generator
      • Optional Authentication/Entitlements Modules
        • RESTful Authentication and Entitlements
        • Multimethod Authentication Module
        • Simple Access Entitlements Module
      • Optional Authenticator Modules
        • Multimethod Authenticator
        • Command Execution Authenticator
    • AMPS Statistics
    • File Format Versions
  • AMPS Configuration Guide
    • AMPS Configuration Basics
      • Getting Started With AMPS Configuration
      • Units, Intervals, and Environment Variables
      • Working With Configuration Files
      • Including External Files
    • Instance Level Configuration
    • Admin Server and Statistics
    • Modules
    • Message Types
    • Transports
    • Logging
    • State of the World (SOW)
      • SOW/Topic
      • SOW/*Queue
      • SOW/ConflatedTopic
      • SOW/View
    • Replication
      • Replication Validation
    • Transaction Log
    • Authentication
    • Entitlement
    • Actions
      • Configuration for Actions
      • Choosing When an Action Runs
        • On a Schedule
        • On AMPS Startup or Shutdown
        • On a Linux Signal
        • On a REST Request
        • On Minidump Creation
        • On Client Connect or Disconnect
        • On Client Logon
        • On Client Offline Message Buffering
        • On Subscribe or Unsubscribe
        • On Incoming Replication Connections
        • On Outgoing Replication Connections
        • On Message Published to AMPS
        • On Message Delivered to Subscriber
        • On Message Affinity
        • On SOW Message Expiration
        • On SOW Message Delete
        • On OOF Message
        • On Message Condition Timeout
        • On Message State Change
        • On a Custom Event
      • Choosing What an Action Does
        • Rotate Error/Event Log
        • Compress Files
        • Truncate Statistics
        • Manage Transaction Log Journal Files
        • Remove Files
        • Delete SOW Messages
        • Compact SOW Topic
        • Query SOW Topic
        • Manage Security
        • Enable or Disable Transports
        • Publish Message
        • Manage Replication Acknowledgment
        • Extract Values from a Message
        • Translate Data Within an Action
        • Increment Counter
        • Raise a Custom Event
        • Execute System Command
        • Manage Queue Transfers
        • Create Minidump
        • Shut Down AMPS
        • Debug Action Configuration
      • Conditionally Stopping an Action
        • Based on File System Capacity
        • Based on an Expression
      • Examples of Action Configuration
        • Archive Journals Once a Week
        • Archive Journals On RESTful Command
        • Record Expired Queue Messages to a Dead Letter Topic
        • Copy Messages that Exceed a Timeout to a Different Topic
        • Deactivate and Reactivate Security on Signals
        • Reset Entitlements for a Disconnected Client
        • Extract Values from a Published Message
        • Shut Down AMPS When a Filesystem Is Full
        • Increment a Counter and Echo a Message
    • Protocols
  • AMPS Monitoring Guide
    • Statistics Types
    • Table Reference
    • Administrative Actions
    • Host Statistics
      • cpu
      • disks
      • memory
      • name
      • network
    • AMPS Instance Statistics
      • api
      • clients
      • config.xml
      • config_path
      • conflated_topics
      • cpu
      • cwd
      • description
      • environment
      • lifetimes
      • logging
      • memory
      • message_types
      • name
      • name_hash
      • pid
      • processors
      • queues
      • queries
      • replication
      • sow
      • statistics
      • subscriptions
      • timestamp
      • transaction_log
      • transports
      • tuning
      • uptime
      • user_id
      • version
      • views
  • AMPS Command Reference
    • Commands to AMPS
      • logon
      • Publishing
        • publish
        • delta_publish
      • Subscribing to and Querying Topics
        • subscribe
        • sow
        • sow_and_subscribe
        • unsubscribe
        • delta_subscribe
        • sow_and_delta_subscribe
      • Removing Messages (SOW/Topic or Message Queue)
      • heartbeat
      • flush
    • Responses from AMPS
      • sow: Content from Server
      • publish: Content from Server
      • oof: Content from Server
      • ack: Status from Server
      • group_begin / group_end : Result Set Delimiters
    • Protocol Reference
      • AMPS Protocol
      • Legacy Protocols Reference
    • Command Cookbook
      • Cookbook: Delta Publish
      • Cookbook: Delta Subscribe
      • Cookbook: Publish
      • Cookbook: SOW
      • Cookbook: SOW and Delta Subscribe
      • Cookbook: SOW and Subscribe
      • Cookbook: SOW Delete
      • Cookbook: Subscribe
  • Deployment Checklist
    • Ensure Sufficient Capacity
    • Apply System and AMPS Configuration
    • Create Maintenance Plan
    • Create Monitoring Strategy
    • Create Patch and Upgrade Plan
    • Create and Test Support Process
    • Conclusion
  • AMPS Clients
    • Performance Tips and Best Practices
    • C++
    • C#/.NET
    • Java
    • JavaScript
    • Python
Powered by GitBook

Get Help

  • FAQ
  • Legacy Documentation
  • Support / Contact Us

Get AMPS

  • Evaluate
  • Develop

60East Resources

  • Website
  • Privacy Policy

Copyright 2013-2024 60East Technologies, Inc.

On this page
  • AMPS Protocol
  • Header Fields - Reference
Export as PDF
  1. AMPS Command Reference
  2. Protocol Reference

AMPS Protocol

AMPS Protocol

The following table describes how the headers in the amps protocol are processed by AMPS.

Current releases of AMPS use a simplified JSON-like syntax for the amps protocol.

AMPS Message Header - Sorted by Name

AMPS Header Field

Abbreviation

Name

ack_type

a

AckType

password

pw

Password

bookmark

bm

Bookmark

batch_size

bs

BatchSize

client_name

ClientName

cmd

c

Command

cmd_id

cid

CommandId

correlation_id

x

CorrelationId

data_only

DataOnly

expiration

e

Expiration

filter

f

Filter

gseq

GroupSequenceNumber

heartbeat

Heartbeat

leaseperiod

lp

LeasePeriod

matches

Matches

msg_len

l

MsgLen

max_msgs

MaximumMessages

opts

o

Opts

orderby

OrderBy

query_id

QueryID

reason

Reason

records_deleted

RecordsDeleted

records_inserted

RecordsInserted

records_returned

RecordsReturned

records_updated

RecordsUpdated

seq

s

Sequence

send_empty

SendEmpty

send_keys

SendKeys

send_oof

SendOutOfFocus

sow_key

k

SowKey

sow_keys

SowKeys

status

Status

sub_id

SubscriptionId

sids

SubscriptionIds

src

Src

timeout_interval

TimeoutInterval

timestamp

ts

TransmissionTime

top_n

TopNRecordsReturned

topic_matches

TopicMatches

topic

t

Topic

use_ns

UseNamespaces

user_id

UserId

version

v

Version

Header Fields - Reference

This section provides a reference to the header fields that have been used in AMPS messages. Not all headers are present on all outgoing messages, and not all headers are processed on incoming commands. See the detailed message descriptions in this guide for descriptions of which fields are used on a given command or a given response from AMPS. Further, although this table lists the header fields defined in every protocol, current versions of AMPS may not use every header defined in this table (see the detailed message descriptions for which fields are relevant for a given command or response).

Name

Type

Definition

AckType

string

Acknowledgment type for the given command.

BatchSize

integer

Default is 1 when not present.

Specifies the number of messages that are batched together when returning a query result.

Bookmark

string

A client-originated identifier used to mark a location in journaled messages.

ClientName

string

Used to identify a client.

Useful for publishers that wish to identify the source of a publish, client status messages and for client heartbeats.

Can be set with logon command.

Command

One of:

  • publish

  • subscribe

  • sow

  • sow_and_subscribe

  • sow_delete

  • unsubscribe

  • flush

  • heartbeat

  • logon

Command to be executed.

CommandId

string

Client-specified command ID.

The CmdId is returned by the engine in responses to commands to allow the client to correlate the response to the command.

CorrelationId

string, base64 encoded characters only

Opaque token set by an application and returned with the message.

DataOnly

Boolean (true or false)

If true, only send raw data to subscriber for a matching publish message, i.e. do not include FIX/NVFIX envelope.

Expiration

integer (seconds)

SOW expiration time if used in publish.

Filter

string, should wrap in CDATA

Content filter expression.

GracePeriod

integer (milliseconds)

Grace period after heartbeat interval is exceeded before client is considered in error state.

GroupSequenceNumber

integer

Group Sequence Number returned with each batch message of a SOW response.

Heartbeat

One of:

  • start

  • stop

  • beat

Heartbeat command.

LeasePeriod

timestamp

For messages from a queue, the time at which the lease expires.

LogLevel

One of:

  • info

  • none

Set the log level.

Deprecated

Not used in current versions of AMPS.

Matches

integer

Returned in the acknowledgment to a SOW query that indicates number of matches.

MaximumMessages

integer greater than zero

Specifies the maximum number of messages within a batch publish.

MessageID

string, e.g. MAMPS–XYZ

Set by AMPS engine to tag every incoming message.

MessageLength

integer

Sent with messages that have data (a message body) to indicate the number of bytes in the message body.

MessageType

string

One of the configured message types in AMPS.

Message type.

MsgLen

integer

Sent with messages that have data (a message body) to indicate the number of bytes in the message body.

Opts

string

A comma-delimited list of options on a specific command.

Password

string

Password used to authenticate with an AMPS server.

QueryID

string

SOW query identifier set by client to identify a query.

Reason

string

The failure message that appears when an acknowledgment returns a status or failure.

RecordsDeleted

integer

Used in conjunction with the stats acknowledgment, this is the number of records deleted from the SOW with a sow_delete command.

RecordsInserted

integer

Used in conjunction with the stats acknowledgment, this is the number of records inserted into the SOW.

RecordsUpdated

integer

Used in conjunction with the stats acknowledgment, this is the number of records updated in the SOW.

RecordsReturned

integer

Returned in the acknowledgment to an SOW query that indicates number of records in the store.

SendEmpty

Boolean (true or false); default is true

If true, empty messages that are published will be forwarded to matching subscriptions.

SendKeys

Boolean (true or false)

Option to instruct AMPS that a client would like to receive the SowKey(s) back.

SendOutOfFocus

Boolean (true or false)

If true, Out of Focus messages are sent for the SOW query.

SendSubscriptionIDs

Boolean (true or false)

If false, subscription identifiers will not be sent for a matched message.

Sequence

integer greater than zero

An integer that corresponds to the publish message sequence number.

SowKey

string containing the digits of an unsigned long for AMPS-generated SOW keys

arbitrary string in the base64 character set for user-provided SOW keys

A SowKey will accompany each message returned in an SOW batch.

A SowKey may also be added to messages coming in on a subscription when the published message matches a record in the SOW.

A publish command may contain a SOW key if the SOW for the topic is configured to accept user-provided SOW keys.

SowKeys

comma-separated list of SowKey values

Comma-separated list of SowKey values.

Status

One of:

  • stopped

  • alive

  • timed out

  • error

Used to indicate client status when client is monitored for heartbeats.

SubscriptionId

string, e.g. SAMPS-XYZ

The subscription identifier set by server when processing a subscription.

SubscriptionIds

string

Comma-separated list of SubIds sent from AMPS engine to identify which client subscriptions match a given publish message.

TimeoutInterval

integer

Used in conjunction with the heartbeat interval to set the timeout interval for a publisher.

TopNRecordsReturned

unsigned integer

The number of records to return.

Note: If TopN is not equally divisible by the BtchSz, then more records will be returned so that the total number of records is equally divisible by the BtchSz setting.

Topic

string

Topic

TopicMatches

integer

Returned in the acknowledgment to an SOW query that indicates number of topic matches.

TransmissionTime

ISO-8601 date-time

Timestamp - Optionally set to time the message was processed by the server.

UseNamespaces

Boolean (true or false)

Use SOAP XML namespaces in all messages from the AMPS engine.

UserId

string

Used to identify the user ID of a command.

Version

string

Contains the version of the AMPS server.

PreviousProtocol ReferenceNextLegacy Protocols Reference

Last updated 11 months ago

For more information see the chapter in the AMPS User Guide.

Replicating Messages Between Instances