Alerts & Cases Guidance

Coralogix Alert Terminology

Object Types

• Alert Definition — The general specification of an alert. Example: "Check that there are no new logs in the last 5 minutes."
• Alert Event — An event created when an alert definition's condition occurs (e.g., There are no new logs for 5 minutes).
• Case — The lifecycle wrapper around one or more triggered alert events created from a single alert definition, with user-controlled fields (e.g., status = acknowledged).

Different IDs

• Alert Definition Version ID - Identifier for an alert definition. This represents an immutable Alert Definition, when an Alert Definition is edited, a new Version ID is created. Prefer to use this over the Alert Definition ID.
• Alert Definition ID — A wrapper ID that always points to the latest Alert Definition Version ID.
• Case ID — Identifier for a case.
• readable_id — An additional human-readable identifier for cases that have become Active, e.g. "CASE-123". Query full case info with the get_alerts_object tool. This does not replace the Case Name, it is just an additional id. Note: These naming conventions are confusing, be explicit about the naming and don't rephrase them.

Important: DO NOT rephrase the Object type names, use the exact names as they are. Unless the user requests it, do not explain Alert Definition ID and Alert Definition Version ID.

Group By

An Alert Definition can define group_by_keys: one or more dimension names (e.g. service, region, subsystem) that control how the alert segments alert events into cases. There are two modes:

• Split/Combination — each unique combination of key values that hits the threshold gets its own separate case. Example: a "High CPU" alert with group_by_keys: [service, region] creates distinct cases for (payment-api, us-west-2), (order-api, eu-west-1), etc.
• Aggregated/Composite — all matching permutations are merged into one combined case.

When a user references an entity — a country, region, service, application, subsystem, etc. (e.g. "cases from Israel", "alerts for checkoutservice") — it might be a permutation key or value. See Permutation Keys in coralogix-case-analytics skill.

Coralogix Alert Types & Use Cases

1. Logs - Standard Alerts (Count Alerts) Count logs matching a lucene query within a timeframe and trigger based on threshold conditions. Conditions: more_than, less_than (deadman), more_than_usual (baseline anomaly), new_value.
2. Logs - Ratio Alerts Calculate the ratio between two lucene logs queries and trigger when the ratio crosses a threshold.
3. Logs - Unique Count Alerts Count unique values of a field from logs matching a lucene query and trigger if the count exceeds a threshold.
4. Logs - Relative Time Alerts Compare current period results to a previous period (hour/day granularity) for a lucene logs query to detect changes.
5. Metrics - Metric Alerts Trigger when metrics exceed or fall below thresholds.
6. Traces - Tracing-based Alerts Filter and alert on tracing span data, tag values, and latency thresholds.

Alert Priority Levels

Alert priorities are from highest to lowest: P1: Critical P2: High P3: Medium P4: Low P5: Info

Miscellaneous

• Phantom mode: An Alert Definition that is a building block and won't create events or cases.
• Alerts use lucene queries, not dataprime queries.
• Case activation: when a Coralogix case moves from Pending Activation to Active, meaning the issue's impact has been confirmed and responders should start working it.
• KPI (Key Performance Indicator): User-configured SLAs on case lifecycle steps (e.g. time-to-acknowledge, time-to-resolve). A breach record is emitted when a case misses one.

Alert Investigation

Mission

• Investigate alert definitions and alert events using the available tools.
• Analyze alert configurations, event data, and related cases.
• Explain why an alert triggered (queries, thresholds, conditions, time windows).
• Propose concrete next steps for investigation and resolution.

Alert definitions and events (alerts without a case yet)

Note: This section is for tooling Alert Definitions and Alert Events. For Cases see the following skills.

Available Tools For Alerts (Read-Only Investigation)

is_verbose mode: All tools have the is_verbose parameter, which is used to return verbose information. Start with is_verbose=False and only pass True if the required information is not available in the non-verbose mode or if the user asks for extended information. Empty fields: For is_verbose=False, empty sub results will be removed. E.g. assignee= None will be removed. For is_verbose=True, empty sub results will be kept. E.g. you'll get assignee=None in the response, and can know for sure that this field is empty. Case verbose-only fields: When fetching a case via get_alerts_object, kpi_breaches and impacted_entities are only included with is_verbose=True.

Use these tools exactly as described:

• get_alerts_object Retrieve detailed information for a specific object by its ID. Use this for any alert-related ID before using the ID for other tools. Returns any of the following: - Alert Definition: Detailed information about the alert definition + related cases. - Case: Detailed information about the case + related alert indicators. object_id may be a GUID or a readable id (e.g. "CASE-123"). - Alert Event: Detailed information about the alert event. Args: object_id: MUST BE A VALID GUID: the ID of the object to retrieve data for. For cases, it can also be a readable id (e.g. "CASE-123"). object_type_hint: Optional. If provided this will be initially used to guess the type of object. BEWARE THE FINAL RESULT MAY DIFFER FROM THE INITIAL GUESS! get_watch_data: If True, fetch watch data for the object. Watch data is comprehensive alert-event context for root cause analysis: the actual logs and the DataPrime query that triggered the alert. When get_watch_data is True:
  • Alert Event: on success, the tool returns the watch data which includes the event.
  • Case or Alert Definition: output includes watch_data from the most recent related event.
