This article provides an overview of the AtomSphere Event Framework and how Events such as "process errors" and "Atom offline" are generated and consumed.
The Event Framework provides the technical infrastructure and plumbing for logging, handling, and alerting from processes at run-time. It captures Events from processes and Atoms within your account and records them in the platform database. These Event records are used by AtomSphere to generate email alerts based on user subscriptions and are available to query directly through the Event platform API.
Note the list of Events is not visible in the AtomSphere UI.
How the Event Framework Works
- Something happens during a process execution or the Atom runtime's status changes.
- The Atom uploads the event message to the AtomSphere platform.
- An Event record is created in the platform database.
- The Event record is available to be sent/consumed by the various delivery channels such as email, RSS, or the platform API.
- The Events records are purged after 7 days.
- The Atom runtime must be able to communicate with the AtomSphere platform to upload the message. If the Atom cannot connect for some reason, Events along with other messages will be queued and uploaded once the connection is re-established.
- Process Events are generated and uploaded to the platform asynchronously during and after the execution completes. This can mean Events may not be available until sometime after the execution finishes. You should not rely on these Events if you need to trigger immediate/real-time workflows.
- Events reside in the AtomSphere platform, not the local Atom runtimes. You cannot query/obtain Events from the local Atom.
- Event records are purged after 7 days.
- Events are NOT generated for Test Mode executions.
- For Low Latency executions, process.execution Events are NOT generated, even for process errors. user.notification Events ARE created however be cautious when using them in high volume scenarios. See Functional Monitoring of Integration Processes Best Practices for considerations.
- Events ARE generated for executions and Atoms in environments classified as "Test" however email alerts are not sent by the platform.
Types of Events
There are four types of Events.
System-generated message created based upon the Atom's status, including when the Atom comes online or goes offline.
Keep in mind this status is from the AtomSphere platform's perspective. For example, if the Atom cannot connect to the platform for some reason, the platform may determine it is offline because it has not received a ping from the Atom however the Atom may actually still be running and executing processes as normal.
User-generated message created when a process contains a Notify shape with the "Enable Events" option enabled. When enabled, the Notify shape message creates an Event record in addition to writing to the process log as normal.
System-generated message created when a process execution begins and ends. The completion event can be the result of a successful or errored execution, including one that ended with the use of an Exception shape configured within the process flow.
System-generated message created when the Atom is so busy it is unable to initiate a scheduled process execution. This event type is rare and is usually indicative of an Atom reaching its processing capabilities.
Schedules are "missed" if the scheduler service does not run once each minute. There are generally two scenarios which can cause this to happen:
Note: Missed scheduled events are not related to the "Maximum Queued [Forked] Executions per Node" or "Timeout for Queued [Forked] Executions per Node" Atom properties. They also do not represent scheduled processes that did not execute while an Atom was stopped.
Key Event Attributes
For the full list of attributes see Event object. In addition to eventType described above, some of the notable attributes include:
- eventLevel - The log level (e.g. INFO, WARNING, ERROR).
- status - The user-specified message or Event status (e.g. COMPLETE, ERROR).
- processName - Name of process for applicable Events.
- environment - Name of the environment.
- classification - Classification of the environment (e.g. PROD, TEST).
Events are distinct from process execution results that are displayed in the Process Reporting console.
Creating User Notification Events
Most types of Events are created automatically by the Atom and/or platform, however you can create your own user notification events by using a Notify shape with a process. Notify shapes can be used "inline" because they do not modify document data.
You can also create Events with your own error message by using an Exception shape (assuming it causes the process execution to fail). However it manifests as a process.execution Event type.
Notify shapes always write to the process log but if you want it to additionally create an Event, simply check the option Enable Events:
The Notify shape's Title, Message Level, and Message will be available in the Event record.
See Notify shape for more information and considerations on creating Events.
Once Events are uploaded and captured in the platform database, they can be consumed via several channels. See Functional Monitoring of Integration Processes Best Practices for considerations of using each.
|AtomSphere sends email notifications to users based on their Email Alert subscription preferences. See Email alert management for configuration information.|
Events are always published via RSS. There are two feeds, "Monitor" (all Events) and "Alerts Only" (only Warning or higher Events), available at the overall AtomSphere account level as well as the individual Atom runtime.
Events can be queried directly using the AtomSphere API Event object. This provides the most flexibility for filtering and routing based upon whatever criteria is required. By creating an integration process within AtomSphere (or using an external client), you can integrate Events into an incident reporting system or monitoring tool within your organization.
|Process Log||Event types process.execution and user.notification are also captured in the execution's process log. The process log can be viewed through the Process Reporting console or the Download process log API.|