System probes

System probes collect information about the environment and system properties of the JVM running Magnolia. They can be used to discover the environment and system properties used by Magnolia and their settings.

System probes are configured in the instrumentation module.

There are four system probes:

Available System probes

Both SystemProbe and SystemPropertiesProbe capture the same information - the JVM system properties - but in slightly different forms as measurement labels.
Both EnvironmentProbe and EnvironmentPropertiesProbe collect the same information - the environment properties visible through System.getenv() - but as differently labelled metrics.

RuntimeProbeCommand captures information about the JVM running Magnolia: its name, vendor and version. Unlike the other system probes, RuntimeProbeCommand is actually a Magnolia command that collects its metrics when executed.

All system probes are configured in the Instrumentation module. Probes should be added in /modules/instrumentation/config/probes and specify the class property (required) and enabled property (optional). System probes defined in the instrumentation module are created or modified when the instrumentation module is restarted or changed.

There are common properties for system probes, including:

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

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

Table 1. Common properties
Property Default Description

class

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).

SystemProbe

The SystemProbe records the system properties and their values in the JVM.

System properties are retrieved by calling:

System.getProperties()

Each system property will be added as a label to the metric with its value. You can restrict the system properties collected by defining the properties parameter; only system properties matching a name in properties will be collected.

Configuration properties

Property Description Required

class

Should be info.magnolia.services.instrumentation.probes.environment.SystemProbe.

name

The metric name used by Prometheus. Taken as from the node name when configured.

description

A description of the metric.

properties

An array of properties names.

If defined, only system properties matching a defined property name will be collected.

excludedProperties

An array of property names to exclude from collection.

excludedProperties lets you "blacklist" selected properties: any property name in excludedProperties will not be collected and saved.

If defined, only system properties not matching the excluded properties will be collected.
You can use both properties and excludedProperties, but any property name listed in excludedProperties will not be collected, even it is also defined in properties (i.e. "blacklisting" a property overrides "whitelisting" a property).

Metrics

Metric Description

<metric-name>

The configured metric name with each system property and its value as labels.

The value of the metric will always be 1.

Labels

The labels included with the metric depend on the system properties defined and the setting of the properties property.

Example

SystemProbe example config

SystemPropertiesProbe

The SystemPropertiesProbe records the system properties and their values in the JVM like SystemProbe. Unlike SystemProbe, SystemPropertiesProbe records each system property as a separate measurement with set labels (propertyName and propertyValue).

The system properties recorded by SystemPropertiesProbe may be more convenient to work with since they have set labels (propertyName and propertyValue) than SystemProbe’s labels of <system property>=<value>.

System properties are retrieved by calling:

System.getProperties()

The name of each system property will be added as the value of the propertyName label. The value of each system property will be added as the value of the propertyValue label.

Configuration properties

Property Description Required

class

Should be info.magnolia.services.instrumentation.probes.environment.SystemPropertiesProbe.

name

The metric name used by Prometheus. Taken as from the node name when configured.

description

A description of the metric.

properties

An array of properties names.

If defined, only system properties matching a defined property name will be collected.

excludedProperties

An array of property names to exclude from collection.

excludedProperties lets you "blacklist" selected properties: any property name in excludedProperties will not be collected and saved.

If defined, only system properties not matching the excluded properties will be collected.
You can use both properties and excludedProperties, but any property name listed in excludedProperties will not be collected, even it is also defined in properties (i.e. "blacklisting" a property overrides "whitelisting" a property).

Metrics

Metric Description

<metric-name>

The configured metric name with each system property and its value as labels.

The value of the metric will always be 1.

Labels

Label Metric Description

propertyName

<metric-name>

The name of a defined system property.

propertyValue

<metric-name>

The value of the system property.

Example

SystemPropertiesProbe example config

EnvironmentProbe

EnvironmentProbe was deprecated in v1.3. Use SystemProbe instead.

EnvironmentPropertiesProbe

The EnvironmentPropertiesProbe records the environment properties and their values in the JVM like EnvironmentProbe. Unlike EnvironmentProbe, EnvironmentPropertiesProbe records each environment property as a separate measurement with set labels (propertyName and propertyValue).

The system properties recorded by EnvironmentPropertiesProbe may be more convenient to work with since they have set labels (propertyName and propertyValue) than EnvironmentProbe’s labels of <system property>=<value>.

System properties are retrieved by calling:

System.getenv()

The name of each environment property will be added as the value of the propertyName label. The value of each environment property will be added as the value of the propertyValue label.

Configuration properties

Property Description Required

class

Should be info.magnolia.services.instrumentation.probes.environment.EnvironmentPropertiesProbe.

name

The metric name used by Prometheus. Taken as from the node name when configured.

description

A description of the metric.

properties

An array of properties names.

If defined, only system properties matching a defined property name will be collected.

excludedProperties

An array of property names to exclude from collection.

excludedProperties lets you "blacklist" selected properties: any property name in excludedProperties will not be collected and saved.

If defined, only system properties not matching the excluded properties will be collected.
You can use both properties and excludedProperties, but any property name listed in excludedProperties will not be collected, even it is also defined in properties (i.e. "blacklisting" a property overrides "whitelisting" a property).

Metrics

Metric Description

<metric-name>

The configured metric name with environment properties name as the propertyName label and their values as the propertyValue label.

The value of the metric will always be 1.

Labels

Label Metric Description

propertyName

<metric-name>

The name of a defined system property.

propertyValue

<metric-name>

The value of the system property.

Example

EnvironmentPropertiesProbe example config
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