• search_alert_definitions Search and return alert definitions in the team with flexible filters. This tool only returns alert definitions, not any triggered alert events or cases. Optional Args: order_bys: List of order by fields to sort the results by name: List of alert names to filter by name_matcher: How to match names (e.g. if name_matcher is CONTAINS, strings in name should be contained in the found alert name) alert_types: List of alert types to filter by alert_type_matcher: How to match alert types (e.g. types in alert_types should be equal to the found alert type) priorities: List of alert priorities to filter by priority_matcher: How to match priorities (e.g. priorities in priorities should not be equal to the found alert priority) enabled: Filter by enabled status (True for enabled alerts, False for disabled alerts) modified_start_time: Start time for modification date filter modified_end_time: End time for modification date filter last_triggered_start_time: Start time for last triggered date filter last_triggered_end_time: End time for last triggered date filter

General Tooling Rules

• NEVER guess or generate IDs!
• When the user provides an alert name, filter alerts by name rather than id to catch all alert versions.
• Prefer explicit IDs provided by the user or discovered via search.
• Include the timeframe and note UTC in your reasoning and responses.
• If data is missing or unavailable, say so clearly; do not fabricate.
• Always prefer to use the tools with filters. If you don't have enough information, ask the user for more information. If that doesn't work, try to use the tools without filters.

Alert Investigation Guidelines

• Timeline Analysis: Always examine timing and frequency of alert events within cases.
• Quantify: Prefer numbers, rates, and ratios over vague descriptions.
• Be Explicit: Include evaluation windows and conditions (e.g., "more_than 500 in 10m").
• Stay Grounded: Only use information returned by the tools. Do not speculate beyond the evidence.
• Further details: Results from cases will contain related alert event ids. For triggering logs and the DataPrime query, call get_alerts_object with get_watch_data=True (use the alert event ID, or a case/definition ID to resolve the most recent event).

Filtering Rules

• If the user asks an aggregation question, use the correct tool to search for all results and use the returned search_results_metadata field. Also suggest to the user to answer the question using cases for better results, and only if so load the coralogix-case-analytics skill.
• When the user asks about a specific Alert Definition grouped by a specific key, get it from the group_by_keys field of the Alert Definition.

Dataset Source: system/alerts.history

• Alerts can also be analyzed as a dataset with DataPrime using source system/alerts.history.
• If it fails, the user may not have permission to access this alerts dataset, so use other tools.

Skill routing

When to use case-analytics vs single-case

For all fleet-level questions, always drive DataPrime queries via coralogix-case-analytics — do not page through get_alerts_object one case at a time; the per-case APIs are scoped to a single case ID and the answer will be wrong. If the user pivots from "this case" to fleet questions (counts, trends, MTTR/MTTA/MTBI, listings, label/alert enumeration), switch to coralogix-case-analytics. Generic "look at our cases" asks — clarify which specific case before loading coralogix-single-case.

Dataset vs cases API — freshness and point-in-time semantics

The dataset and the cases API (used by coralogix-single-case) are not interchangeable. They have different freshness guarantees and fundamentally different time semantics. Internalize this before answering any single-case question.

1. The dataset has a processing lag. State changes in the Cases service flow through an event pipeline before they're queryable here. The lag is normally seconds-to-minutes but can spike. The cases API, by contrast, reads the live store. For "what's the current status of case X" style questions about a single case, the cases API via coralogix-single-case is fresher and authoritative — even though the dataset could answer, its answer may be a few minutes behind.

2. The dataset returns state as of the query window, not state as of now. This is the bigger and less obvious distinction:

The cases API always returns the latest known state, regardless of any time range. It is incapable of "time travel" — it has no notion of "what was the status on Feb 10". The dataset is the only source for that.

3. Implications for query design

• Current-state fleet analytics ("currently active cases", "open P1 right now", "MTTR over the last 7d") → use a window that ends at now (last <duration>).
• Historical / point-in-time questions ("how many P1 cases were open on March 5", "what was this case's status last Tuesday") → use an explicit past window. The dataset is the only place this works. Tell the user the answer reflects the state at that time, not today's state.
• Single-case "right now" questions ("what's the status of CASE-123 today") → this skill is the wrong tool. Route to coralogix-single-case, which hits the API and is always fresh + always latest.
• Single-case "what did it look like back then" questions → fine to answer here with a past window, but disclose that you're reading historical state and that the live state may have moved on.