---
name: sparklogs-ask
description: Query SparkLogs logs and device health/state over time to answer what happened on a host or across a fleet. Counts, timelines, disk, CPU, patches, Windows events, other system and application log events, installed software, collection health. Conversational answers from SparkLogs telemetry.
---

# SparkLogs Ask

Answer this question from SparkLogs telemetry. This is a conversation with the data, not an investigation report.

**WEL** means Windows Event Log.

No output template. No WHAT WAS NOT CHECKED catalog. Go as deep as the question needs. Follow-ups expected.

`sparklogs-investigate` is a cited system-condition summary with findings; offer when they want a written report. `sparklogs-analyze-cause` only after a summary exists.

## Investigation discipline

1. **Bounded discovery first:** capped structure tools before event payloads (`list_sources`, `query_scope_activity`, `describe_pattern`).
2. **Aggregate before detail:** counts and rank before `query_logs`.
3. **Cache before re-query:** `refine_query_result` on the cached slice when it already covers the question.

Tool decision tree and recipes: `references/guides/mcp-tool-decision-tree.md`.

## How to answer

Answer first, then stop. Hedge precisely ("not in this window", "not checked", "insufficient evidence"). Cite `query_url` (col) on facts. Reuse a short `external_investigation_id` (arg) until the topic changes.

**Questions that pick the path:** (e.g., what is on the box? what happened and when? one host or fleet? which symptom domain? is collection trustworthy?)

**Principles:** empty `sparklogs.*` fields = uncurated (not a health finding); completeness from feed reports only (`agent_complete_through` (col)); default to named scope; ask only on fuzzy identity (`match_kind` (col) ties, weak match, zero hits). Fleet hunt only when serious/shared and they agree.

Funnel, scope, LQL errors: `references/guides/mcp-tool-decision-tree.md`, `references/guides/scope-resolution.md`, `references/guides/lql-reference.md`. Stuck: `references/guides/common-mistakes.md`, `references/guides/stream-kinds.md`.

## Which tool (quick route)

- Standing / latest event of each episode → `query_device_health`, omit `view` (arg) (`fieldset` (arg) `rca` for one host; `min_severity` (arg) `warning` means that latest event is still warning or worse)
- Inventory / what is on the box → same tool, `view` (arg) `latest_state`
- Process CPU, memory or I/O trends → same tool, `view` (arg) `top_processes_over_time`, with `rank_by` (arg)
- Raw device measurements over time → same tool, `view` (arg) `series` with `topics` (arg); `view` (arg) `topics` discovers available topics and fields
- Episode series / RCA → same tool, `view` (arg) `event_timeline`, same `min_severity` (arg); peak in the window, then every in-window event of those episodes
- Counts, patterns, when → `query_event_counts_by_severity`, `describe_pattern`, `query_scope_activity`
- Named backup product installed → `query_device_health` first; job verdict in events, not VSS alone
- Raw event lines → `query_logs` last, then refine
- Collector debug → `sparklogs.agent.vector` / `sparklogs.agent.log` only

## Where to look

## Live tool reference

If server instructions are missing or terminology is unclear, call `server_info` with `include_instructions: true`.
For detailed views, fieldsets, aggregation or paging, call it with `describe_tool` (arg) naming the tool.
Use these references when the visible description leaves a question, not on every call.
Process charts use `query_device_health` with `view` (arg) `top_processes_over_time`.

## Curated data (read this before opening reference files)

- **`subsource` (LQL) = feed id.** Scope filters before `query_logs`: `service` (LQL) → `app` (LQL) → `subsource` (LQL) → `category` (LQL) → `pattern_hash` (LQL).
- **Curated events** carry `sparklogs.reason` (LQL), `sparklogs.class` (LQL), and module fields. Empty `sparklogs.*` on an event means **uncurated** (not a collection-health finding).
- **Reason** (`sparklogs.reason` (LQL)) = our curated vocabulary. **Vendor code** = NTSTATUS, HRESULT, MSI exit, Kerberos result, etc. **pattern_hash** (LQL) = stable shape id on every event.
- **Device row** (`query_device_health`, feed health, `agent_complete_through` (col)) is authoritative for collection and completeness. Event volume is not coverage.
- **Playbooks** = symptom recipes. **Themes** = investigation topic bundles (not customer marketing themes).

## What is in the pack

`playbooks/`, `themes/`, `references/feeds/<id>/` (`README.md`, `reasons.md`, `enums.md`, `fields.md`, `recipes.md`, `patterns.md` where present), `guides/`. Artifact choice detail: `references/guides/generated-reference-router.md`.

## After you pick a `subsource` (LQL)

1. Open `references/feeds/<id>/README.md` (short index).
2. **Stream kind** and exploration order: `references/guides/stream-kinds.md`. Classic WEL: `provider_name` (LQL) before `pattern` (LQL); device state: `query_device_health` with `sparklogs.kind` (LQL) / `sparklogs.topic` (LQL) / `sparklogs.reason` (LQL).
3. Open **one** artifact (read-mode table below). Rich feeds (especially `win.eventlog.security`) often need `recipes.md` or `reasons.md` first, not only `fields.md` or `enums.md`. Security also carries `patterns.md` and `mapping-ecs.md` / `mapping-ocsf.md` when shape or external taxonomy is the question.

**Reason meaning:** the `sparklogs.reason` (LQL) value and the event `message` (col) together; grep `reasons.md` for the matching `##` heading (summary table first, one section only).

## Decode tables (`enums.md`)

Per-feed closed vocabularies. **Grep** the code, constant, or `##` heading; never load a whole file.

