Skip to content
Telescope

Severity Rules

Since v0.0.24

Severity rules enable Docker and Kubernetes sources to extract and normalize severity information from log message bodies. Unlike ClickHouse sources that have dedicated severity columns, Docker and Kubernetes logs typically embed severity within the message text itself (e.g., {"level": "error"} or [ERROR] Connection failed).

Why severity rules?

Section titled “Why severity rules?”

Without severity rules:

  • Docker and Kubernetes logs appear without color coding
  • Severity-based graph grouping is not available
  • Log analysis lacks visual severity indicators

With severity rules:

  • Colored log bars indicate severity at a glance
  • Graph grouping by severity reveals patterns
  • Consistent visualization across all source types

How severity rules work

Section titled “How severity rules work”

Severity rules operate in two phases: extraction and remapping.

Phase 1: extraction

Section titled “Phase 1: extraction”

Extract severity from the raw message body using one of two methods:

JSON extraction

Section titled “JSON extraction”

Navigate nested JSON structure using comma-separated paths.

Example:

  • Path: log,level
  • Log: {"log": {"level": "warn"}, "timestamp": "2024-01-01"}
  • Extracted: "warn"

JSON extraction is useful for structured logging formats where severity is embedded in a JSON field.

Regex extraction

Section titled “Regex extraction”

Match patterns with optional capture groups.

Example:

  • Pattern: \[(\w+)\]
  • Capture group: 1
  • Log: [ERROR] Connection failed
  • Extracted: "ERROR"

Regex extraction is useful for plain text log formats where severity appears in the message text. Capture groups allow you to extract specific parts of the match:

  • Group 0 = full match (e.g., [ERROR])
  • Group 1 = first capture group (e.g., ERROR)
  • Group 2+ = additional capture groups if defined

Case-insensitive matching: Available as an option for regex rules.

Evaluation order

Section titled “Evaluation order”

Rules are evaluated in the order defined. The first rule that successfully extracts a value wins, and remaining extraction rules are skipped.

This allows you to define multiple rules as fallbacks:

  1. Try JSON extraction first
  2. If that fails, try regex pattern matching
  3. If all rules fail, severity defaults to UNKNOWN

Phase 2: remapping (optional)

Section titled “Phase 2: remapping (optional)”

Map extracted values to normalized severity levels using regex pattern matching.

Pattern matching

Section titled “Pattern matching”

Remap rules use regex patterns to match extracted values:

Example:

  • Pattern: warn.*
  • Extracted value: "warning"
  • Normalized to: "WARN"

Characteristics:

  • Patterns are evaluated as regex (e.g., error|err|e matches any of these)
  • Patterns use fullmatch semantics (must match entire extracted value)
  • Case-insensitive matching available per rule
  • First matching pattern wins (evaluation order matters)

Normalized severity levels

Section titled “Normalized severity levels”

Telescope recognizes eight standard severity levels for visualization:

LevelColorTypical Use
UNKNOWNGrayDefault when extraction fails or no match
FATALRedFatal errors causing application shutdown
ERRORRedError conditions requiring attention
CRITICALOrangeCritical conditions
WARNYellowWarning messages
INFOBlueInformational messages
DEBUGGreenDebug information for development
TRACEGrayDetailed trace information

Fallback behavior

Section titled “Fallback behavior”

If no remap rule matches, the extracted value is used as-is. This allows custom severity levels while still benefiting from extraction and visualization.

Configuration

Section titled “Configuration”

Severity rules are configured during source creation or editing in the source wizard:

  1. Extraction rules: Define one or more rules to extract severity from message bodies

    • Choose between JSON field extraction or regex pattern matching
    • Order rules from most specific to most general

  2. Remap rules: Optionally normalize extracted values to standard levels

    • Use regex patterns for flexible matching
    • Order patterns from most specific to most general
    • Enable case-insensitive matching as needed

See the Source Configuration UI for step-by-step UI instructions and the Severity Rules How-to Guide for practical examples.

Benefits

Section titled “Benefits”
  • Consistent visualization: All log sources can have consistent severity-based coloring and grouping, regardless of how severity is stored
  • Flexible extraction: Support both structured (JSON) and unstructured (plain text) log formats from the same source
  • Normalization: Convert varied severity naming conventions (error/err/ERROR/3) to standard levels for easier analysis
  • Visual analysis: Colored log bars and graph grouping make it easy to spot error patterns and severity trends at a glance
Section titled “Related documentation”