# How to Customize Event Severity Levels and Alert Thresholds in LogSentinelAI

> Learn to customize event severity levels and alert thresholds in LogSentinelAI. Control Telegram alerts and sampling limits using environment variables and CLI flags for tailored monitoring.

- Repository: [JungJungIn/logsentinelai](https://github.com/call518/logsentinelai)
- Tags: how-to-guide
- Published: 2026-02-26

---

**LogSentinelAI uses environment variables and CLI flags to control Telegram alert thresholds via `TELEGRAM_ALERT_LEVEL` and realtime sampling limits via `REALTIME_SAMPLING_THRESHOLD`, while severity classifications are defined per analyzer in the `SeverityLevel` enum.**

LogSentinelAI classifies every detected anomaly using a hierarchical severity system that drives alerting logic and operational workflows. Understanding how to customize event severity levels and alert thresholds in LogSentinelAI allows operators to tune noise levels, reduce alert fatigue, and align automated responses with organizational incident management policies. The configuration mechanism relies on a combination of environment variables in [`core/config.py`](https://github.com/call518/logsentinelai/blob/main/core/config.py), priority mappings in [`core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/core/elasticsearch.py), and optional source-level extensions to analyzer enums.

## Understanding LogSentinelAI Severity Levels

LogSentinelAI attaches a severity classification to every `LogEvent` processed by its analyzers. This value determines whether the event triggers external notifications and how it ranks against other events in the pipeline.

### The SeverityLevel Enum

Each analyzer defines its available severity values through the `SeverityLevel` enum. For example, the General Log analyzer in [`src/logsentinelai/analyzers/general_log.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/analyzers/general_log.py) implements a five-tier scale:

```python

# src/logsentinelai/analyzers/general_log.py

class SeverityLevel(str, Enum):
    CRITICAL = "CRITICAL"
    HIGH = "HIGH"
    MEDIUM = "MEDIUM"
    LOW = "LOW"
    INFO = "INFO"

```

The `LogEvent` Pydantic model stores this classification in its `severity` field:

```python

# src/logsentinelai/analyzers/general_log.py

class LogEvent(BaseModel):
    severity: SeverityLevel          # ← severity attached to each event

```

### Numeric Priority Mapping

When determining whether to send a Telegram alert, the system converts textual severity labels into numeric priorities where lower numbers indicate higher urgency. This mapping is handled by the `get_severity_priority` function in the Elasticsearch handler:

```python

# src/logsentinelai/core/elasticsearch.py

def get_severity_priority(severity: str) -> int:
    severity_map = {
        "CRITICAL": 1,
        "HIGH": 2,
        "MEDIUM": 3,
        "LOW": 4,
        "INFO": 5
    }
    return severity_map.get(severity.upper(), 999)

```

## Configuring Alert Thresholds

The **alert threshold** represents the minimum severity required to trigger a Telegram notification. LogSentinelAI evaluates this threshold during the event filtering phase before dispatching messages.

### Telegram Alert Level Environment Variable

The global configuration variable `TELEGRAM_ALERT_LEVEL` controls the cutoff severity. By default, only `CRITICAL` events generate alerts, as defined in [`src/logsentinelai/core/config.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/config.py):

```python

# src/logsentinelai/core/config.py

TELEGRAM_ALERT_LEVEL: str = os.getenv("TELEGRAM_ALERT_LEVEL", "CRITICAL").upper()

```

To customize this threshold, export the environment variable before starting the application:

```bash

# Trigger alerts for HIGH and above

export TELEGRAM_ALERT_LEVEL=HIGH

```

Alternatively, add the variable to your `.env` or `.env.template` file for persistent configuration.

### Alert Filtering Logic

During alert creation, LogSentinelAI compares the numeric priority of each event against the configured threshold. The filtering logic in [`src/logsentinelai/core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/elasticsearch.py) performs the following check:

```python

# src/logsentinelai/core/elasticsearch.py

alert_threshold_priority = get_severity_priority(TELEGRAM_ALERT_LEVEL)
event_priority = get_severity_priority(event_severity)

if event_priority <= alert_threshold_priority:
    alert_events.append(event)

```

Events with a priority value less than or equal to the threshold are included in the Telegram notification payload.

## Adjusting the Sampling Threshold

In addition to severity-based alerting, LogSentinelAI can automatically switch to **sampling mode** when log volume exceeds operational limits. This prevents processing backlogs during traffic spikes.

### Environment Variable vs CLI Flag

The sampling threshold is configurable through two mechanisms:

1. **Environment Variable**: Set `REALTIME_SAMPLING_THRESHOLD` in [`src/logsentinelai/core/config.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/config.py) (default: 100):

```python

# src/logsentinelai/core/config.py

"sampling_threshold": int(os.getenv("REALTIME_SAMPLING_THRESHOLD", "100")),

```

2. **Command-Line Flag**: Override via `--sampling-threshold` defined in [`src/logsentinelai/core/commons.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/commons.py):

```python

# src/logsentinelai/core/commons.py

parser.add_argument('--sampling-threshold', type=int, default=None,
                    help='Auto-switch to sampling if accumulated lines exceed this (only for full mode)')

```

When the accumulated `pending_lines` counter exceeds this value, the monitoring component in [`src/logsentinelai/core/monitoring.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/monitoring.py) automatically transitions the pipeline to sampling mode.

### Practical Examples

Raise the threshold to 300 lines using either method:

```bash

# Method 1: Environment variable

export REALTIME_SAMPLING_THRESHOLD=300

# Method 2: CLI flag for a single execution

logsentinelai --mode realtime --sampling-threshold 300

```

## Extending Severity Levels (Optional)

If the default five-tier severity scale does not match your operational taxonomy, you can extend the classification system by modifying the analyzer source and priority map.

Add a custom level (e.g., `NOTICE`) to the analyzer enum:

```python

# src/logsentinelai/analyzers/general_log.py

class SeverityLevel(str, Enum):
    CRITICAL = "CRITICAL"
    HIGH = "HIGH"
    MEDIUM = "MEDIUM"
    LOW = "LOW"
    INFO = "INFO"
    NOTICE = "NOTICE"   # ← new level

```

Then update the priority mapping in the Elasticsearch handler to assign a numeric rank:

```python

# src/logsentinelai/core/elasticsearch.py

def get_severity_priority(severity: str) -> int:
    severity_map = {
        "CRITICAL": 1,
        "HIGH": 2,
        "MEDIUM": 3,
        "LOW": 4,
        "INFO": 5,
        "NOTICE": 4   # choose rank between LOW and INFO

    }
    return severity_map.get(severity.upper(), 999)

```

## Summary

- **Severity classifications** are defined in analyzer-specific `SeverityLevel` enums (e.g., [`src/logsentinelai/analyzers/general_log.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/analyzers/general_log.py)) and stored in the `severity` field of `LogEvent` models.
- **Alert thresholds** are controlled by the `TELEGRAM_ALERT_LEVEL` environment variable, which defaults to `CRITICAL` and filters events via numeric priority comparison in [`src/logsentinelai/core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/elasticsearch.py).
- **Sampling mode triggers** when `pending_lines` exceeds `REALTIME_SAMPLING_THRESHOLD` (default 100), configurable via environment variable or the `--sampling-threshold` CLI flag in [`src/logsentinelai/core/commons.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/commons.py).
- **Custom severity levels** require extending both the analyzer enum and the `get_severity_priority` mapping in [`src/logsentinelai/core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/elasticsearch.py).

## Frequently Asked Questions

### How do I reduce alert noise from LogSentinelAI?

Set the `TELEGRAM_ALERT_LEVEL` environment variable to `HIGH` or `MEDIUM` to suppress notifications for lower-severity events. According to the source code in [`src/logsentinelai/core/config.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/config.py), the system defaults to `CRITICAL`, so raising the threshold filters out less urgent events before they reach Telegram.

### What happens if I set TELEGRAM_ALERT_LEVEL to an invalid severity?

The `get_severity_priority` function in [`src/logsentinelai/core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/elasticsearch.py) returns `999` for unknown severities. Since this value exceeds all standard priorities (1-5), no events will match the filter condition `event_priority <= alert_threshold_priority`, effectively disabling all Telegram alerts.

### Can I use different alert thresholds for different analyzers?

The current implementation uses a global `TELEGRAM_ALERT_LEVEL` variable applied uniformly across all analyzers. To implement analyzer-specific thresholds, you would need to modify the alert filtering logic in [`src/logsentinelai/core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/elasticsearch.py) to check the event source or analyzer type before applying the priority comparison.

### Where does LogSentinelAI check the sampling threshold during execution?

The monitoring component in [`src/logsentinelai/core/monitoring.py`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/core/monitoring.py) evaluates `self.pending_lines` against the configured threshold at line 348. When the accumulated line count exceeds this value, the system automatically switches from full processing to sampling mode to maintain performance.