Class PrometheusNaming

Object

PrometheusNaming

public class PrometheusNaming
extends Object

Utility for Prometheus Metric and Label naming.

Note that this library allows dots in metric and label names. Dots will automatically be replaced with underscores in Prometheus exposition formats. However, if metrics are exposed in OpenTelemetry format the dots are retained.

Constructor Summary

Constructors

Constructor	Description
PrometheusNaming()

Method Summary

Modifier and Type	Method	Description
static String	escapeName(String name, EscapingScheme scheme)	Escapes the incoming name according to the provided escaping scheme.
static boolean	isValidLabelName(String name)
static boolean	isValidLegacyLabelName(String name)
static boolean	isValidLegacyMetricName(String name)
static boolean	isValidMetricName(String name)	Test if a metric name is valid.
static boolean	isValidUnitName(String name)	Units may not have illegal characters, and they may not end with a reserved suffix like 'total'.
static boolean	needsEscaping(String name, EscapingScheme scheme)
static String	prometheusName(String name)	Get the metric or label name that is used in Prometheus exposition format.
static String	sanitizeLabelName(String labelName)	Convert an arbitrary string to a name where isValidLabelName(name) is true.
static String	sanitizeMetricName(String metricName)	Convert an arbitrary string to a name where isValidMetricName(name) is true.
static String	sanitizeMetricName(String metricName, Unit unit)	Like sanitizeMetricName(String), but also makes sure that the unit is appended as a suffix if the unit is not null.
static String	sanitizeUnitName(String unitName)	Convert an arbitrary string to a name where validateUnitName(String) is null (i.e. the name is valid).
static String	validateMetricName(String name)	Same as isValidMetricName(String), but produces an error message.
static String	validateUnitName(String name)	Same as isValidUnitName(String) but returns an error message.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PrometheusNaming

public PrometheusNaming()

Method Details

isValidMetricName

public static boolean isValidMetricName(String name)

Test if a metric name is valid. Rules:

• The name must match METRIC_NAME_PATTERN.
• The name MUST NOT end with one of the RESERVED_METRIC_NAME_SUFFIXES.

If a metric has a Unit, the metric name SHOULD end with the unit as a suffix. Note that OpenMetrics requires metric names to have their unit as suffix, and we implement this in prometheus-metrics-core. However, prometheus-metrics-model does not enforce Unit suffixes.

Example: If you create a Counter for a processing time with Unit SECONDS, the name should be processing_time_seconds. When exposed in OpenMetrics Text format, this will be represented as two values: processing_time_seconds_total for the counter value, and the optional processing_time_seconds_created timestamp.

Use sanitizeMetricName(String) to convert arbitrary Strings to valid metric names.

validateMetricName

@Nullable
public static String validateMetricName(String name)

Same as isValidMetricName(String), but produces an error message.

The name is valid if the error message is null.

isValidLegacyMetricName

public static boolean isValidLegacyMetricName(String name)

isValidLabelName

public static boolean isValidLabelName(String name)

isValidLegacyLabelName

public static boolean isValidLegacyLabelName(String name)

isValidUnitName

public static boolean isValidUnitName(String name)

Units may not have illegal characters, and they may not end with a reserved suffix like 'total'.

validateUnitName

@Nullable
public static String validateUnitName(String name)

Same as isValidUnitName(String) but returns an error message.

prometheusName

public static String prometheusName(String name)

Get the metric or label name that is used in Prometheus exposition format.

Parameters:

name - must be a valid metric or label name, i.e. isValidMetricName(name) or isValidLabelName(name) must be true.

Returns:

the name with dots replaced by underscores.

sanitizeMetricName

public static String sanitizeMetricName(String metricName)

Convert an arbitrary string to a name where isValidMetricName(name) is true.

sanitizeMetricName

public static String sanitizeMetricName(String metricName,
 Unit unit)

Like sanitizeMetricName(String), but also makes sure that the unit is appended as a suffix if the unit is not null.

sanitizeLabelName

public static String sanitizeLabelName(String labelName)

Convert an arbitrary string to a name where isValidLabelName(name) is true.

sanitizeUnitName

public static String sanitizeUnitName(String unitName)

Convert an arbitrary string to a name where validateUnitName(String) is null (i.e. the name is valid).

Throws:

IllegalArgumentException - if the unitName cannot be converted, for example if you call sanitizeUnitName("total") or sanitizeUnitName("").

NullPointerException - if unitName is null.

escapeName

public static String escapeName(String name,
 EscapingScheme scheme)

Escapes the incoming name according to the provided escaping scheme. Depending on the rules of escaping, this may cause no change in the string that is returned (especially NO_ESCAPING, which by definition is a noop). This method does not do any validation of the name.

needsEscaping

public static boolean needsEscaping(String name,
 EscapingScheme scheme)