Instrumentation module

Edition

Incubator (services)

Issues

INSTRUMENT

Git

Git

Latest

2.4

Compatible with Magnolia 5.7, 5.6.

The Magnolia Instrumentation module provides "probes" for monitoring Magnolia internal metrics and activities over time. The probes are configurable within Magnolia and can be turned on and off. New probes can be added to Magnolia while it is running without restarting.

The probes provide their measurements to an external Prometheus server, a free and open source monitoring product, for storage. Prometheus stores the measurements in a time series database. The measurements stored in Prometheus can be accessed by other services to query and extract the measurements.

Grafana is an external server capable of analyzing and displaying time series from Prometheus and displaying the results in a graphs and dashboards. Grafana dashboards can contain bar graphs, line graphs, tables, dials, pie charts, text, histograms, heat maps and other visualizations of Prometheus time series data.

This module is at the INCUBATOR level.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.services</groupId>
  <artifactId>instrumentation</artifactId>
  <version>2.4</version>
</dependency>

Monitoring solutions

We offer two monitoring solutions:

  • On premises monitoring

  • Cloud service monitoring

The on premises monitoring solution includes:

  • Instrumentation module (Magnolia provided, to be installed by the customer)

  • Standard configuration of instrumentation probes (Magnolia provided, to be installed by the customer)

  • Standard Grafana dashboards for instrumentation probes (Magnolia provided, to be installed by the customer)

  • Grafana server (customer provided)

  • Prometheus server (customer provided)

In the on premise solution, the Prometheus server collects the metrics measurements directly for the monitored Magnolia instance (a.k.a. "pull").

The cloud monitoring solution includes:

  • Instrumentation module (Magnolia provided)

  • Standard configuration of instrumentation probes (Magnolia provided)

  • Cloud instance with configured Prometheus, Grafana and data collection server (Magnolia provided)

In the cloud solution, the monitored Magnolia instance pushes metric measurements to the data collection server (a.k.a. "push").

Installing Monitoring

Depending on the solution, on premise or cloud service, one or more of the following must be installed:

  • the Magnolia instrumentation module

  • configuration for instrumentation probes (may be bundled as a Magnolia module) Grafana server, plus configuration and dashboards (on premise solution only) Prometheus server plus configuration (on premise solution only)

See Installing On Premises Monitoring for more on installing all of the above.

Instrumentation probes

The available instrumentation probes can be broken down into a number of groups:

Magnolia configuration probes

Magnolia configuration probes: configured through the instrumentation module, these probes can collect:

  • whether the Magnolia instance is a public or author instance

  • the values of Magnolia properties

  • the values of repository properties

  • the values of Magnolia server configuration

See Magnolia configuration probes for the available Magnolia configuration probes.

JVM probes

JVM probes: configured through the instrumentation module, these probes can measure:

  • class loading: total number of classes currently loaded, number of classes loaded, number of classes unloaded

  • garbage collection: number of garbage collections executed, running total of garbage collection time

  • memory pools: overall bytes used, committed, max available, bytes used in each memory pool

  • threads: current number of threads, peak number of threads used, total number of threads started

  • JVM: current JVM version and vendor

  • runtime metrics: number of processors, system load average, CPU time used by JVM

See JVM probes for the available JVM probes.

System probes

System probes: configured through the instrumentation module, these probes can measure:

  • defined system properties: system properties in the JVM

  • defined environment properties: environment properties in the JVM

See System probes for the available system probes.

Run time probes

Run time probes: configured through the instrumentation module, these probes can measure:

  • when the JVM started

  • how long the JVM has been running

See Run time probes for the available run time probes.

JMX probes

JMX probes: configured through the instrumentation module, this probe can measure:

  • defined MxBean values inside and outside of Magnolia, e.g. Magnolia cache MxBeans, Tomcat MxBeans

See JMX probes for more on the JMX probe.

Module probes

Module probes: configured through the instrumentation module, these probes can measure:

  • installed modules: each installed module and its current version as a separate measurement

  • installed modules: each installed module and its current version as metric labels

See Module probes for more on the module probes.

Cache probes

Cache probes: configured through the Magnolia cache module, these probes can measure:

  • cache actions: counts of gets, puts, removes and clears

See Cache probes for more.

Rendering probes

Rendering probes: configured through the Magnolia rendering engine, these probes can measure:

  • rendering times: collects times for rendering of individual pages, areas and components

  • rendering times: collects times for rendering of individual pages, areas and components for histograms

See Rendering probes for more on configuring and using rendering probes.

Filter probes

