# Monad Organization Logs Alert

Alert type ID: `monad-log-alert`

Compatible with all Monad tiers

## Description
This alert fires in real time whenever a pipeline log event matches a configured set of conditions. Unlike metric-based alerts that aggregate data over a time window, the Organization Logs Alert reacts to individual log events as they are emitted — letting you get notified the instant a specific error appears, a schema mismatch is logged, or any combination of level and message conditions is met.

Conditions are evaluated using AND logic: a log event fires the alert only when every configured filter matches. The dedupe window is scoped per pipeline node, so a flapping node never suppresses alerts from a healthy node in the same pipeline.

:::note
At least one filter (log level or message filter) must be configured. A rule with no levels and no message filter will never fire.
:::

## Prerequisites

1. Active pipelines generating logs in your Monad organization
2. Pipelines configured with at least one node that emits structured log output

## Setup Instructions

1. Select _Log Type_ — currently `pipeline` is the only supported log source
2. Optionally select one or more _Log Levels_ to watch (e.g. `error`, `fatal`). At least one level or a message filter must be set — a rule with neither will never fire
3. Optionally configure a _Message Filter_ to match on the log's message field using a substring, prefix, suffix, or regular expression
4. Set a _Dedupe Window_ to control how frequently the same pipeline node can re-fire the alert (default: `1h`)

## Configuration Options

### Settings
| Setting | Type | Required | Default | Description |
|---------|------|----------|---------|-------------|
| log_type | string | Yes | `pipeline` | Log source to evaluate. Currently only `pipeline` is supported. |
| levels | array of strings | No | _(none)_ | Alert when a log matches any of these severity levels. Valid values: `debug`, `info`, `warn`, `error`, `fatal`. At least one level or a message filter must be configured. |
| message_filter | object | No | _(none)_ | Optional filter applied to the log's `msg` field. See Message Filter below. |
| dedupe_window | string | No | `1h` | Minimum time between repeated alerts for the same pipeline node. Must be one of `5m`, `30m`, `1h`. |

### Dedupe Window Options
| Value | Description |
|-------|-------------|
| `5m` | 5 minutes |
| `30m` | 30 minutes |
| `1h` | 1 hour |

### Message Filter
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| operator | string | No* | How to match the message value. One of: `contains`, `starts_with`, `ends_with`, `matches_regex`. |
| value | string | No* | The string or regular expression pattern to match against the message. |

\* `operator` and `value` must be set together — providing one without the other is a validation error.

## Alert JSON Format

When a log event matches the configured conditions, the alert generates the following JSON structure:

```json
{
  "rule_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Schema Mismatch Alert",
  "organization_id": "org-123",
  "severity": "critical",
  "description": "Log alert 'Schema Mismatch Alert' matched on pipeline pipeline-abc-123 node node-xyz-456",
  "metadata": {
    "pipeline_id": "pipeline-abc-123",
    "node_id": "node-xyz-456",
    "log_level": "error",
    "message": "schema mismatch: expected field 'event_type' not found",
    "log_type": "pipeline"
  },
  "resource": {
    "resource_type": "pipeline",
    "resource_id": "pipeline-abc-123"
  }
}
```

### Alert Metadata Fields
- **pipeline_id**: The ID of the pipeline whose node emitted the matching log
- **node_id**: The ID of the specific node that emitted the log
- **log_level**: The severity level of the matched log event
- **message**: The log message that triggered the alert
- **log_type**: The log source type (`pipeline`)

## Use Cases
- **Error Detection**: Get notified immediately when any pipeline node logs an `error` or `fatal` event, rather than waiting for a metric threshold to be breached
- **Schema Mismatch Monitoring**: Alert the moment a transform or enrichment node logs a schema mismatch or unexpected field, catching data quality issues before they propagate
- **Authentication Failure Alerting**: Trigger on any `auth failure` or `unauthorized` message from an input node as soon as it happens
- **Connection Issue Detection**: Use `matches_regex` to catch a family of related messages — e.g. `connection (refused|timed out|reset)` — across all pipeline nodes with a single rule
- **Noise Reduction**: Combine level and message filters to target only the specific log events that require action, avoiding alert fatigue from routine informational logs

## Limitations
- Only `pipeline` logs are supported as a log source at this time
- `dedupe_window` must be one of `5m`, `30m`, or `1h`
- A rule with no levels and no message filter will never fire — at least one filter must be set
- `message_filter` requires both `operator` and `value` to be set together, or neither
- Each level value in `levels` must be unique — duplicates are rejected at rule creation

## Example Configurations

### Alert on any error or fatal log
```json
{
  "log_type": "pipeline",
  "levels": ["error", "fatal"],
  "dedupe_window": "5m"
}
```
Fires immediately when any pipeline node emits an `error` or `fatal` log, with a 5-minute dedupe window per node.

### Alert on schema mismatch errors
```json
{
  "log_type": "pipeline",
  "levels": ["error"],
  "message_filter": {
    "operator": "contains",
    "value": "schema mismatch"
  },
  "dedupe_window": "30m"
}
```
Fires when an error log containing "schema mismatch" is emitted, with a 30-minute dedupe window per node.

### Alert on authentication failures
```json
{
  "log_type": "pipeline",
  "levels": ["warn", "error"],
  "message_filter": {
    "operator": "contains",
    "value": "auth failure"
  },
  "dedupe_window": "5m"
}
```
Fires on the first `warn` or `error` log mentioning "auth failure", re-alerting at most every 5 minutes per node.

### Alert on connection-related errors using regex
```json
{
  "log_type": "pipeline",
  "levels": ["error"],
  "message_filter": {
    "operator": "matches_regex",
    "value": "connection (refused|timed out|reset)"
  },
  "dedupe_window": "30m"
}
```
Catches any of several connection error variants with a single rule, firing at most once every 30 minutes per node.