PingDirectory

Customizing published metrics

The server is preconfigured with a wide variety of definitions that publish the values of specified monitor attributes as metrics that can be consumed by Prometheus. However, you can also configure additional metrics by creating Prometheus monitor attribute metrics.

Each of these definitions includes the following configuration properties:

metric-name

The name of the metric as it should be published for use in Prometheus. The metric name must start with a letter or an underscore and must contain only letters, digits, and underscores. This is required, and all metric definitions must have a unique name.

monitor-attribute-name

The name of the monitor attribute whose value should be published as a Prometheus metric. This is required, and only single-valued attributes are supported. The value must be an integer or floating-point number.

monitor-object-class-name

The name of the object class for the monitor entry that contains the attribute to publish as a Prometheus metric. This is required.

metric-type

The data type for the metric to be published. This is required, and the value should be one of the following:

  • boolean — Indicates that the value of the attribute represented by monitor-attribute-name has one of the following values: true, false, enabled, disabled, yes, no, on, off, 1, or 0. The server sends a gauge metric to Prometheus with a value of:

    • 1 to represent any of the following: true, enabled, yes, on, or 1

    • 0 to represent any of the following: false, disabled, no, off, or 0

  • counter — Indicates that the value is one that increases over time as certain events occur in the server. This can include values that simply increment each time the event occurs, such as counting the number of connections accepted by the server since it started, but it can also include values that increase by larger amounts, such as counting the total number of bytes transferred in responses.

  • gauge — Indicates that the value is one that can go up or down over time and whose value represents the current state of some aspect of the server, such as the number of connections that are currently established.

filter

An optional search filter that can be used to indicate that the metric should only be published for monitor entries that match this filter. If this is not specified, then the metric is published for any monitor entry with the specified attribute and object class.

metric-description

An optional human-readable string that describes the purpose for the metric or that provides some other additional information about it.

label-name-value-pair

An optional set of name-value pairs for labels that should be included in the definition for the metric. If provided, each item should use an equal sign to separate the label name from the value, such as label_name=label_value. Label names must start with a letter or underscore and must only contain letters, digits, and underscores. Label values can be any non-empty string.

Metric-specific labels override server-wide labels, so if a metric-specific label is defined with the same name as a label that would otherwise be applied to all metrics, then the metric-specific value will be used instead of the server-wide value.

For example, to create a Prometheus metric that exposes the value of the currentConnections attribute of the general monitor entry, you could use a configuration change like:

dsconfig create-prometheus-monitor-attribute-metric \
 	--extension-name "Prometheus Monitoring" \
 	--metric-name general_monitor_current_connections \
 	--set monitor-attribute-name:currentConnections \
 	--set monitor-object-class-name:ds-general-monitor-entry \
 	--set metric-type:gauge \
 	--set "metric-description:The number of connections currently established"

If you want to remove any of the metrics that are included in the out-of-the-box configuration, then remove the definition for that metric from the server configuration.