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
  • Header Fields
  • Options Field
  • Returns
  • Errors
Export as PDF
  1. AMPS Command Reference
  2. Commands to AMPS
  3. Subscribing to and Querying Topics

subscribe

The subscribe command is the primary way to retrieve messages from the AMPS processing stream. A client can issue a subscribe command on a topic to receive all published messages to that topic in the future. Additionally, content filtering can be used to choose which messages the client is interested in receiving.

Header Fields

Field

Description

Command

Command to be executed. Value: subscribe

Topic

Topic to place a subscription against.

AckType

Acknowledgment type for the given command.

Value is a comma separated list of one or more of the following: none, received, processed or completed.

Bookmark

A bookmark specifying the point in the transaction log at which to start the subscription.

If the topic provided is not recorded in a transaction log, AMPS enters the subscription without replaying messages. You can provide a single bookmark, or a comma-delimited list of bookmarks. When a list is provided, AMPS starts the subscription at the earliest bookmark in the list.

CommandId

If specified with an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the ack response header.

DataOnly

A Boolean value (true or false) which, if true, will send only raw data to subscriber for a matching publish message.

In the case where the message type is XML, the SOAP envelope will not be included.

Filter

A CDATA wrapped string, used as a content filter expression.

Options

A comma separated list of flags available to the subscribe command.

SendSubscriptionIds

Boolean (true or false) that tells if true requests AMPS to send subscription identifiers with a matched message.

SubscriptionId

The subscription ID for this command. When provided with a new subscription, this is the identifier that AMPS will use for the subscription.

When provided with the replace option, this field specifies the subscription to replace.

When provided with a pause or resume option, this field specifies the subscriptions to pause or resume.

For a new subscription, the AMPS clients will generate a subscription ID if one is not provided.

TopN

The maximum number of messages to provide from a bookmark subscription.

This parameter is only valid for replay from the transaction log.

This parameter is not valid if no bookmark is provided, if the provided bookmark is 0|1| (start from now), or if the command includes the live option.

Options Field

The following table contains a list of the Options available and their definitions when used in the AMPS subscribe command.

Option

Description

none

This is the default Options type.

bookmark

Specifies that the subscription should return bookmarks, if available, on each publish message. Bookmarks are only available if the topic that is subscribed to is recorded in the transaction log.

Notice that this option does not set the starting point for a bookmark subscription: use the Bookmark header for that purpose.

This option is not required to receive bookmarks for a bookmark subscription. Those subscriptions always include bookmarks on each publish message.

conflation=n

Specifies whether to conflate this subscription. The value provided can be a time interval, auto, or none.

When present and set to a value other than none, enables conflation for the subscription.

Can also be set to auto, which requests that AMPS attempt to determine an appropriate conflation interval based on client consumption.

Recognizes the same time specifiers used in the AMPS configuration file (for example, 100ms or 1s or 1m).

Default: none

conflation_key=[keys]

When conflation is enabled, specifies the fields to use to determine message uniqueness.

The format of this option is a comma-delimited list of XPath identifiers within brackets.

For example, to conflate based on the value of the /tickerId and /customerId within a message, the value of this option would be:

[/tickerId,/customerId].

Defaults to the SOW key fields for SOW topics. No default for non-SOW topics. This option is required for non-SOW topics.

This option is not valid with the oof option unless the keys provided are identical to the keys for the topic.

fully_durable

Tells AMPS to send messages to subscribing clients only after they have been persisted to the local transaction log and acknowledged by all downstream instances that use synchronous replication.

This option is only valid for bookmark subscriptions.

live

Tells AMPS to send messages to subscribing clients before they have been persisted to the transaction log.

This option has no effect on subscriptions that are not replays from the transaction log (that is, this option only applies to bookmark subscriptions).

max_backlog=n

When subscribing to a queue, the number of unacknowledged messages the client is willing to accept at a time.

AMPS will not exceed this number, but may choose a smaller number depending on the queue configuration.

non_regex_topic

Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.

no_sowkey

Tells AMPS not to send the AMPS-generated SowKey for messages.

oof

Not supported by this command type.

pause

Pause a bookmark subscription.

This option is only valid for bookmark subscriptions that do not use the live option. When this option is present, AMPS pauses the subscription or subscriptions provided in the SubId of the command.

rate=n

Set the maximum message delivery rate for a bookmark subscription.

This option is only valid for bookmark subscriptions that do not use the live option.

The rate can be specified as either the number of messages per second (for example, 1000), the number of bytes per second (for example, 100KB), or a multiple of the original replay rate (for example, 1.5X).

rate_max_gap=n

When entering a bookmark subscribe that is rate-limited, specify the maximum amount of time that AMPS will wait between messages.

replace

Replace the subscription associated with CmdId with another subscription.

resume

Resume a bookmark subscription.

This option is only valid for bookmark subscriptions that do not use the live option.

When this option is present, AMPS resumes the subscription or subscriptions provided in the SubId of the command.

select=[fields]

Specifies the fields to include in messages provided on this subscription.

The contents of this option are a comma-delimited list of inclusion specifiers.

send_keys

Not supported by this command type.

timestamp

AMPS will include a header with the time at which this instance of AMPS processed the incoming publish command for this message.

Returns

A subscribe command returns the following command types:

Command

Description

publish

A message published to AMPS.

oof

Returned when the oof option is requested on the command, the subscription is to a topic in the SOW, and the subscription is not a bookmark subscribe.

ack

Acknowledgments requested, as described in the following section.

It is possible to specify a processed acknowledgment be sent back to the client that issued the subscribe command. Within this processed acknowledgment, a client can get back the result of placing the subscription (success or failure) and the SubscriptionId, which uniquely identifies the subscription within AMPS. Keeping track of the SubscriptionId is useful for unsubscribing from subscriptions and issuing SOW queries.

The following table contains a list of the supported acknowledgment messages available to the subscribe command.

Acknowledgment

Description

none

No acknowledgment message is returned. This is the default behavior.

completed

Used by bookmark subscriptions to identify the point at which replay is completed.

When a bookmark is present on the subscribe request and this acknowledgment is requested, AMPS sends a completed acknowledgment message to indicate that bookmark replay is complete and the subscription has reached the point in the transaction log at which the subscribe command was received.

Messages delivered after the completed ack are from new publishes.

processed

AMPS has completed the work necessary to register the subscription.

When a bookmark is present and this acknowledgment is requested, this acknowledgment indicates that AMPS is about to begin replay.

persisted

When a bookmark is present and this acknowledgment is requested, AMPS periodically sends a persisted acknowledgment message to indicate the most recent bookmark in the server's transaction log.

received

The subscribe message has been received.

Errors

Any errors that occur during this command will be returned in the status of a processed acknowledgment and logged to the log file. Regardless of success or failure, the processed acknowledgment will only be returned if requested by including processed in the AckType field.

PreviousSubscribing to and Querying TopicsNextsow

Last updated 6 months ago

The table below describes the Options available for use in the subscribe command.

Options Field