| Kind | Typical feed | Use when |
|---|---|---|
| NTSTATUS / security status | `win.eventlog.security` | Logon/auth failure codes |
| Win32 / HRESULT | `win.eventlog.application`, `win.eventlog.system`, `win.eventlog.setup` | Servicing, app, VSS errors |
| MSI exit codes | `win.eventlog.application` | Installer failures |
| Logon types, WU result codes | `win.eventlog.security`, `win.eventlog.application` | Discriminate 4625/4624, update errors |

## How much to read

| Material | When | How |
|---|---|---|
| Playbook | Symptom matches index below | One file, whole |
| Theme | Investigation topic matches index | One file, whole |
| Feed `README.md` | You picked a `subsource` (LQL) | Whole (short index) |
| `reasons.md` | Need what a reason means | Skim summary table (~first 100 lines), then **one** `##` section |
| `enums.md` | Vendor/status code | **Search only** |
| `fields.md` | Filter/group on a field | Search for field name |
| `recipes.md` | Worked pivot for this feed | One section |
| `patterns.md` | Is this pattern string expected? | Search one heading (grammar/drift, not meaning) |
| Guides | Cross-cutting stuck point | One file from skill when→file table |

## Unfamiliar `pattern_hash` (LQL)

1. `describe_pattern` for text, examples, fleet spread.
2. Grep `references/feeds/<id>/reasons.md` or `recipes.md` if a reason or pivot is the question.
3. `patterns.md` only when the question is whether the pack meant to produce that string shape.

Routing indexes below. Open one file when the step needs it.

Playbooks are incomplete recipes. If a recipe LQL produces empty results: widen by `subsource` (LQL), then `references/guides/stream-kinds.md`, then raw logs.

**Playbooks** (symptom recipes):

| Symptom | File |
|---|---|
| Backup job failed | `references/playbooks/backup-failure.md` |
| BitLocker recovery | `references/playbooks/bitlocker-recovery.md` |
| Certificate expiry | `references/playbooks/certificate-expiry.md` |
| Directory replication | `references/playbooks/directory-replication-failure.md` |
| Disk full or filling | `references/playbooks/disk-full-or-filling.md` |
| Memory or handle leak | `references/playbooks/memory-or-handle-leak.md` |
| RAID / array degraded | `references/playbooks/raid-or-storage-degraded.md` |
| RMM connectivity | `references/playbooks/rmm-connectivity.md` |
| Slow logon | `references/playbooks/slow-logon.md` |
| Windows Update / patch failure | `references/playbooks/windows-update-failure.md` |
| VSS / shadow copies / backup plumbing | `references/playbooks/windows-vss.md` |

**Themes** (domain context):

| Topic | File |
|---|---|
| Patches / CBS / DISM / Setup | `references/themes/windows-updates-and-patching.md` |
| Who changed what (Security) | `references/themes/windows-security-and-audit.md` |
| Defender | `references/themes/endpoint-protection.md` |
| App / System crashes and services | `references/themes/windows-operational-events.md` |
| CPU, RAM, disk, installed software, monitors | `references/themes/device-health-and-state.md` |
| Named backup product (Veeam etc.): installed products. Not operational events. | `references/themes/device-health-and-state.md` |

**Data feeds** (`subsource` (LQL) = directory name). Follow **After you pick a `subsource` (LQL)** in the corpus block above.

| Feed | What | Path |
|---|---|---|
| `win.eventlog.security` | Security auditing: logons, account and policy changes, actors | `references/feeds/win.eventlog.security/` |
| `win.eventlog.system` | System channel: services, drivers, kernel, VSS, storage | `references/feeds/win.eventlog.system/` |
| `win.eventlog.application` | Application channel: app crashes, hangs, vendor app events | `references/feeds/win.eventlog.application/` |
| `win.eventlog.setup` | Windows Update results per update | `references/feeds/win.eventlog.setup/` |
| `win.eventlog.platform` | Platform channels: kernel, PnP, boot, power, drivers | `references/feeds/win.eventlog.platform/` |
| `win.eventlog.storage` | Storage channels: disks, volumes, NTFS, storage drivers | `references/feeds/win.eventlog.storage/` |
| `win.eventlog.network` | Network channels: SMB client and server, DHCP, DNS client, Wi-Fi, firewall | `references/feeds/win.eventlog.network/` |
| `win.eventlog.identity_security` | Identity and security channels: code integrity, exploit protection, Group Policy, Entra and TPM | `references/feeds/win.eventlog.identity_security/` |
| `win.eventlog.management` | Management channels: Task Scheduler, BITS, WinRM, WMI, Windows Update client | `references/feeds/win.eventlog.management/` |
| `win.eventlog.apps` | Apps channels: packaged apps, app model, application compatibility | `references/feeds/win.eventlog.apps/` |
| `win.servicing.cbs` | CBS servicing internals: component store, packages | `references/feeds/win.servicing.cbs/` |
| `win.servicing.dism` | DISM operations and image health | `references/feeds/win.servicing.dism/` |
| `win.defender.eventlog` | Defender: threats, protection state | `references/feeds/win.defender.eventlog/` |
| `sparklogs.device.state` | Device health and state snapshots: CPU, RAM, disk, installed software, monitors | `references/feeds/sparklogs.device.state/` |
| `sparklogs.agent.vector` | Collector debug only: data collector internals | `references/feeds/sparklogs.agent.vector/` |
| `sparklogs.agent.log` | Collector debug only: agent supervisor log | `references/feeds/sparklogs.agent.log/` |

## Escalation

Offer `sparklogs-investigate` for an in-depth written report (name the matching playbook from the table when it fits). `sparklogs-analyze-cause` only after that report exists.