Counters guide

Counters are sum or count queries that can be run on documents and routing orders.

These queries can be scheduled using CRON expressions.

They can also be manually triggered from the user interface. Read the Counters user interface to learn how to synchronize a counter from the Platform 6 Portal.

The results of the queries, called counter’s value can be queried from monitoring tools (Grafana, Nagios, Centreon …) and used to draw graphs or to trigger alerts.

Counter’s parameters

A counter consists of several attributes.

Parameter Description
name The name of the counter
description The multi-language description of the counter
target Determines if the query is going to be run on items or routing orders
data cluster When queries are run on Item, the Data Cluster to the user; usually B2B2OX for documents like MessageInfos
type Determines if the counter’s value is calculated by running a SUM or COUNT query
query An XPath (XML Path Language) expression

XPath expressions

Validation

Valid XPath expressions are tightly coupled to the XML capabilities of the underlying database:

  • PostgreSQL supports XPath 1.0 expressions,
  • DB2 most of XPath 2.0
  • MS-SQL its own very specific set

Root elements

Routing orders XPaths should always start with /routingOrder.

Item XPaths should start with a slash followed by the concept name as in /MessageInfo[FinalRecipient="BankOfAmerica"]

Date & time variable expansions

To facilitate writing XPaths relative to time, two variable expansions are provided for date and time.

Date

The ${DATE} variable will be expanded to a timestamp:

  • The format of the timestamp is specified by the counters.date.format configuration and defaults to yyyyMMdd'T'HH:mm:ss.S z.
  • The timezone short form (CST, CDT, etc…) is specified by the counters.date.timezone configuration and defaults to the server time zone.

Time

The ${TIME} variable will be expanded to an epoch (the number of milliseconds since January 1st, 1970).

Calculations can be performed on DATE and TIME using the following syntax: ${[DATE|TIME]([+|-]\d+[s|m|h|d|M|y])*} where:

  • s: seconds
  • m: minutes
  • h: hours
  • d: days
  • M: months
  • y: years

Examples

Assuming the current date/time is May 13th, 2013 at 11:34:57.12 CEST which is an epoch of 1368437697012 ms.

XPath Expanded
MessageInfo[DateCreated<"${DATE-15d}"][Status="SENT"] MessageInfo[DateCreated<"20130428T11:34:57.12 CEST"][Status="SENT"]
MessageInfo[DateSent>"${DATE-2d+1h}"][Status="SENT"] MessageInfo[DateSent>"20130511T12:34:57.12 CEST"][Status="SENT"]
MessageInfo[DateCreated<"${DATE-15d}"][DateSent>"${TIME-2d+1h}"][Status="SENT"] MessageInfo[DateCreated<"20130428T11:34:57.12 CEST"][DateSent>"1368268497012"][Status="SENT"]

Counters scheduling

Counters’s queries can be scheduled using CRON expressions.

Let’s take the example of a counter which counts the number of failed routing orders.

The counter’s properties will look like below:

{
    "appKey": "",
    "name": "Count_FailedRoutingOrders",
    "description": { "EN": "Number Of Failed Routing Orders" },
    "dataCluster": "B2BOX",
    "query": "/routingOrder",
    "target": "FailedRoutingOrder",
    "type": "COUNT"
}

With the user interface

Once the counter is created, you can manually synchronize it through the user interface.

If there are 24 failed routing orders, the counter’s value will be:

{
    "value": 24,
    "lastSyncDate": 1534853700107
}

(where lastSyncDate is the last synchronisation date).

You can try to recreate a failing routing order and check after synchronisation that the counter’s new value is 25.

However, you can’t spend your time clicking on the synchronisation button, especially if you have hundreds of counters.

With the Routes service

You can automatize the synchronisation task thanks to the Routes service.

Go to the Routes service user interface and create a new route deployment script.

Choose a name (eg: Count_FailedRoutingOrders), a description, select the type Scheduler and the template BaseRoute.groovy.

In the script segment destroyRoutes, enter the following line:

camel.destroyAllRoutes()

In the script segment addRoutes, we’ll define the route using the Camel component Quartz2.

The purpose of the route will be to ask the Counters service to synchronize the counter which id is Count_FailedRoutingOrders at a period determined by a CRON expression.

For any counter, the route will look like this:

from("quartz2://platform6/p6route_${COUNTER_ID}?cron=${CRON_EXPRESSION}")
    .to('p6cmb://counters?platform6.request.action=synchronize&platform6.request.user=${USER_EMAIL_ADDRESS}&id=${COUNTER_ID}')
    .routeId('${ROUTE_ID}')

The parameters are:

  • COUNTER_ID: the counter’s identifier.
  • CRON_EXPRESSION: the CRON expression.
  • USER_EMAIL_ADDRESS: the email address of the user scheduling the counter (eg: admin@amalto.com).
  • ROUTE_ID: it can be anything that you want, but it must be unique. We suggest you also use the counter’s id.

For some information about CRON expressions, have a look at our CRON scheduling section. It will explain the required format and show some examples.

Thus, if we decide to synchronise our Count_FailedRoutingOrders counter every 10 seconds, the route will look like as follow:

from("quartz2://platform6/p6route_Count_FailedRoutingOrders?cron=0/10+*+*+*+*+?")
    .to('p6cmb://counters?platform6.request.action=synchronize&platform6.request.user=admin@amalto.com&id=Count_FailedRoutingOrders')
    .routeId('Count_FailedRoutingOrders')

Enable the route deployment script and save it.

Finally, start the route deployment script. As long as the job is running, the counter will automatically be synchronized every 10 seconds.

Remote access to counters values

Each counter created auto-deploys a RESTful resource that allows remote access to its current value.

Authentication

All Platform 6 RESTful services are guarded with basic authentication. The username/passwords used are those defined using the Platform 6 user administration.

Enumerate all deployed counters

A resource was made available to allow the enumeration of all deployed counters:

http://<hostname>:8080/b2box/rest/resource/counters

The response is available in text/plain or text/html formats and contains a list of all deployed counters including the URL of each individual counters resource (see below).

The representation of the value results returned are in a Nagios format. This is a simple text-based format that Nagios parses to determine if a value is in a CRITICAL, WARN or OK state.

List of all deployed counters

Access a counter’s value

The URL to access a counter’s value is:

http://<hostname>:8080/b2box/rest/resource/counters/<branchid>/<countername>

Where:

  • <hostname>: the host running the Platform 6 instance.
  • <branchid>: the branch’s id specified in the counter definition (usually it’s B2HEAD).
  • <countername>: the name of the counter to query.

Warning

If a counter’s name contains spaces then the URL will require this name to be escaped.

Counter's value

Additional optional parameters to a GET call:

  • maxerror: if the current counter’s value is greater than this parameter value, the response message will be formatted as an error (CRITICAL).
  • maxwarn: if the current counter’s value is greater than this parameter value, the response message will be formatted as a warning (WARN).
  • margin: an additional value that is added to a stated maximum (maxwarn, maxerror) before testing against the current counter’s value. This is useful for example when using the maxwarn parameter. WARN responses will be generated up the given margin value and then CRITICAL responses will be generated.