Class PrometheusNaming

Object
PrometheusNaming
@StableApi 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 Details

  • Method Details

    • isValidMetricName

      public static boolean isValidMetricName(String name)
      Test if a metric name is valid. Any non-empty valid UTF-8 string is accepted.

      Collision detection for suffixes like _total, _info, _bucket, etc. is handled at registration time by the PrometheusRegistry, not by name validation.

      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) for compatibility-preserving sanitization that strips reserved suffixes, or normalizeMetricName(String) for permissive normalization that keeps the original suffixes intact.

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

    • 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 valid metric name.

      Reserved metric name suffixes (_total, _created, _bucket, _info and their dot variants) are stripped. These suffixes are appended automatically by Prometheus exposition format writers, so including them in a base metric name would result in double-suffixing or unintended type inference. For example, a JMX attribute named RequestTotal would be sanitized from kafka_consumer_request_total to kafka_consumer_request, and the counter writer would add _total back at scrape time.

      This behaviour was present in client_java 1.5.x and is restored here to fix a regression introduced in 1.6.0 that affected downstream tools (e.g. the JMX Exporter and the simpleclient bridge) which relied on sanitizeMetricName to strip these suffixes before passing names to the snapshot builders.

      If you want permissive normalization that keeps reserved suffixes intact, use normalizeMetricName(String) instead.

      Throws:
      IllegalArgumentException - if the input is empty

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

    • normalizeMetricName

      public static String normalizeMetricName(String metricName)
      Convert an arbitrary string to a valid metric name without stripping reserved suffixes.

      Any non-empty valid UTF-8 string is accepted and returned unchanged. This is the permissive normalization behavior introduced in 1.6.0. Use this method for new integrations that want to preserve the original metric name and rely on registration-time collision detection instead of suffix stripping.

      Throws:
      IllegalArgumentException - if the input is empty

    • normalizeMetricName

      public static String normalizeMetricName(String metricName, Unit unit)
      Like normalizeMetricName(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 valid unit name by replacing illegal characters.
      Throws:
      IllegalArgumentException - if the unitName cannot be converted, e.g. if you call 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)