> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics-based Triggers

> Monitor key metrics and get alerts based on custom threshold conditions and temporal aggregation functions.

export const HnyIcon = ({alias, path, size = 16, iconColor}) => {
  const iconMap = {
    "home": "house.svg",
    "marker": "caretFilledDown.svg",
    "show-marker-options": "chatTextLeft.svg",
    "download": "arrowLineDown.svg",
    "trace-waterfall": "trace.svg",
    "show-query-details": "listDashes.svg",
    "table": "table.svg",
    "log-lines": "logLines.svg",
    "chart": "chartLine.svg",
    "show-settings": "gear.svg",
    "add": "plus.svg",
    "remove": "delete.svg",
    "persist": "caretDown.svg",
    "close": "close.svg",
    "copy": "copy.svg",
    "zoom-in": "magnifyingGlassPlus.svg",
    "zoom-out": "magnifyingGlassMinus.svg",
    "color-assignment": "drop.svg",
    "drag": "dots-six-vertical.svg",
    "drawer": "drawer.svg",
    "show-actions": "dotsThree.svg",
    "edit": "pencil.svg",
    "delete": "trash.svg",
    "move": "arrowsOutCardinal.svg",
    "show-legend": "circleInfo.svg",
    "usage-ok": "usageGood.svg",
    "usage-warning": "usageWarning.svg",
    "usage-danger": "usageDanger.svg",
    "open-query-builder": "query.svg",
    "home-menu": "house.svg",
    "query-menu": "query.svg",
    "boards-menu": "board.svg",
    "triggers-menu": "bell.svg",
    "slos-menu": "handshake.svg",
    "service-map-menu": "serviceMap.svg",
    "history-menu": "clockCounterClockwise.svg",
    "manage-data-menu": "cube.svg",
    "usage-menu": "usageGood.svg",
    "show-details": "dotsThreeVertical.svg",
    "resize-handle": "board-panel-resize-handle.png",
    "standard-dataset": "cube.svg",
    "trace-dataset": "cubeChat.svg",
    "all-datasets": "linkedSquares.svg",
    "share": "arrowBentRight.svg",
    "run-in-query-builder": "arrowSquareUpRight.svg",
    "link": "link.svg",
    "text": "text.svg",
    "receive": "arrowLineDown.svg",
    "process": "lightning.svg",
    "sample": "drop.svg",
    "send": "arrowLineUp.svg",
    "submit": "arrowUp.svg",
    "canvas-menu": "sparkle.svg",
    "canvas": "sparkle.svg",
    "private": "lockKey.svg",
    "shared": "people.svg",
    "expand": "caretDown.svg",
    "previous": "caretLeft.svg",
    "next": "caretRight.svg"
  };
  const iconBasePath = "/_assets/icons/";
  const iconPath = path || (alias ? `${iconBasePath}${iconMap[alias]}` : undefined);
  return <span className="hny-icon" style={{
    display: "inline-block",
    width: `${size}px`,
    height: `${size}px`,
    maskImage: `url(${iconPath})`,
    maskSize: "contain",
    maskRepeat: "no-repeat",
    maskPosition: "center",
    WebkitMaskImage: `url(${iconPath})`,
    WebkitMaskSize: "contain",
    WebkitMaskRepeat: "no-repeat",
    WebkitMaskPosition: "center",
    backgroundColor: iconColor || "var(--hny-icon-color)",
    verticalAlign: "middle"
  }} />;
};

export const CalloutExample = ({children}) => {
  return <Callout icon="clipboard-check" color="#6B7280">
      {children}
    </Callout>;
};

Learn how to create and update metrics-based Triggers, see example configurations, and understand key limitations and differences from event-based Triggers.

## Creating a metrics-based Trigger

Setting up a metrics-based Trigger works much like setting up an event-based Trigger, with a few key differences tailored to how metrics behave.

To create a metrics-based Trigger:

