Retail:Monitoring and Management

Back to main page

Contents 1 Introduction 1.1 Java Management Extensions (JMX) Technology. (http://www.oracle.com/technetwork/articles/java/javamanagement-140525.html) 1.2 Java Util Logging (JUL) Technology (https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html) 1.3 System scripts 2 Consuming information and actions using JConsole 2.1 Enabling JMX monitoring 2.2 Connecting with JConsole 2.3 Java VM general charts 2.4 Java VM information 2.5 Hardware manager information and actions 3 Consuming logging events using the Elastic logging stack 3.1 Configuring logging in the Hardware Manager 3.2 Installing and running the logging stack 4 Appendix. Information published 4.1 Java VM information 4.2 General Hardware Manager information 4.3 Printers information 4.4 Display information 4.5 Payment device information 4.6 Processes information 4.7 Timing statistics 4.8 Counter statistics 5 Appendix. Actions published 5.1 General actions 5.2 Printer actions 5.3 Customer display actions 5.4 Payment actions 6 Appendix. Logging events published 6.1 Severe level 6.2 Warning level 6.3 Fine level 6.4 Finer level

Introduction

The monitoring and management functionalities included in the Openbravo Hardware Manager is based in standard technologies:

Java Management Extensions (JMX) Technology. (http://www.oracle.com/technetwork/articles/java/javamanagement-140525.html)

This technology is used to publish information like status, attributes and statistics, and to publish actions like device testing actions. All the information and actions published can be consumed by all monitoring and management tools that support JMX for example JConsole and Java Mission Control.

Java Util Logging (JUL) Technology (https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html)

This technology is used to publish logging events that are raised during the operation of the Hardware manager Logging events can be processed in several ways, the most simple way is just write all logging events to a file, but also can be collected, processed and and stored by tools like Logstash and Fluentd.

System scripts

As system script there are two simple utilities that allow to start and stop the Hardware Manager from the command line. For Windows systems the scripts are start.bat and stop.bat, and for Linux and MacOS systems the scripts are start.sh and stop.sh.

Consuming information and actions using JConsole

JConsole is a basic monitoring application that uses JMX. It is open source and free. It is and standalone application but it comes with the Oracle Java JDK or OpenJDK, it cannot be downloaded independently.

Enabling JMX monitoring

When opened JConsole, it can connect to local java applications or remote java applications. To connect to local applications is enabled by default but to connect to remote applications, remote monitoring has to be enabled in the monitored application. As an example remote monitoring with disabled security can be enabled passing the following parameters to the monitored application:

-Dcom.sun.management.jmxremote.port=portNum
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false 

Where portNum is the port the application will listen for remote JMX connections. This remote monitoring can also be secured with user and password, and encrypted. To set these parameters you have to set the environment variable HWMANAGER_OPT. In Linux it can be set this way:

export HWMANAGER_OPT = " \
 -Dcom.sun.management.jmxremote.port=5000 \
 -Dcom.sun.management.jmxremote.ssl=false \
 -Dcom.sun.management.jmxremote.authenticate=false"

For the details about this configuration refer to the JMX documentation: https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html

Connecting with JConsole

When opening JConsole the following dialog appears:

Here you can select any of the local processes running or a remote host or port listening for JMX connections. The JMX name exposed by the Hardware Manager is the main java class: org.openbravo.poshw.Main.

Java VM general charts

In the Overview tab there are general performance charts showing the heap memory usage, threads, classes loaded and CPU usage.

Java VM information

In the VM Summary tab there is general information of the Java VM used to run the Hardware Manager like the version, vendor name, live threads, current heap memory, operating system details, and application arguments.

Hardware manager information and actions

In the MBeans tab there are detailed Java VM monitoring information and also all the Hardware Manager published information and actions. The Hardware Manager monitoring information is in the package com.openbravo.pos.monitor. Here there are several samples of screenshots showing Hardware Manager monitoring information.

Here there is a sample screenshot showing Hardware Manager management actions for printers and cash drawers.

Consuming logging events using the Elastic logging stack

Logstash / Elasticsearch / Kibana is a logging stack by Elastic https://www.elastic.co/ that allows to collect, process and store, logging events coming from different sources. These three tools are open source and free to use.

Configuring logging in the Hardware Manager

Logging is configured in the Hardware Manager in the file logging.properties. By default logging is disabled but it is pre-configured to publish logging events to the console, file or a remote server. For example to enable logging to the console add the following line:

handlers=java.util.logging.ConsoleHandler

To enable logging to file add the following line:

handlers=java.util.logging.FileHandler

To enable logging to a remote server add the following lines. This is the configuration to use to publish to the elastic logging stack.

handlers=java.util.logging.SocketHandler
java.util.logging.SocketHandler.host=remote-host
java.util.logging.SocketHandler.port=remote-port

To configure the level of the logging events published it has to be done at root level and/or in each logging handlers. The logging levels available are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER and FINEST.

.level=INFO
java.util.logging.SocketHandler.level=WARNING

For detailed information, refer to the following document: http://tutorials.jenkov.com/java-logging/configuration.html

Installing and running the logging stack

The three applications of the stack can be downloaded from the Elastic web page https://www.elastic.co/ There are packages for Windows and Linux.

• Logstash

Logstash is the dynamic data collection pipeline of the stack. To configure Logstash there is needed to edit a logstash.config file. The sections to configure are the input sources, filters and output destinations. The following configuration sample file listens logging data in a server port and sends the data to the console in ruby format and to an elasticsearch database:

input { 
  tcp {
    port => 8200
    codec => "json"
  }     
}
filter {
}
output {
  stdout { codec => rubydebug }
  elasticsearch { hosts => "http://localhost:9200" }
}

To run logstash execute the following command

bin/logstash -f logstash.config

For detailed information to configure logstash go the document: https://www.elastic.co/products/logstash

• Elasticsearch

Elasticsearch is the database where log events are stored. Is a distributed, JSON-based search and analytics engine.

To run elasticsearch with its default configuration execute the following command:

bin/elasticsearch

For detailed information to configure elasticsearch go to the document: https://www.elastic.co/products/elasticsearch

• Kibana

Finally Kibana is the user interface of the stack if offers all the configuring and managing aspects of the logging stack. To configure kibana there is needed at least to configure the location of the elasticsearch database. To do it edit the file config/kibana.yml and add the following line:

elasticsearch.url: "http://localhost:9200"

To run kibana first execute the following command:

bin/kibana

And then open a browser and go to http://localhost:5601 The user interface will appear and you can see all the functionalities available to inspect and analyse the logging data provided by one or all the hardware manager applications that publish the logging events to the logging stack.

For detailed information to configure and operate kibana go to the document: https://www.elastic.co/products/kibana

Appendix. Information published

Java VM information

In every java application the java.lang.management package provides the interface for monitoring and managing the Java VM. This API provides access to the following types of information.

• Number of classes loaded and threads running.
• Java VM uptime, system properties, and VM input arguments.
• Thread state, thread contention statistics, and stack trace of live threads.
• Memory consumption.
• Garbage collection statistics.
• Low memory detection.
• On-demand deadlock detection.
• Operating system information.

General Hardware Manager information

The com.openbravo.pos.monitor provides the following information in the ApplicationStats object.

• Version. The Hardware Manager version number.
• License. The license and copyright text.
• Server Name. The library name and version for the Jetty embedded web server used.
• Server state. Web server identifier state: 0 STARTING, 1 STARTED, 2 STOPPED, 3 STOPPING, 4 FAILURE.
• Server status. Extended web server state information. If started it shows the ports and services running.
• Configuration path. Path of the configuration file.
• Configuration text. All configuration properties.
• Certificate Issuer DN. The issuer Domain Name of the HTTPS certificate if * exists.
• Certificate Subject DN. The subject Domain Name of the HTTPS certificate if exists.
• Certificate Thumbprint. The Thumbprint hash number in hexadecimal of the HTTPS certificate.

Printers information

The com.openbravo.pos.monitor provides the following information in the DevicePrinterProxy_% object. There is one object for configured printer.

• Name. The configured name.
• Description. Extended configuration information.
• Printer type. The type of the printer: 0 Receipt printer, 1 Desktop printer.
• System name. If the printer is a desktop printer, the operating system name.
• Health. Checks the physical status of the printer, this information depends on the capabilities the printer offers. It may offer information about whether the printer is ready or not, connection status, whether there is paper or not, whether the cover is open or not...
• Physical info. Detailed information offered by the printer. The information offered depends on the printer capabilities.

Display information

The com.openbravo.pos.monitor provides the following information in the DeviceDisplay_proxy object.

• Name. The configured name.
• Description. Extended configuration information.
• Health. Checks the physical status of the display, this information depends on the capabilities the display offers. It may offer information about whether the display is ready or not, connection status...
• Physical info. Detailed information offered by the display. The information offered depends on the display capabilities.

Payment device information

The com.openbravo.pos.monitor provides the following information in the DevicePaymentProxy object.

• Name. The configured name.
• Description. Extended configuration information.
• Health. Checks the physical status of the payment device, this information depends on the capabilities the payment device offers. It may offer information about whether the payment device is ready or not, connection status...
• Physical info. Detailed information offered by the payment device. The information offered depends on the payment device capabilities.

Processes information

The com.openbravo.pos.monitor provides the following information in the DeviceProcessProxy_% object. There is one object for running process like the PDF printing process.

• Name. The configured name.
• Description. Extended configuration information.
• Health. Checks the physical status of the process, this information depends on the capabilities the process offers
• Physical info. Detailed information offered by the process. The information offered depends on the process capabilities.

Timing statistics

The com.openbravo.pos.monitor provides the following information in the StopWatch Stats_% object. There is one object for functionality monitored.

• Running. Whether the functionality monitored is currently running or not.
• Elapsed. Total time in nanoseconds consumed by the functionality since the Hardware Manager started.
• Last Elapsed. Time in nanoseconds the last time the functionality was invoked.
• Max Elapsed. Maximum time in nanoseconds consumed in one single invocation.
• Min Elapsed. Minimum time in nanoseconds consumed in one single invocation.
• Average. Average in nanoseconds of all invocations.
• Calls. Total times the functionality has been invoked since the Hardware Manager started.
• Success calls. The total times the functionality succeeded.
• Error calls. The total times the functionality failed.
• Last error. Error message of the last time the functionality failed.

The functionalities with timing statistics are:

• Processing and printing a receipt document.
• Printing a report.
• Executing a payment.
• Displaying text in the display.
• Executing a process, like printing a PDF file.
• Finishing a receipt. This object monitor the functionality of finishing a receipt, not the total time of printing it.
• Executing the receipt servlet. This includes receipt printing, cash drawer operations and display.
• Executing the report servlet.
• Executing the process servlet.

Counter statistics

The com.openbravo.pos.monitor provides the following information in the CounterStats_% object. There is one object for quantities monitored. Currently only payment amounts are using counter statistics.

• Total, Total amount accumulated.
• Average. Average amount of each invocation.
• Calls. Total times the functionality has been invoked.
• Last value. Last amount accumulated.
• Max value. Maximum amount accumulated.
• Min value. Minimum amount accumulated.

The functionalities with counter statistics are:

• Payment sales succeeded.
• Payment sales not authorized.
• Payment sales failed.
• Payment refunds succeeded.
• Payment refunds not authorized.
• Payment refunds failed.
• Payment voids succeeded.
• Payment voids not authorized.
• Payment voids failed.

Appendix. Actions published

General actions

• Start and stop the embedded web server

Printer actions

• Reset the printer
• Print a receipt test
• Print a PDF test
• Open the drawer
• Check the drawer status

Customer display actions

• Clear the display
• Show sample text in the display

Payment actions

• Execute a test transaction. Payment transactions executed with JMX are all marked as test so cannot be executed real payment transactions using this functionality

Appendix. Logging events published

Severe level

• Errors raised during operation that avoids continuing the normal execution of the application

Warning level

• Errors raised during operation that allows to continue the normal execution.
• Devices declared in the configuration but unable to instance

Fine level

General

• Application initialization and finalization actions
• Application version and license

Printer devices

• Reset action
• Print receipt action
• Print report action
• Open drawer action
• Check drawer status action

Display devices

• Write Visor action
• Clear Visor action

Payment devices

• Execute payment action

Finer level

Printer devices

• Cash drawer status

Display devices

• Text displayed

Payment devices

• Execution parameters and result values