Package org.acemq.rabbitmq.admin.alerts

Class Alert

java.lang.Object
org.acemq.rabbitmq.admin.alerts.Alert
public final class Alert extends Object
Builds an AlertRule. 

 AlertRule rule = Alert.named("queue-backing-up")
         .on("rabbitmq_detailed_queue_messages_ready")
         .above(1000)
         .lasting(Duration.ofMinutes(5))
         .severity(Severity.WARNING)
         .groupedBy("vhost", "queue")
         .because("a queue is deep and not draining")
         .build();

Reads in the order the thought arrives: what it is called, what it measures, what is too much, for how long, how much it matters, and why. The last one is required — an alert whose reason nobody wrote down is an alert that gets silenced the second time it fires.

  • Method Details

    • named

      public static Alert named(String name)
      Parameters:
      name - what to call it, in kebab case
      Returns:
      a builder

    • on

      public Alert on(String metric)
      Parameters:
      metric - the metric to watch. On the detailed endpoint these carry the rabbitmq_detailed_ prefix, and a rule naming the aggregate metric will silently match nothing there
      Returns:
      this builder

    • above

      public Alert above(double threshold)
      Parameters:
      threshold - fires when the value is strictly greater
      Returns:
      this builder

    • below

      public Alert below(double threshold)
      Parameters:
      threshold - fires when the value is strictly less
      Returns:
      this builder

    • aboveZero

      public Alert aboveZero()
      Fires when the value is anything but zero.

      The right shape for the alerts that matter most: an unroutable publish, a message in a dead-letter queue, a federation link that is not running. For those, one is as bad as a thousand and a threshold would only delay the page.

      Returns:
      this builder

    • isZero

      public Alert isZero()
      Returns:
      this builder, firing when the value is exactly zero

    • where

      public Alert where(String label, String pattern)
      Narrows the rule to the samples whose label matches.

      Without this a rule watches every sample the metric produces, which for a per-queue metric means every queue on the broker. That is right for "is any queue not draining" and badly wrong for "is anything in a dead-letter queue": the second one, unfiltered, is a critical alert that fires whenever any ordinary queue holds a single message.

      The pattern is matched in full, not as a substring, in both halves — Java's matches() and PromQL's =~ are both anchored, so "orders" does not match "orders.new" in either. Use ".*\\.dlq" for a suffix.

      Parameters:
      label - the label name, for example queue or vhost
      pattern - a regular expression the label's value must match in full
      Returns:
      this builder

    • whileZero

      public Alert whileZero(String otherMetric)
      Requires a second metric on the same object to be zero at the same time.

      The difference between a useful alert and one that gets muted. "This queue is deep" is true during every normal burst; "this queue is deep and no consumer is attached" is never normal.

      Joined on the labels given to groupedBy(java.lang.String...), in both halves: in PromQL as and on(vhost, queue), and here by matching those labels between the two metrics. A sample with no counterpart does not fire, which is how and on(...) behaves when a series is missing on one side.

      Parameters:
      otherMetric - the metric that must read zero
      Returns:
      this builder

    • lasting

      public Alert lasting(Duration duration)
      How long the condition must hold before it counts.

      Carried into the generated Prometheus rule as for:. It cannot be honoured by AlertRule.evaluate(org.acemq.rabbitmq.admin.metrics.MetricsSnapshot), which sees one scrape and has no history — so a rule with a duration is a rule whose in-process evaluation is deliberately more eager than the deployed one, and that difference is worth knowing before relying on it.

      Parameters:
      duration - how long
      Returns:
      this builder

    • severity

      public Alert severity(Severity severity)
      Parameters:
      severity - how much it matters
      Returns:
      this builder

    • groupedBy

      public Alert groupedBy(String... labels)
      Parameters:
      labels - the labels that identify what fired, for the generated rule's description
      Returns:
      this builder

    • because

      public AlertRule because(String reason)
      Why this matters, in a sentence somebody woken at three in the morning can act on.

      Required. An alert with a threshold and no reason is one nobody can triage: the question at that hour is never "is this number high" but "what breaks if I ignore it".

      Parameters:
      reason - the sentence
      Returns:
      the rule