Table of Contents
CSS uses a Java Message Server (JMS) for several purposes. Log messages from CSS applications in general can optionally be sent to JMS, see Chapter 24, Logging - org.csstudio.logging. The alarm system uses JMS for the communication between the alarm server and clients.
CSS uses Apache ActiveMQ, a free and open-source implementation of JMS available from http://activemq.apache.org.
Fundamentally, ActiveMQ is a portable Java application, but the scripts to start it are slightly different for Windows and other operating systems, so assert that you download the version suitable for your computer. After downloading it, the ActiveMQ server can be started like this:
cd [activemq_install_dir] bin/activemq start
To stop the server, replace the argument start
with stop.
As a very basic test on Unix and OS X, you can check if the server is listening
on port 61616:
netstat -an | fgrep 61616
The page https://github.com/ControlSystemStudio/cs-studio/wiki/JavaMessageServer has more details on how to adjust the default JMS configuration. For example, you probably want to disable parts of JMS that are not required for operation with CSS.
To use JMS for logging or the alarm system, CSS needs the URL of your JMS instance. It should be of the form
failover:(tcp://your_jms_host:61616)
“Failover” with a single server instructs the client to automatically re-connect after network problems. Actual failover between multiple JMS instances is also possible, but for details you need to refer to the Apache ActiveMQ documentation.
As a basic test of your JMS setup, you can enable JMS logging in your CSS product, for example by adding these lines to your plugin customization file (see Chapter 6, Hierarchical Preferences):
org.csstudio.logging/console_level=FINE org.csstudio.logging/jms_level=FINE org.csstudio.logging/jms_url=failover:(tcp://your_jms_host:61616)
As a result, CSS should send several log messages to JMS.
You can verify this by starting the JMS Monitor,
see Chapter 33, JMS Monitor - org.csstudio.debugging.jmsmonitor, to view messages
for the LOG Topic.
While you should probably disable this in a production setup, the default configuration of ActiveMQ includes a web browser interface. It is accessible at http://localhost:8161/admin on the host where JMS is running. It can display who is connected to JMS and what topic each connection is reading or writing.
All JMS messages used by CSS are of the MapMessage
type. Fundamentally, this allows messages with arbitrarily named string
properties for content.
In reality, however, messages are most useful when the involved applications
understand the messages.
For example, every message shall have a TYPE property.
CSS log messages as sent by the plugin org.csstudio.logging
(see Chapter 24, Logging - org.csstudio.logging) have the following properties:
TYPE: Set to “log” to identify as log message.TEXT: The actual log message.SEVERITY: Log level, for example “SEVERE” or “FINE”. The exact severity may depend on the underlying logging system.CREATETIME: Time when message was created. Format must beyyyy-MM-dd HH:mm:ss.SSSCLASS: Name of (Java) class were message was created.NAME: Name of Java methodAPPLICATION_ID: Application name like “CSS” or “AlarmServer”HOST: Host name running the application.USER: Name of user who was running the application.
The content of messages exchanged within the alarm system or from for example a tool that logs write actions from an operator interface should try to use the same properties as much as possible.
The original RDB schema for logging JMS messages as shown in Figure 12.1, “Message RDB Schema”was developed for the DESY version of CSS.
The column “DATUM” (German for date) holds the time when a message
was written to the RDB. All other message properties like TEXT and
CREATETIME are written to the MESSAGE_CONTENT and MSG_PROPERTY_TYPE
tables.
This schema is very compact and generic.
On the other hand, it is operationally often useful to search for all messages
of TYPE=log or with a certain SEVERITY. Such searches are relatively slow in
the original schema because they require nested lookups in the MESSAGE_CONTENT
table.
The SNS version of CSS therefore added commonly used message properties
directly to the MESSAGE table. Some tools like the message viewer from
org.csstudio.alarm.beast.msghist automatically determine
which message properties are in the main MESSAGE table, and which are in the
MESSAGE_CONTENT table. Other tools like the ones used to write messages from
JMS to the RDB are site-specific, see Chapter 35, RDB Logging - org.cstudio.logging.jms2rdb
CSS includes a generic message history browser as part of the alarm system, see Chapter 31, Message History Browser - org.cstudio.alarm.beast.msghist. Once the messages are logged to the relational database, it is of course possible to create various tools to create customized reports, for example based on JSP technology for web reports.