VMware Log Insight
English | 中文
Maintainer: Wei Zhou · zhouwei008@gmail.com
Community-maintained open-source project; not an official VMware or Broadcom product.
Overview · Quick Start · MCP Configuration · Capabilities and Workflows · Safety and Audit · Troubleshooting · Companion Skills · Reference · License
Overview
Runs locally over stdio by default; configure required targets and credentials on your own machine.
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 (formerly vRealize Log Insight) — the appliance that collects syslog from ESXi hosts, vCenter, and VMs. The centralized-log data source for the VMware skill family. Strictly non-destructive: it queries, it never writes.
Full agent instructions: skills/vmware-log-insight/SKILL.md.
Quick Start
Requires Python >=3.10 and uv.
uv tool install vmware-log-insight==2.4.4
vmware-log-insight --help
Target, credential and local data setup: setup guide.
Installation and configuration details (including offline setup)
Install
uv tool install vmware-log-insight==2.4.4
mkdir -p ~/.vmware-log-insight
cp config.example.yaml ~/.vmware-log-insight/config.yaml # edit host/username/provider
echo 'VMWARE_LOG_INSIGHT_PROD_PASSWORD=...' > ~/.vmware-log-insight/.env
chmod 600 ~/.vmware-log-insight/.env
vmware-log-insight doctor
Offline / Air-Gapped Install (from source)
This project uses the modern PEP 517 build system (hatchling), so there is no
setup.py by design — that is expected, not a missing file. If you cloned the
source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and
cannot do an editable (-e) install with a non-setuptools backend. Editable
mode is a developer convenience, not needed to run the tool — do one of:
# From the source tree — a normal (non-editable) install builds a wheel:
pip install . # NOT pip install -e .
# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .
For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:
# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist # → dist/*.whl (or: uv build, for just this package)
# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-log-insight
MCP Configuration
Copy this configuration into your MCP client's local stdio settings. The client must be able to find uvx; the initial package installation requires access to a package index.
{
"mcpServers": {
"vmware-log-insight": {
"command": "uvx",
"args": ["--from", "vmware-log-insight==2.4.4", "vmware-log-insight-mcp"],
"env": {
"VMWARE_LOG_INSIGHT_CONFIG": "~/.vmware-log-insight/config.yaml"
}
}
}
}
Capabilities and Workflows
MCP Tools (7 — all read-only)
| Tool | What |
|---|---|
search_logs |
Search events by time window + text (whole-token match), up to 200 events |
aggregate_logs |
Count/aggregate over time bins (UCOUNT/AVG/... of a field), with z-score spike detection |
list_log_fields |
List the appliance's fields (name + type), for aggregate_logs field |
get_log_insight_version |
Appliance version/build |
list_log_alerts / get_log_alert / get_log_alert_history |
Query defined alerts and their trigger history |
Workflows
- Find errors fast —
vmware-log-insight search -q error -l 1h. - Where did logs burst? —
vmware-log-insight aggregate -q error -l 6h --bin-ms 300000, readspikes[], thensearchthe spike window. - Root cause — pass
search_logsresults (plus vCenter events from vmware-monitor and metrics from vmware-aria) to vmware-debugbuild_incident_timeline.
Safety and Audit
Security
Read-only by construction. Credentials in ~/.vmware-log-insight/.env (chmod 600);
plaintext passwords auto-obfuscated to grep-safe b64: (obfuscation, not
encryption — inject from a secret manager for real secrecy). TLS on by default.
See SECURITY.md.
Remote access (HTTPS) and limiting tools
By default vmware-log-insight mcp speaks stdio to one local client and offers every tool. Two options change that
(vmware-policy ≥ 1.21.0).
Serve over HTTPS so clients on other machines can connect. Every caller needs a bearer token:
vmware-audit token create alice # prints the token once; give it to alice
vmware-audit token list # names only
vmware-audit token revoke alice # refused from its next request, no restart
vmware-log-insight mcp --transport https --host 0.0.0.0 --port 8443 \
--cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
--public-name mcp.example.com
Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
claude mcp add --transport http vmware-log-insight https://mcp.example.com:8443/mcp \
--header "Authorization: Bearer $VMWARE_MCP_TOKEN"
{
"mcpServers": {
"vmware-log-insight": {
"type": "http",
"url": "https://mcp.example.com:8443/mcp",
"headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
}
}
}
- The server will not start without a token, refuses Host/Origin values outside
--public-name, and checks before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names. - Behind a TLS-terminating reverse proxy on the same machine use
--transport http --host 127.0.0.1 --public-name mcp.example.comand pass theAuthorizationheader through. - Behind a load balancer or gateway on another machine, keep
--transport https(a self-signed certificate is fine), list in--public-namethe host name the balancer sends asHost, and have it forwardAuthorization. Its health probe can useGET /healthz, which needs no token and returns only{"status": "ok"}(vmware-policy ≥ 1.23.0). - Send
traceparentorX-Request-IDwith each request to have it stored on the audit row;vmware-audit log --correlation-id IDthen finds the calls behind one platform request. - The audit log records each caller as
token:<name>. Calls run side by side, with or without a target: each target keeps up toVMWARE_MCP_POOL_SIZEsessions (default 2), and each session is a login on the target. A call that finds them all busy waits at most 300 s for one. - Everyone who can reach the endpoint acts with this server's account. Tokens identify callers; they grant nothing on the platform. Run one endpoint per privilege level.
- Several people or roles on one endpoint: run
vmware-audit roles enableonce, then give each token a role (vmware-audit token create NAME --role reader, or a role inroles.yamlnaming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
Limiting tools: every tool of this server is read-only, so --expose read changes nothing here; it
exists for the write-capable skills. Least privilege comes from the account the server uses.
Details: skills/vmware-log-insight/references/setup-guide.md ("Serving MCP over HTTPS", "Limiting which tools are offered").
Troubleshooting
Troubleshooting
401 on /sessions→ check username/password/providerand theVMWARE_LOG_INSIGHT_<TARGET>_PASSWORDenv var.503 everywhere→ appliance starting up;doctorreports it as a status, not a crash.- Empty results → widen
--last;textmatches whole words, not substrings (tryword*); default API port is 9543 (setportif different). UCOUNT needs a field→ pass--field(names fromfields); COUNT and SAMPLE take none.
System proxy bypass
The Log Insight REST client honors the operating system proxy bypass list for the configured origin.
TLS verification still follows verify_ssl, and CA environment settings such as SSL_CERT_FILE remain active.
Other origins retain their normal proxy routing.
Companion Skills
The VMware Skills family contains 14 MCP servers and the shared Policy library. Choose tools by responsibility: vmware-skills.
Companion Skills
| Need | Skill |
|---|---|
| Raw centralized logs + spikes | vmware-log-insight (this) |
| vCenter events & alarms | vmware-monitor |
| Metrics, anomalies, capacity | vmware-aria |
| Incident correlation / root cause | vmware-debug — feed it search_logs output |
| VM lifecycle / operations | vmware-aiops |
Reference
Release history: RELEASE_NOTES.md.
Read-only self-test with your own model and agent host: model-fit self-test.
Upgrading to 2.0
2.0 renames all 7 MCP tools so every name starts with a verb (e.g. alert_get → get_log_alert, alert_history → get_log_alert_history, alert_list → list_log_alerts). The full old → new table is in
RELEASE_NOTES.md. Nothing else changes: same tools, parameters,
safety gates and CLI commands. If an agent prompt, script or ~/.vmware/rules.yaml names a tool, update it — though deny
rules written with the old names keep working with vmware-policy ≥ 1.18 (vmware-audit policy lists any rule the
renames widened), and vmware-pilot ≥ 1.13 translates old names in saved workflows.
If an install older than 2.0 shares that rules.yaml, give it vmware-policy ≥ 1.18.2 too: it matches each rule
against both the old and the new name, so one file serves both.
License
MIT.
Transient request recovery
Only GET requests are automatically retried after a transport failure or a 502/503/504 response. Writes are sent once even when a retry budget is supplied: a missing response may mean the change already took effect. Inspect the target before retrying a write. A single authentication recovery after an explicit rejection is handled separately. This boundary has synthetic HTTP contract coverage; it does not establish positive appliance compatibility.
Metadata
Release files for vmware-log-insight 2.4.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vmware_log_insight-2.4.4.tar.gz | 256.6 kB | Without provenance | Details for vmware_log_insight-2.4.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vmware_log_insight-2.4.4-py3-none-any.whl | Python 3 | none | any | Details for vmware_log_insight-2.4.4-py3-none-any.whl |
Total release size: 312.6 kB
Release files / vmware_log_insight-2.4.4.tar.gz
| Download URL | vmware_log_insight-2.4.4.tar.gz |
|---|---|
| Size | 256.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a0d40488874eb01da848464725c46afce67be121e49f4f352a33df6fee1288f
|
|
BLAKE2b-256 checksum How to use checksums |
e06af1aa00342538012249cc3305cbbdc7fd1834317e230294de0bfdf588f192
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.12
|
Release files / vmware_log_insight-2.4.4-py3-none-any.whl
| Download URL | vmware_log_insight-2.4.4-py3-none-any.whl |
|---|---|
| Size | 56.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
54d09afc83ab642bb2deaf5aaf5f8efeaeed08c255ee44568f737c7cb66d49e3
|
|
BLAKE2b-256 checksum How to use checksums |
fb04031c862c37744aa7a1fc42e0b0ab007596a3c985cd19335c2a87e37bf2c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.12
|
Security for vmware-log-insight 2.4.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.