VMware Log Insight

VMware Log Insight

免责声明：由社区维护的开源项目，与 VMware, Inc. 或 Broadcom Inc. 无关， 未获其认可或赞助。“VMware”、“vSphere”和“Aria”是 Broadcom 的商标。源代码依据 MIT 许可证公开，供公众审查。

面向 VMware Aria Operations for Logs（原名 vRealize Log Insight）的只读日志搜索与聚合工具——这款设备用于收集 ESXi 主机、vCenter 和 VM 的 syslog。它是 VMware 技能系列的集中式日志数据源。严格只读，不会造成破坏：只查询，不写入。

升级到 2.0

2.0 将全部 7 个 MCP 工具重命名，使每个名称都以动词开头（例如，alert_get → get_log_alert、alert_history → get_log_alert_history、alert_list → list_log_alerts）。完整的新旧名称对照表见 RELEASE_NOTES.md。其他内容均未更改：工具、参数、 安全限制和 CLI 命令都相同。如果 Agent 提示词、脚本或 ~/.vmware/rules.yaml 中指定了工具名称，请更新这些名称。不过，使用旧名称编写的拒绝规则仍可在 vmware-policy ≥ 1.18 下正常工作（vmware-audit policy 会列出因重命名而扩大适用范围的规则），而 vmware-pilot ≥ 1.13 会转换已保存工作流中的旧名称。 如果低于 2.0 的安装与其他安装共用该 rules.yaml，也请将其升级到 vmware-policy ≥ 1.18.2：该版本会同时根据新旧名称匹配每条规则，因此一个文件即可兼顾两者。

配套技能

需求	技能	工具数
原始集中式日志和突增	vmware-log-insight（本项目）	7
vCenter 事件与警报	vmware-monitor	27
指标、异常、容量	vmware-aria	28
事件关联／根因分析	vmware-debug — 将 search_logs 输出传给它	2
VM 生命周期／运维	vmware-aiops	49

安装

uv tool install vmware-log-insight
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

离线／隔离网络安装（从源代码安装）

本项目使用现代 PEP 517 构建系统（hatchling），因此按设计不包含 setup.py——这是预期行为，并非文件缺失。如果你克隆了源代码，并遇到 ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build，说明你的 pip 版本低于 21.3，无法使用非 setuptools 后端进行可编辑（-e）安装。可编辑模式是开发者的便利功能，运行工具并不需要它——可以选择以下任一方式：

# 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 .

对于真正隔离网络的主机，请在联网的机器上构建 wheel 并复制到目标主机——这样目标主机无需联网：

# 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 工具（7 个，均为只读）

工具	说明
search_logs	按时间范围和文本搜索事件（整词匹配），最多返回 200 个事件
aggregate_logs	按时间区间计数／聚合（对 field 执行 UCOUNT/AVG/...），并检测 z-score 突增
list_log_fields	列出设备的字段（名称和类型），供 aggregate_logs 的 field 使用
get_log_insight_version	设备版本／构建版本
list_log_alerts / get_log_alert / get_log_alert_history	查询已定义的警报及其触发历史

工作流

• 快速查找错误 — vmware-log-insight search -q error -l 1h。
• 日志在哪些时段激增？ — vmware-log-insight aggregate -q error -l 6h --bin-ms 300000，读取 spikes[]，然后搜索突增时段。
• 根因分析 — 将 search_logs 结果（以及 vmware-monitor 提供的 vCenter 事件和 vmware-aria 提供的指标）传给 vmware-debug 的 build_incident_timeline。

故障排查

• /sessions 返回 401 → 检查用户名、密码、provider 以及 VMWARE_LOG_INSIGHT_<TARGET>_PASSWORD 环境变量。
• 所有请求都返回 503 → 设备正在启动；doctor 会将其报告为状态，而不是崩溃。
• 结果为空 → 增大 --last；text 匹配完整单词，而不是子串（试试 word*）；默认 API 端口是 9543（如果不同，请设置 port）。
• UCOUNT needs a field → 传入 --field（名称来自 fields）；COUNT 和 SAMPLE 不需要参数。

安全

从设计上来说，此工具是只读的。凭据存放在 ~/.vmware-log-insight/.env 中（chmod 600）； 明文密码会自动混淆为 grep 安全的 b64:（这是混淆，不是 加密——要实现真正的保密，请从密钥管理器注入）。默认启用 TLS。 请参阅 SECURITY.md。

远程访问（HTTPS）和限制工具

默认情况下，vmware-log-insight mcp 通过 stdio 与一个本地客户端通信，并提供所有工具。两种选项可以改变这一行为 （vmware-policy ≥ 1.21.0）。

通过 HTTPS 提供服务，以便其他机器上的客户端可以连接。每个调用方都需要一个 bearer 令牌：

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

连接客户端（此处以 Claude Code 为例；任何支持可流式 HTTP 和自定义请求头的 MCP 客户端都可以）：

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}" }
    }
  }
}

• 没有令牌时，服务不会启动；它会拒绝 --public-name 之外的 Host/Origin 值，并在绑定之前检查未认证请求是否会返回 401。请使用客户端信任的证书，并确保其名称与这些名称匹配。
• 在同一台机器上的 TLS 终止反向代理之后运行时，请使用 --transport http --host 127.0.0.1 --public-name mcp.example.com，并转发 Authorization 请求头。
• 在另一台机器上的负载均衡器或网关之后运行时，请保留 --transport https（自签名证书也可以），在 --public-name 中列出负载均衡器发送为 Host 的主机名，并让它转发 Authorization。它的健康探测可以使用无需令牌的 GET /healthz，该请求只会返回 {"status": "ok"}（vmware-policy ≥ 1.23.0）。
• 每个请求都发送 traceparent 或 X-Request-ID，以便将其存储在审计记录中；然后使用 vmware-audit log --correlation-id ID 查找某个生产请求背后的调用。
• 审计日志会将每个调用方记录为 token:<name>。调用会并行运行，无论是否指定目标：每个目标最多保留 VMWARE_MCP_POOL_SIZE 个会话（默认值为 2），每个会话都是在该目标上的一次登录。如果调用时所有会话都处于忙碌状态，则最多等待 300 秒，直到有一个会话可用。
• **所有能够访问该端点的人，都将以此服务的账户身份执行操作。**令牌用于识别调用方；它们不会授予调用方任何平台权限。每个权限级别运行一个端点。
• **一个端点供多个人或角色使用：**运行一次 vmware-audit roles enable，然后为每个令牌指定角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中指定角色，并列出工具和目标；vmware-policy ≥ 1.24.0）。角色会限制令牌可以调用此端点上的哪些工具，但不能授予超出该账户已有权限的权限。请参阅 vmware-policy 的 README 中的“网络调用方的角色”。

**限制工具：**此服务的每个工具都是只读的，因此 --expose read 在此处不会产生任何变化；此选项是为支持写操作的技能提供的。最小权限来自服务使用的账户。

详情：skills/vmware-log-insight/references/setup-guide.md（“通过 HTTPS 提供 MCP 服务”“限制提供的工具”）。

许可证

MIT。