1. Select **Triggers** (<HnyIcon alias="triggers-menu" />) from the navigation menu.
2. Select **New Trigger**.
3. In the modal that appears, select the **Metrics** dataset.
4. Define the Trigger query:
   * Enter a name and description.
   * Select fields from your metrics dataset.
   * Optionally, use [query-scoped Calculated Fields](/investigate/query/build/calculated-fields/#choosing-the-scope) to apply temporal aggregation functions like `RATE()` or `INCREASE()`, which compute change over time.
     Example: `my_rate_dc RATE(http_requests_total)`.
   * Ensure the query returns a single scalar value, not a time series.
     * Most queries start with a [temporal aggregation function](/investigate/query/temporal-aggregation/) wrapped in a spatial aggregation like `SUM()` or `AVG()`.
       Example: `SUM(my_rate_dc)`.
     * You can also use spatial aggregations alone on metrics.
       In this case, Honeycomb applies a default temporal aggregation function based on the metric's metadata as described in [Applying Temporal Aggregation Functions: Default Behavior](/investigate/query/apply-temporal-aggregation/#default-behavior).
5. Set threshold conditions and choose where to send notifications.
6. Select **Create Trigger** to save.

Your Trigger will evaluate the query at regular intervals (every 15 minutes by default) and send alerts whenever the threshold condition is met.

## Modifying a Metrics-Based Trigger

You can modify a metrics-based Trigger the same way you edit an event-based Trigger.

To modify a metrics-based Trigger:

1. Select **Triggers** (<HnyIcon alias="triggers-menu" />) from the navigation menu.
2. Find the Trigger you want to update, and select its name.
3. In the editor, adjust the query, threshold, or notification settings as needed.
4. Select **Save Trigger** to apply your changes.

<Note>
  You cannot change a Trigger's dataset after it has been created.
  To use a different dataset, create a new Trigger.
</Note>

## Examples

Use these examples as a starting point for building your own metrics-based Triggers.
Each highlights a common use case and shows how to structure the Trigger query.

<Tip>
  Define your calculated field before using it in a Trigger.
  You can do this while building the Trigger; appropriate clauses in the query editor include a **Define calculated field** option.
</Tip>

<CalloutExample>
  **Error Rate Spike**

  * **Goal**: Detect a spike in errors
  * **Calculated Field**: `my_error_rate RATE($k8s.pod.network.errors)`
  * **Trigger Query**: `AVG(my_error_rate)`
  * **Threshold**: `> 0.05`

  This configuration alerts when the average error rate across the Environment exceeds 5%.
</CalloutExample>

<CalloutExample>
  **Saturation Check**

  * **Goal**: Detect a spike in CPU usage
  * **Calculated Field**: `last_cpu_util LAST($k8s.pod.cpu.utilization)`
  * **Trigger Query**: `AVG(last_cpu_util)`
  * **Threshold**: `> 0.9`

  This configuration tracks the most recent CPU utilization across containers and alerts when it rises above 90%.
  It uses `LAST()` to get the most recent sample for each container.
</CalloutExample>

<CalloutExample>
  **Throughput Threshold**

  * **Goal**: Detect sustained high request volume
  * **Calculated Field**:`incr_requests INCREASE($http.server.requests, 300)`
  * **Trigger Query**: `SUM(incr_requests)`
  * **Threshold**: `> 1000`

  This configuration alerts when total requests in the last 5 minutes exceed 1000.
</CalloutExample>

## Compare Metrics-Based and Event-Based Triggers

Metrics-based and event-based Triggers share a similar setup process, but they behave differently in how they evaluate data and support configuration.

| Feature                        | Metrics-Based Triggers       | Event-Based Triggers   |
| ------------------------------ | ---------------------------- | ---------------------- |
| **Temporal Aggregation**       | Via Calculated Fields only   | Not applicable         |
| **Query Preview**              | One bucket only; no 16x view | 16x historical preview |
| **Templates**                  | Not supported                | Supported              |
| **Granularity Selector in UI** | Available                    | Not Applicable         |