This chapter discusses the concepts that are relevant when you monitor Ensemble. This chapter includes the following sections:
An Ensemble production
is a specialized package of software and documentation that integrates multiple, potentially disparate software systems. A production includes elements that communicate with these external systems, as well as elements that perform processing that is internal to the production.
Ensemble permits only one production to be running in a given namespace at any given time.
A running production continues to run even when you close the Management Portal.
It is important to be familiar with the acceptable states of a production, as well as the problem states. These states are displayed in the Management Portal:
||When a production has been started and is operating normally, it has a status of Running. This is an acceptable state.
||A production acquires a status of Stopped when, at the end of the shutdown sequence, all of its queues are free of synchronous messages. This is an acceptable state.
||A production acquires a status of Troubled if Ensemble is stopped but the production did not shut down properly. See Correcting Production Problem States, later in this book.
An Ensemble production includes a number of business hosts
that communicate with each other (and with external systems). A business host is responsible for some category of work.
There are three distinct types of business host. In order to monitor a production, it is not necessary to know the details of why a given business host was implemented as a certain type. However, it is useful to be aware of the types:
Within a production, all communication is carried out by means of request and response messages between the business hosts. In order to understand a production at a high level, just remember that messages carry all traffic, and that the work of a production is to process messages.
Without exception, the Ensemble message warehouse stores all messages, and this information is available in the Management Portal. This section provides an overview of messages and the information that is available about them:
Every message is either a request or a response. There may be requests that do not have a corresponding response defined, but every response is (conceptually) paired with a request. Any request may be synchronous (waits for a response) or asynchronous (does not wait), depending on the details of the business host; you cannot configure this.
Each message has a unique numeric identifier or ID
. This is displayed in many places in the Management Portal, with the caption ID
, depending on the location on the page.
A message has a header, whose structure is the same for all messages. The header contains data fields that help route the message through the system. A message also contains a body, which provides different fields depending on the message type.
Each message uses a specific message body class, chosen by the production developers. The message body class determines whether the message is a request or a response and determines the fields that the message contains. These decisions are not configurable once the production is complete.
For Electronic Document Interchange (EDI) formats, Ensemble provides specialized message body classes that represent the message as a virtual document. In this case, the message body does not contain fields to represent data in the message. Ensemble provides alternative mechanisms for accessing that data. For an introduction, see Ensemble Virtual Documents
The Management Portal displays contents of the message as a whole, treating the message header and the message body as a single unit. The ID of the message header is the ID of the message as a whole. In some cases (for example, if you resend a message), a new header is added (with a new unique ID); as a result, the ID of the resent message is not the same as that of the original message.
Every message is associated with a specific session. A session marks the beginning and end of all the activities prompted by a primary request message from outside Ensemble. Sessions are useful to you because they give you an easy way to see sets of related messages; the Management Portal provides an option for visually tracing the messages, and you can filter this display by session.
Each session has a unique numeric SessionID
. All messages associated with a session use the same SessionID. Ensemble assigns these SessionIDs as follows:
The primary request message starts the session. The SessionID is the same as the ID of the primary request message.
Each additional message that is instantiated during this session has the same SessionID as the primary request, but has a unique message ID.
The following shows an example. Note that (unlike the example) the message IDs within a session are unlikely to be sequential in a production that has many business hosts. When creating a new message, Ensemble always uses the next available integer as the message ID.
Each message has a life cycle during which its status
changes. These statuses are visible on most pages that display messages. The possible status of any message is one of the following:
The message is in transit between its sender and the appropriate queue. This is the first stage in the normal life cycle of a message.
The message is on a queue. This is the second stage in the normal life cycle of a message.
The intended recipient has received the message. This is the third stage in the normal life cycle of a message.
The intended recipient has received the message and has finished processing the message. This is the fourth stage in the normal life cycle of a message.
This status applies only to response messages.
A business operation can defer a message response for later delivery. The response can be picked up and sent back to the original requester by any business host in the production. Between the time when the business operation defers the response, and when the response is finally sent, the response message has a status of Deferred
The sender of the original message is unaware of the fact that the message was deferred. If the original call was synchronous, the call does not return to the sender until the response is sent.
When the response message is finally sent, it has a status of Completed
A response message becomes Discarded
if it reached its destination after the timeout period for the corresponding request expired.
You can also manually mark a message as Discarded
, which you might do for a suspended message that cannot be delivered for some reason.
Note that a message that is marked as Discarded
still remains in the permanent store; messages are deleted only when you explicitly delete them.
The message was suspended by the business operation after failing to reach its external destination or was manually suspended by an administrator. Note that some business operations are designed to set the status of any failed messages to Suspended.
In either case, you can view this message within the Management Portal to determine why it failed and you can resend it if appropriate. For example, if the problem is on the external side of the communication, the external system can be repaired, and then the message can be resent. You could also discard it or even delete it.
The message was aborted by an administrator.
The message encountered an error.
Note that request and response messages have separate statuses. Request-response pairs are not tracked together for various reasons: a request might be repeated several times before it is successfully delivered; some requests have an optional response that can be ignored if it does not arrive; some responses can be deferred for later delivery; some requests are designed to have no response.
Each message has an invocation style
, which describes how the message was sent. The business host that sends a message specifies its invocation style:
means the message is created in one job, then placed on a queue, at which time the original job is released. Later, when the message is processed, a different job will be allocated for the task.
means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be available again in the sender’s pool until the message is delivered to the target.
Ensemble records the following two time stamps for each message. Note that the invocation style affects the meaning of these time stamps:
The message processed time stamp
. Ensemble sets TimeProcessed when the message is taken off of the queue but then resets it to the current time while the message is being processed. Typically, for a completed message, it represents the time that the message processing was completed.
The Ensemble messaging engine determines the priority of a message, which is one of the following:
(1) Used for ACK messages and alarms for interrupted tasks.
(2) Used for synchronous messages.
(4) Used for an asynchronous call made for a BPL synchronous <call>. This ensures that the request and response are processed before any queued asynchronous message.
(6) Used for other asynchronous messages.
The business hosts process messages by means of jobs. A job
is a CPU process that hosts the work done by an Ensemble production. This terminology is intended to avoid confusion between CPU processes (jobs
) and business processes (processes
In general, a job is either running
(processing a message) or it is not running. From a low-level, system viewpoint, an Ensemble production consists almost entirely of jobs waiting to wake up to perform work.
consists of one or more jobs. Each business host can have its own, private pool of allocated jobs a pool with a specific size that cannot be exceeded.
When a business host receives a message, the business host assigns the work to a job from its pool. The job then performs the work. If no job is available, the business host waits for a job to become available. After the job completes the work, the job either returns to the pool or starts work on another message.
More formally, each message is assigned to a specific message queue
, which handles messages in the order that it receives them. Each queue is associated with a single pool, and vice versa.
Unlike other types of business host, a business process can use a public pool (called the actor pool
), which receives messages from a public queue (called the actor queue
). The actor pool and actor queue are shared by all business processes that do not use private pools and queues.
© 1997-2019 InterSystems Corporation, Cambridge, MA