- 快猫星云Flashcat

Script processor — run a custom shell script to flexibly transform alert events.

Overview

The Script event processor is a powerful component for handling alert events: it lets you run a custom script to flexibly process and transform alert events. The processor passes the alert event as JSON to your script via stdin, and the script can return the modified event data.

Parameters

Timeout (required)

Name: Timeout
Unit: milliseconds (ms)
Default: 10000 (10 seconds)
Description: maximum execution time for the script. If the script exceeds this limit, it is force-killed and the original event is returned.

Script content (required)

Name: Script content
Format: shell script
Description: the custom script code you want to run to handle alert events.

How It Works

Event input: the processor converts the current alert event to JSON and pipes it to the script via stdin
Script processing: your script reads the event JSON from stdin and processes it
Result output: the script writes the modified event JSON to stdout
Event update: the processor parses the script output and updates the original event

Common scenarios

Modify alert severity
Add custom labels
Modify alert description

Notes

1. Script requirements

The script must read JSON data from stdin
The script must output valid JSON to stdout

2. Error handling

If the script fails or times out, the original unmodified event is returned
If the script output is empty or invalid JSON, the original event is returned

3. Performance

Set the timeout reasonably to avoid impacting alert handling performance
Avoid running overly complex operations inside the script

4. Security

Be careful with external input inside the script
Avoid running unsafe system commands
Periodically review the script content

Testing Tips

Use the test feature: before saving, click the “Test” button to verify script behaviour
Local testing: simulate an event JSON locally to test the script
Iterate: start with a simple script and progressively add logic

Example Scripts

Example 1: pass-through

#!/bin/bash

# 读取输入事件
event_json=$(cat)
echo "$event_json"

Example 2: bump severity based on a label

#!/bin/bash
event_json=$(cat)

# 用 jq 检查标签里有没有 critical
is_critical=$(echo "$event_json" | jq -r '.tags_map.env // empty')

if [ "$is_critical" = "prod" ]; then
  # 把 prod 环境的告警级别提升到 1（S1）
  echo "$event_json" | jq '.severity = 1'
else
  echo "$event_json"
fi

Example 3: add custom labels

#!/bin/bash
event_json=$(cat)
echo "$event_json" | jq '.tags_map.processed_by = "ops-script-v2" | .tags_map.processed_at = (now | tostring)'

FAQ

Q1: Can the script call external commands (curl / kubectl / aws-cli)?

A: Yes — the script runs in the standard shell of the host where n9e-server runs. Preconditions:

The required commands are already installed on the server host;
The script process has sufficient user privileges (n9e by default uses the account that launched the server);
The commands have the necessary network reachability (e.g. kubectl needs kubeconfig properly configured).

Strongly suggested: install the tooling explicitly on the server deployment host — do not assume commands are present.

Q2: How do I debug a failing script?

Use the “Test” button on the page (provide a sample event JSON);
Check stderr output in the Execution Records;
In the script, use echo "DEBUG: xxx" >&2 to write debug info to stderr (it will not pollute the JSON on stdout);
Locally simulate: cat sample.json | bash your-script.sh.

Q3: What happens if the script output is not JSON or is corrupted?

A: The processor ignores the script output and continues with the original event. So a broken script will not lose alerts, but it also means your modifications had zero effect. Test coverage is essential.

Q4: Are Python / Node.js scripts supported?

A: Technically yes — as long as the shebang line (e.g. #!/usr/bin/env python3) points at an interpreter installed on the server host. Mind performance: forking an interpreter on every alert is non-trivial; slow scripts will be killed at timeout. For simple logic, prefer bash + jq.