How to Customize Event Severity Levels and Alert Thresholds in LogSentinelAI

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, priority mappings in 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 implements a five-tier scale:

# 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:

# 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:

# 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:

# 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:

# 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 performs the following check:

# 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 (default: 100):

# 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:

# 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 automatically transitions the pipeline to sampling mode.

Practical Examples

Raise the threshold to 300 lines using either method:

# 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:

# 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:

# 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) 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.
• 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.
• Custom severity levels require extending both the analyzer enum and the get_severity_priority mapping in 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, 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}