Unique Client Naming and AMPS

In the AMPS client APIs, each instance of the AMPS client is required to provide a client name. The AMPS server treats the client name as a distinct token for a specific instance of an application.

What that means in practical terms is that:

• Only one client with the same name should be connected at a given time

• Different instances of the application should use different names

• The same instance of the application should use the same name

Although these are always good practices, AMPS only enforces unique client naming when there is a transaction log configured for the instance.

Logon and Client Name

AMPS sets the client name for the connection when the client logs on, not when the client connects. This prevents a client that does not have permission to log on from setting a client name that might be in use by another application.

AMPS may be configured to allow implicit logon. In implicit logon, the client name is set on the first command, and the client name uses the name of the connection (such as amps-json-tcp-23). Starting in 5.0.0.0, AMPS does not allow implicit logon by default, since this approach to assigning names will cause AMPS to assign duplicate names across instance restarts and the same application instance will have different names when it reconnects to AMPS. (See the User Guide for information on enabling implicit logon.)

Transaction Logging, Durable Messaging and Unique Names

When a transaction log is configured, AMPS only allows one application with a given client name and the same authenticated ID to connect at a time.

Unique client naming is particularly important when a transaction log is configured. There are two reasons for this:

First, because the application has identified itself as being the same instance as another running instance, AMPS assumes that the same instance of the application is reconnecting before the operating system has notified the server that the previous instance disconnected. To minimize application downtime and use server resources efficiently, AMPS disconnects the previous instance.

The AMPS client declares the uniqueness of messages published to the AMPS server by including a monotonically increasing sequence number on each message published. The client controls the number, and AMPS keeps track of the highest number that AMPS has persisted for a given client. If more than one instance of the client were to use the same name, there would be no way for AMPS to tell the sequence numbers apart.

Last, but not least, the AMPS client libraries use the client name, in conjunction with the AMPS server, as a part of the message durability and recovery strategy. For durable publish and durable subscriptions that will survive an application restart, it's important for the client name to be both unique and consistent across restarts.

Choosing a Naming Strategy

In choosing a naming strategy, consider what makes an application instance unique and use this as the basis for your naming. Also consider making the name easy to correlate to the application instance. At the same time, consider that the longer the name is, the more space will be consumed for AMPS error logs. A good approach is to look for the shortest name that is unique, easy to correlate, and easily readable. While AMPS does not enforce specific restrictions on the character set for a client name, 60East recommends avoiding non-printing characters, newlines, and square brackets ([]) to make it easier to process AMPS logs.

Suppose we have an application for entering orders by a given agent. Each agent has a unique view of the application, and each agent has a distinct instance of the application. At the same time, even if a particular agent shuts down the application and restarts their computer, when they start the application again, it's not a new instance -- they're resuming the same instance of the application. In this case, a unique name might combine the name of the application, the agent name, and the name of the computer running the application. So, for example, a good client name for this application might take a format like Orders-AndyP-TradeDesk45.

By contrast, suppose we have an application that runs an elastic grid of workers that run on virtual machines that are started on demand and shut down when there is no more work to do. Each of these workers is stateless, and is created from an identical operating system image. In this case, it's important for each worker to have a completely unique name. A good client name for this application might use a descriptive name for the application combined with a unique token such as the IP address of the worker. A good client name for this application might take a format such as CrunchData-192.168.0.20.