---
id: flow--alarm-plugin
title: "Alarm"
summary: "Pass-through component that raises a flow alarm (an alarm definition from the repository) when a condition is met: on every request, on a downstream exception, on a slow request, or when the request rate in a time window is too low or too high. Place it in front of the part of the flow you want to monitor."
audience: user
keywords: "input, output, onraise, alarm, condition, x, y"
---
# Alarm

Pass-through component that raises a flow alarm (an alarm definition from the repository) when a condition is met: on every request, on a downstream exception, on a slow request, or when the request rate in a time window is too low or too high. Place it in front of the part of the flow you want to monitor.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Input | input | any | Data to monitor. Every record counts as one request. |
| Output | output | same as input | The input data, forwarded unchanged for every record, whether an alarm is raised or not. |
| OnRaise | error output | `Viaducta.Plugins.AlarmPlugin.AlarmInfo` | Called once when an alarm is raised. `AlarmInfo` has `Id` (id of the raised alarm) and `Name` (alarm definition name). |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `Alarm` | alarm selector (alarm definition name) | | Required. Name of the alarm definition to raise. The options are the alarm definitions of the repository; the stored value is the definition name. |
| `Condition` | dropdown: `1` ALWAYS, `2` ON_EXCEPTION, `3` LESS_THAN_X_REQUESTS_IN_Y_MS, `4` MORE_THAN_X_REQUESTS_IN_Y_MS, `5` REQUEST_DURATION_LONGER_THAN_Y_MS | `1` | Required. When to raise the alarm (see Behaviour). |
| `X` | integer (optional) | | Request count threshold. Required for `3` and `4`. |
| `Y` | integer (optional) | | Milliseconds. Window length for `3` and `4`, duration limit for `5`. |

## Behaviour

- On start the plugin checks that `Alarm` is set and exists, and that `X` / `Y` are given for the selected condition; otherwise the flow fails to start.
- Every record on `Input` increments a request counter and is passed to `Output` synchronously.
- Conditions:
  - `1` ALWAYS: raises the alarm when a record arrives (before forwarding it). If the metadata contains error information with an exception, that exception is attached to the alarm.
  - `2` ON_EXCEPTION: if the components behind `Output` throw an exception back to this component, the alarm is raised and the exception is re-thrown. The next record that passes without exception clears the alarm.
  - `5` REQUEST_DURATION_LONGER_THAN_Y_MS: measures how long the downstream (synchronous) processing of a record took. Longer than `Y` ms raises the alarm, otherwise the alarm is cleared.
  - `3` / `4`: a background timer runs every `Y` ms (first check 100 ms after start). It compares the number of requests counted since the last check against the threshold, raises or clears the alarm and resets the counter.
- Only one alarm is active per component: while a raised alarm has not been cleared, further matches do not raise a new alarm and do not call `OnRaise`.
- The alarm message is a prefix describing the condition (for example "The request duration exceeded 2000 milliseconds") followed by the definition's default message. The input data, metadata and exception (if any) are attached to the alarm.

## Notes

- `4` MORE_THAN_X_REQUESTS_IN_Y_MS compares the request count with `Y` instead of `X` (code defect). Until fixed, set `X` and `Y` so that the count threshold is in `Y`, or use the same value for both.
- `1` ALWAYS never clears its alarm, so it effectively raises only once (for the first record) until the alarm is cleared elsewhere.
- `3` LESS_THAN: the first check runs 100 ms after the flow starts, so it usually raises the alarm right after start. The timer conditions use the metadata of the last received record; if no record was received at all, there is no metadata for `OnRaise`.
- `5` only measures the synchronous part of the downstream processing; work handed to other threads (Fork, async queues) is not included.
- Exceptions handled downstream (for example by an error pin) do not reach this component and do not raise an `ON_EXCEPTION` alarm.

## Example

```json
{ "Alarm": "OrderApiSlow", "Condition": 5, "Y": 2000 }
```

Http listener → **Alarm** → Http client → ... ; `OnRaise` → Log