Filter probes: configured in the Magnolia filter chain, these probes can measure:

  • processing time: from probe filter

  • processing time: between starting filter and ending filter

  • processing time: collects processing time from probe filter for histograms

  • number of executions: of probe filter

  • Servlet context information

All filter probes can be configured with Magnolia voters to measure or ignore filter chain requests by URL.
See Filter probes for more on measuring request processing by the Magnolia filter chain.

Machine probes

Machine probes: configured through Magnolia, the machine probes can measure:

  • number of available processors

  • physical memory usage

  • swap usage

  • system and process CPU usage

  • open files

See Machine probes for more on measuring machine usage.

Logging probes

Logging probes: configured through the logging configuration (log4j.xml) for Magnolia, this probe can measure:

  • counts of logging messages: by log level and source

  • counts of logging messages: by log level and source, filtered by message

See Logging probes for more on logging probes.

Probes, metrics, measurements and labels

A probe will collect at least one metric. Each metric will be available in the Prometheus server and you can query Prometheus for the metric as well as applying various functions to manipulate the returned results.

See Prometheus query basics for more on the Prometheus query language.

Metrics collected by Prometheus can be further distinguished by labels identifying characteristics associated with a measurement of a metric. You can use measurement labels to group or filter results returned from Prometheus.

A metric will make measurements with a value. Every measurement will also have labels. Each label will have a value.

For example, consider the rendering probe: the rendering probe adds additional information about the rendering time that was measured as labels, including the following labels:

job="magnolia8080" (1)
instance="localhost:8080" (2)
path="/travel/about" (3)
target="page" (4)
template="tours:pages/destinationCatOverview" (5)
1 Identifies the Prometheus job that collected the measurement. Prometheus adds this label to all collected measurements.
2 Identifies the host the measurement was collected from. Prometheus adds this label to all collected measurements.
3 Identifies the path being rendered.
4 Identifies what is being rendered, a page, area or component.
5 Identifies the template being executed.

Labels allow you to refine your Prometheus queries for specific measurements - say the rendering times for just pages, or the rendering time of a specific template - and build a dashboard display for the results.

Here are the labels common to all metrics stored by Prometheus:

Label Description

job

The Prometheus job name that collected the measurement, the label value corresponds to a job defined in the Prometheus configuration.

instance

Identifies the host instance defined in the Prometheus job that collected the measurement

Instrumentation module probes

Some of the probes in the Instrumentation module are defined as part of the module configuration. There are common properties for probes defined in the instrumentation module, including:

  • class - the full class name of the instrumentation probe to instantiate, for example, info.magnolia.services.instrumentation.probes.jvm.ClassLoadingProbe.

  • enabled - a flag, either true or false, true indicating the probe is active and collecting metrics and false if not.

Probes defined in the instrumentation module are created or modified when the instrumentation module is restarted or changed.

Common properties:

Property Default Description

class

none

The fully qualified class name of the probe to instantiate. The class must implement the info.magnolia.services.instrumentation.probes.LaunchableProbe interface.

enabled

true

Flag controlling if the probe is active and can provide measurements (true) or is disabled and not providing measurements (false).

Instrumentation dashboards

Grafana dashboards are easy to make and customize to meet different needs. The following dashboards are currently available:

  • Magnolia: About - visualizes details about the Magnolia server

  • Magnolia: Cache - visualizes results of cache probes

  • Magnolia: Filter Chain - visualizes results of filter chain probes

  • Magnolia: JVM - visualizes results of JVM probes

  • Magnolia: Logging- visualizes results of logging probes

  • Magnolia: Rendering - visualizes results of rendering probes

  • Magnolia: System - visualizes results of system probes

  • Magnolia: Versions - visualizes results of modules probes

  • OS: Metrics - visualizes runtime metrics of OS and JVM probes

  • OS: Metrics (alternate) - visualizes runtime metrics of OS and JVM probes

  • Tomcat: Health - visualizes Tomcat metrics obtained through JMX probes

See Instrumentation dashboards for more details.

Changelog

Version Magnolia Core Notes

1.5

5.6, 5.7

Added blacklists for properties to the system probes

1.4.1

5.6, 5.7

Bug fixes to log4j 2 probes

1.4

5.6, 5.7

Support for log4j 2 probes

1.3

5.5

Bug fixes to instrumentation probes

1.2.2

5.5

Bug fixes to instrumentation probes

1.2.1

5.5

Bug fixes to instrumentation probes

1.2

5.5

New Magnolia configuration probes

1.1

5.5

First public release

1.0

5.4

Initial release of the module
Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Instrumentation module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules