Skill: Import Prometheus Alert Rules

Overview

Bulk-create Prometheus official rule YAML (in any of the three forms: with groups, a plain rules array, or a single rule) into n9e. Typical sources:

• A remote URL (e.g. awesome-prometheus-alerts on GitHub raw)
• YAML text pasted directly by the user

The workflow is a fixed four steps: fetch YAML to a file → choose business group + datasource → preview → write to DB.

⚠️ Core constraint: the YAML file does not enter the LLM context. http_fetch with save_to_file=true writes the content to a temporary file, and the subsequent preview_prom_rule_yaml and import_prom_rule_yaml both read that path via payload_file. The file size can range from a few KB to a few MB; letting it enter the prompt would significantly slow things down, increase cost, and make it easy for the LLM to truncate or rewrite it.

Available Tools

Execution Steps

Step 1: Fetch the YAML to a temporary file

User gave a URL — always include save_to_file=true:

http_fetch(url="https://.../node-exporter.yml", save_to_file=true)

The return is:

{"status_code":200,"content_type":"text/plain","size":8731,"truncated":false,
 "file_path":"/var/folders/.../n9e-aiagent-fetch-xxx.yml"}

Remember the file_path; the last two steps both need it.

User pasted YAML text directly — skip http_fetch and pass the text directly as the payload argument of the subsequent tools (in this case the YAML is already in the context anyway, so there is no point writing it to disk).

Error handling:

• truncated=true means it exceeds max_bytes (default 1 MiB). Call http_fetch(url=..., save_to_file=true, max_bytes=8388608) again (8 MiB is the hard upper limit).
• status_code not 2xx: tell the user the status code and ask whether to try another URL.
• Errors like "blocked: ... resolves to non-public address": the user gave an intranet address; ask the user to paste the YAML content directly.

Step 2: Choose the business group and datasource

Call concurrently (do not serialize):

• list_busi_groups() to list visible business groups. Prefer the one with is_default=true; if there is only one, use it directly; if there is more than one, use AskUserQuestion to let the user choose
• list_datasources(plugin_type="prometheus") to list Prom datasources. If there is only one, use it directly; if more than one, let the user choose

If the user's request already specifies a business group name / datasource name, match by name and use it directly without asking again.

Step 3: Preview

preview_prom_rule_yaml(payload_file=<file_path from step 1>)

The return is {total, items:[{name, severity, prom_ql, for_duration_sec, append_tags, annotations}]}.

Keep the report to the user short — listing the first 3-5 rules plus the total is enough; do not list every rule:

Parsed 38 rules (critical 9 / warning 27 / info 2), for example:

• HostHighCpuLoad (warning, for=0s)
• HostOutOfMemory (warning, for=2m)
• HostOomKillDetected (warning, for=0s) Import all of them into the Prometheus datasource "prom-prod" of business group "default"?

Step 4: Write to the DB

After the user confirms:

import_prom_rule_yaml(
  group_id=<from step 2>,
  datasource_ids="[<ds id from step 2>]",
  payload_file=<file_path from step 1>
)

datasource_ids must be a JSON array string, e.g. "[1]" or "[1,3]".

The return structure:

{
  "total":   38,
  "created": 36,
  "skipped": 2,        // duplicate-name rules, automatically skipped, not a failure
  "failed":  0,        // real write errors (DB/validation, etc.)
  "items": [
    {"name":"HostHighCpuLoad", "status":"skipped_duplicate"},
    {"name":"HostOutOfMemory", "status":"created", "id":177},
    {"name":"BadOne", "status":"failed", "error":"<message>"}
  ]
}

Each rule's status is one of three:

• created — created successfully, has an id
• skipped_duplicate — a rule with the same name already exists, no change was made, no retry needed
• failed — a real error (DB, validation, etc.); see error

Handling duplicate names (important)

⚠️ A rule with the same name is automatically skipped (status=skipped_duplicate), not a failure. When you see skipped > 0, never "retry the whole YAML" with name_prefix — that would create a prefixed duplicate of all the N rules that were already created successfully, doubling the data and polluting it.

The correct way to report: just tell the user which rules were skipped due to duplicate names, and let the user decide what to do:

✅ Imported 36 rules. Another 2 were skipped because rules with the same name already exist: HostHighCpuLoad, HostOutOfMemory. If you want to overwrite them, go to the alert rules page, delete the old ones, and re-import; if you want the old and new ones to coexist (e.g. for comparison testing), you can re-import with name_prefix, but be aware that all 38 rules will be prefixed.

Only use name_prefix/name_suffix when the user explicitly requests coexistence (a very rare comparison-testing scenario), and inform the user in advance that the LLM will prefix all of the rules.

Only real failures (status=failed) need investigation

If status=failed appears, look at the error field: common cases include datasource validation failure, field format errors, etc. These are problems with the YAML itself or the environment; name_prefix cannot fix them.

Cautious mode

User says "create them but don't enable them yet" → pass disabled=1.

Step 5: Output the result

Keep it short:

✅ Imported 36 alert rules into business group "default". ⚠️ 2 were skipped because rules with the same name already exist: HostHighCpuLoad, HostOutOfMemory. To overwrite, manually delete the old rules on the alert rules page, then re-import.

Do not list all 36 rule IDs; the frontend will display them as cards. Do not proactively suggest "retry with name_prefix" — unless the user explicitly wants coexistence.

How to choose between payload and payload_file

Pick one of the two; you cannot pass both (the tool will error).

severity mapping (automatic)

The tool automatically maps the labels.severity string to n9e's number:

No manual conversion by the LLM is needed.

Handling of other labels

All labels other than severity are automatically assembled into n9e's append_tags (format k=v, spaces are stripped).

Common Pitfalls

1. datasource_ids must be a JSON array string: pass "[1]", not "1" or 1.
2. http_fetch cannot fetch from the intranet: a http://10.x.x.x/... URL given by the user will be rejected outright. Ask the user to use a public URL or paste the content directly.
3. payload_file must be one written by http_fetch: the tool validates that the path is under os.TempDir() and starts with n9e-aiagent-fetch-. An arbitrary path cannot be used.
4. The expr in the YAML is stored verbatim: n9e stores the original expression directly (including thresholds); do not have the LLM split the >/< and the threshold.
5. The for field is converted to seconds: 5m → 300, 1h → 3600. If the original YAML has no for, n9e uses 0 seconds (triggers immediately).
6. Do not query list_alert_rules to detect duplicate names. Call import directly and decide whether to retry with a prefix based on the returned error.

Example Conversation

User: Help me import https://raw.githubusercontent.com/samber/awesome-prometheus-alerts/refs/heads/master/dist/rules/host-and-hardware/node-exporter.yml

Thought → Concurrently fetch the URL (save to file) + list business groups + list datasources.

Action 1: http_fetch(url="https://...", save_to_file=true) → {file_path: "/var/.../n9e-aiagent-fetch-abc.yml", size: 8731, ...} Action 2: list_busi_groups() → only default Action 3: list_datasources(plugin_type="prometheus") → only prom-prod

Action 4: preview_prom_rule_yaml(payload_file="/var/.../n9e-aiagent-fetch-abc.yml") → 38 rules

Final answer (preview stage):

Parsed 38 rules... Import them into business group "default" / datasource "prom-prod"?

User: Yes

Action 5: import_prom_rule_yaml(group_id=1, datasource_ids="[2]", payload_file="/var/.../n9e-aiagent-fetch-abc.yml")

Final answer:

✅ Imported 38 alert rules into "default / prom-prod".