Child pages
  • Custom columns language reference
Skip to end of metadata
Go to start of metadata

The list views enables the user to create quite advanced custom columns for each table. To do so, a custom column language needs to be used.

For real world examples, and where to use the language, look at Customizing listview columns

For the advanced user who want to read the low level grammar definition, it can be found visualized in your monitor system, on the page: (update the hostname to your system)

http://my.monitor.server.example.org/monitor/modules/lsfilter/html/LSColumnsVisualization.html

Defining a list of columns

(introduced in 6.1)

The table definition is a list of column instrucitons, separated by comma:

<column>, <column>, <column> ...

where <column> can be any of the following:

  • (6.1) A name of a predefined column. Those names is table-dependent, and a list of the column names can be found here: (FIXME)
  • (6.1) A removal of a column, put a minus sign before the name, example: -description (for services)
  • (6.2) The magic word "defaultt", which represents all columns defined by the system administrator. "all" and "default" is in the defult configuration the same. (note: in 6.1, default was available as alias for all, and preferred to use to simplify upgrade)
  • (6.1) The magic word "all", which represents all non-custom columns defined by the system
  • (6.1) A custom colulumn definition, containing a name (as a quoted string), an =, and a column definition

Example (for services):

status_information, default, -attempt, "Custom column" = 13
Custom column definition 

(introduced in 6.1)

The custom column definition is the result of an expression. The expression results a value, of type, either string, number, boolean or list.

The expression can be any of the following:

  • (6.1) Operators, like expr = expr + expr
  • (6.1) A object field name, reffering to the object of the table, like "name", for hosts, or "host.name" or "description" for services
  • (6.2) A function call, example: time(next_check)
  • (6.2) If statement
  • (6.2) A list compherension
  • (6.2) An element in a list, example: services_with_info[0]

Operators

(introduced in 6.1)

There are several binary operators for use in the expression. Those operators have precedance, so lower priority is evaluated after.

Available operators are:

OperatorExampleDescriptionPriorityAvailable since
Equalitya = bCompares the values, true if a equals b16.1
Adda + bComputes sum of a and b26.1
Subtracta - bComputes difference of a and b26.1
Multiplicationa * bComputes the product of a and b36.1
Divisiona / b

Computes the fraction of a and b

36.1
Negation- aChanges sign of a, example 3 becomes -346.1
Parenthesis( a )Makes a be evaulated before, independent of priorityhigh6.1

Object field name

(introduced in 6.1)

To access information of the objects, there are several variables defined for the object. Which variables are available is dependent on which table the column is defined for.

Several tables have objects reffering to objects in other tables, which is available under the prefix of the object name. For example, services can access parameters for the host. The host field "name" is for the service available as "host.name".

Example (for services):

"Identifier" = host.name + ";" + description

The fields available is the fields available for filters, look at Listview filter columns. There are a few extra fields in 6.2 (To be documented)

Function calls

(introduced in 6.2)

To maniuplate and format data, some function calls can be useful. A function call is written like:

functionname(arg, arg, arg, ...)

Functions available are:

FunctionDescriptionAvailable since
implode( separator, list )
Join each element in the list to a string, with the separator as separator6.2
time( unixtimestamp )
Convert a unix timestamp to a human readable time. Many column in the system returns a timestamp, which needs to be processed with this to be readable6.2
idx( id, val0, val1, val2, ... )
Return the value of one argument, given the value of id. Useful for setting names on, for example, states. Example: idx( state, "Ok", "Warning", "Critical", "Unknown" )6.2
urlencode( string )
Escape a string to be used as an attribute in an url. Useful when building links.6.2
htmlescape( string )
Escape a string to be visible on the page. Useful for example for plugin output to be visible without interfering with the rest of the custom column style.6.2
link( relative_url, contant )
Build a link to an internal page on monitor. The relative_url is relative to http://monitor.example.org/monitor/index.php/. Example: link( "extinfo/host?host=" + urlencode(host.name), "Host extinfo" )6.2
nl2br( string )
Convert newlines to linebreaks. This is useful to format the long plugin output as a custom column. nl2br( htmlescape( plugin_output + "\n" + long_plugin_output ) )6.2

Grammar

For a person want to read the low level definition of the grammar, as of monitor 6.2:

expr4     = name '(' expr_list ')'
expr_list = expr ',' expr_list
expr_list = expr

If statement

(introduced in 6.2)

To select either one expression or the other, given a criteria, an if statement can be used. The syntax is as follows:

if test-expression then expression-if-true else expression-if-false

Example:

"has been checked" = if has_been_checked then "yes" else "no"

List compherension

(introduced in 6.2)

To apply an expression on each element in a list, a list compherension can be used. The syntax is as follows:

[ for-every-element-expression for variable in list-expression ]

where for-every-element-expression is applied on every element in the list respresented by list-expression. The variable specified in "variable" is set to the element in list-expression.

Example, for hosts, which creates a link to each service extinfo for a host (in the hosts-table):

[ link( "/extinfo/details?host=" + urlencode(name) + "&service=" + urlencode(svc), htmlescape(svc) ) for svc in services ]

In this case, name comes from the host, which also contains the field services. The list compherension provieds the svc-variable (as "for svc" is written) in the first expression generating the link.

 

In a list compherension, a filter can be applied, to only return some values. In that case, add an if statment, where the corresponding expression returns a true, the item in the list is processed. Written as:

[ for-every-element-expression for variable in list-expression if filter-expression ]

In the previous example, only output services named "PING": (not really useful, but it's an example... For more advanced examples, see Customizing listview columns)

[ link( "/extinfo/details?host=" + urlencode(name) + "&service=" + urlencode(svc), htmlescape(svc) ) for svc in services if svc = "PING" ]

Element of a list

(introduced in 6.2)

To access an indexed element in a list, add [ id ] to the list. Only integer values can be used for now, not an entire expression. The first attribute needs to be an variable, not an expression.

Example:

"First service" = services[0]

This is mostly useful in combination with the host field "services_with_info" and a list compherension. See examples in Customizing listview columns

 


 

Related pages