vmware-log-insight

VMware Log Insight

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc. "VMware", "vSphere", and "Aria" are trademarks of Broadcom. Source is publicly auditable under the MIT license.

Read-only log search and aggregation for VMware Aria Operations for Logs (vRealize Log Insight) — the centralized-log data source for the VMware skill family. Strictly non-destructive: it queries, it never writes.

What This Skill Does

7 tools, all read-only. No ingest, no alert creation/edit/delete — zero write surface.

Quick Install

uv tool install vmware-log-insight
cp config.example.yaml ~/.vmware-log-insight/config.yaml   # then edit
vmware-log-insight doctor       # verify connectivity

When to Use This Skill

Use it to read the actual log lines behind an incident — what an ESXi host's vmkernel logged, vCenter vpxd errors, a login storm in VM syslog — and to find when log volume spiked.

• vCenter events/alarms (not raw syslog)? → vmware-monitor
• Performance metrics / anomalies / capacity? → vmware-aria
• Correlate logs + events + metrics into one root-cause view? → vmware-debug

Do NOT use when there is no Log Insight appliance, or the user wants vCenter alarms (monitor) or metric anomalies (aria). This skill only reads the log store.

Related Skills — Skill Routing

Common Workflows

1. "Find the errors on a host in the last hour"

1. log_search(text="error", last="1h", filters via CLI hostname=...) — or CLI: vmware-log-insight search -q error -l 1h.
2. Read the events[] (timestamp + text + fields). Narrow with a more specific text if complete=False (result was truncated).
3. Failure branch — auth/connection error: the teaching message names the cause (e.g. "503: appliance starting up"); run vmware-log-insight doctor. A 503 is a status, not a crash.

2. "Was there a log spike, and when?"

1. log_aggregate(text="...", last="6h", bin_width_ms=300000) — counts per 5-minute bin + spikes[] (z-score flagged).
2. Take a spike's timestamp_ms, then log_search(begin_ms=..., end_ms=...) around it to read what burst.
3. Failure branch — empty bins: widen last or drop the text filter; confirm the appliance actually receives logs from the source.

3. Correlate logs into a root-cause timeline

1. log_search / log_aggregate here for the log signal.
2. Pull vCenter events (vmware-monitor) and metrics/anomalies (vmware-aria) for the same window/entity.
3. Hand all of them to vmware-debug incident_timeline (normalise to its event envelope) to rank root causes.

Usage Mode

• MCP (in an agent): call log_search/log_aggregate, then pass results to vmware-debug. Primary mode.
• CLI (humans): vmware-log-insight search -q "apd" -l 2h.

MCP Tools (7 — 7 read, 0 write)

List envelope: log_fields, alert_list and alert_history return {items, returned, limit, total, truncated, hint} rather than a bare list — read the rows from items, and treat truncated: true as "there is more, raise limit or narrow the filter". total is a real count (the appliance returns each collection in one GET and limit is applied client-side), so a page that exactly fills limit is still reported truncated: false when it is genuinely complete.

Query model: time windows use a relative last ("1h", "30m", "7d") or an absolute begin_ms/end_ms (epoch ms); text is a CONTAINS search. See references/cli-reference.md for the full constraint grammar.

Read-Only by Design

All 7 tools here are reads — no ingest, no alert creation/edit/delete, zero write surface. Running with local or small models? See references/agent-guardrails.md.

CLI Quick Reference

vmware-log-insight search -q "scsi apd" -l 2h          # search events
vmware-log-insight search -q error -l 1h --json        # raw JSON
vmware-log-insight aggregate -q error -l 6h --bin-ms 300000   # spikes
vmware-log-insight fields --name host                  # discover fields
vmware-log-insight alert list                          # defined alerts
vmware-log-insight doctor                              # diagnostics
vmware-log-insight mcp                                  # start MCP server (proxy-safe)

Troubleshooting

• POST /sessions returned HTTP 401 — wrong username/password/provider. Check config.yaml (provider: Local | ActiveDirectory) and the VMWARE_LOG_INSIGHT__PASSWORD env var.
• HTTP 503 on every call — the appliance is starting or a service isn't ready; the error says so. Wait and retry; doctor reports it as a status, not a crash.
• HTTP 400 on a search — a malformed constraint. Time/field filters are path-encoded as field/OPERATOR/value; let the CLI/tool build them rather than hand-crafting.
• Empty results but logs exist — check the time window (last) and that the appliance actually ingests from that source; widen the window.
• Default port is 9543, not 443 — set port in config.yaml if your appliance differs.

Audit & Safety

Read-only by construction (no write tools). MCP tools run through @vmware_tool(risk_level="low"), which records each call to the shared audit DB (~/.vmware/audit.db). Targets may declare environment: (production / staging / lab) in config.yaml to scope policy rules; reads are never gated by it, so this skill is unaffected either way, but declaring it keeps any future write tool correctly scoped. Credentials load from ~/.vmware-log-insight/.env (chmod 600); plaintext passwords there are auto-rewritten to a grep-safe b64: form on first load (obfuscation, not encryption — inject from a secret manager for real at-rest secrecy). All API text passes through sanitize() (prompt-injection defence). TLS verification is on by default; disable only for self-signed lab appliances. See references/setup-guide.md.

License

MIT.