solarwinds-logs

SolarWinds 日志搜索

使用 logs CLI 工具通过 SolarWinds Observability API 搜索 DealerVision 生产日志。

首次设置（按需进行）

此技能需要 logs CLI 工具、.NET 10 和 SolarWinds API 令牌。仅在激活技能时安装。

1. 检查是否已安装

Linux/macOS：

logs --help 2>/dev/null || echo "Not installed - setup required"
echo "$SOLARWINDS_API_TOKEN"

Windows（PowerShell）：

logs --help 2>$null
Write-Host "SOLARWINDS_API_TOKEN=$env:SOLARWINDS_API_TOKEN"

2. 安装依赖项和工具（一次性设置）

从已部署的技能文件夹运行设置脚本：

Linux/macOS：

bash ~/.codex/skills/solarwinds-logs/scripts/setup.sh

Windows（PowerShell）：

pwsh ~/.codex/skills/solarwinds-logs/scripts/setup.ps1

如果你使用 Claude Code，请将 ~/.codex/skills 替换为 ~/.claude/skills。

此操作会：

• 如果尚未安装，则安装 .NET SDK 10（用户级）
• 从技能本地程序包安装 logs CLI 工具
• 验证安装
• 检查必需的环境变量

注意： 只需安装一次；之后该工具将全局可用。

3. 配置环境变量

该工具需要 SolarWinds API 令牌进行身份验证。

Linux/macOS：

export SOLARWINDS_API_TOKEN="your-token-here"

Windows（PowerShell）：

$env:SOLARWINDS_API_TOKEN = "your-token-here"

获取令牌：

1. 登录 SolarWinds Observability
2. 前往 Settings -> API Tokens
3. 创建具有 'Logs Read' 权限的新令牌

4. 验证设置

Linux/macOS：

dotnet tool list --global | grep SolarWindsLogSearch
logs "test" --limit 1

Windows（PowerShell）：

dotnet tool list --global | Select-String SolarWindsLogSearch
logs "test" --limit 1

前提条件

• .NET SDK 10.0+（安装该工具所需）
• SOLARWINDS_API_TOKEN 环境变量（使用该工具所需）
• 默认数据中心：na-01

其他方式：手动安装

如果你希望不使用设置脚本而手动安装：

# Requires .NET SDK 10.0+
dotnet tool install --global DealerVision.SolarWindsLogSearch --version 2.4.0 --add-source ~/.codex/skills/solarwinds-logs/tools

# If using Claude Code, replace ~/.codex/skills with ~/.claude/skills
# Windows path: %USERPROFILE%\\.codex\\skills\\solarwinds-logs\\tools (or .claude for Claude Code)

# Verify
logs --help

⚠️ 重要：优先使用简单搜索（不带时间参数）

SolarWinds/Papertrail API 对时间范围的处理并不稳定，使用时间参数时常会跳过近期条目。 logs 工具的设计方式是从最新条目开始，并自动逐页向前搜索，直到达到预定义的上限（通常相当于 24 小时的数据）。

默认搜索模式

始终优先使用不带时间参数的简单关键词搜索：

# ✅ RECOMMENDED - Simple searches that capture current entries
logs 'error'
logs 'exception'
logs 'timeout'
logs 'DbUpdateException'

# ✅ GOOD - Add filters, but avoid time arguments
logs 'error' --severity ERROR
logs 'exception' --program webhook-api

为什么要避免使用时间参数？

使用 --time-range、--start-time 或 --end-time 时，API 可能只返回部分条目，遗漏重要的当前或近期日志条目。这是底层 Papertrail API 的已知问题。

# ⚠️ AVOID - Time arguments can miss recent entries
logs "error" --time-range 1h      # May miss errors from the last few minutes
logs "error" --time-range 24h     # May skip entries that just happened

如何处理带有时间描述的用户请求

当用户提出“今天的错误”或“最近一小时的日志”等请求时：

1. 默认进行简单搜索：运行 logs 'error'，不带时间参数
2. 检索后筛选结果：Agent 可从结果中过滤掉较早的条目
3. 仅在用户明确要求排除当前或近期结果时使用时间参数

示例解读：

• “搜索今天的错误日志” → logs 'error' OR 'exception'（自行筛选结果）
• “查找最近 4 小时内的异常” → logs 'exception'（自行筛选结果）
• “显示错误，但只看昨天的，不包括今天” → 适合使用时间参数

适合使用时间参数的情况

仅在用户明确希望进行以下操作时使用时间参数：

• 排除当前或近期结果
• 查看某个特定的历史时间段（例如，“上周二下午 2 点到 4 点发生了什么”）
• 调查具有具体时间戳的已知历史事故

常用命令

# Search for errors (recommended - no time arguments)
logs 'error'

# Find specific exceptions
logs 'DbUpdateException' --severity ERROR --limit 10

# Filter by service (still no time arguments)
logs 'timeout' --program webhook-api

# Get full details for a specific log entry
logs --id 1901790063029837827 --with-data

# Export large result sets to file
logs 'exception' --output-file results.json

主要选项

选项	说明
--time-range	1h、4h、12h、24h、2d、7d、30d
--severity	INFO、WARN、ERROR、DEBUG
--program	按服务名称筛选（例如，media-processing）
--hostname	按主机筛选
--limit	最大结果数（默认 1000，最多 50000）
--with-data	包含结构化 JSON 负载
--no-data	排除负载（响应更快、更小）
--output-file	将完整结果保存到文件

工作流策略

1. 从宽泛开始 - 运行初始搜索时不要添加太多筛选条件
2. 逐步缩小范围 - 根据结果添加严重级别、时间范围或计划筛选条件
3. 获取详细信息 - 使用 --id 和 --with-data 查看完整日志条目
4. 导出大型数据集 - 使用 --output-file 进行全面分析

输出格式

返回包含以下内容的 JSON：

• success：布尔状态
• query：使用的搜索参数
• summary：统计信息，包括严重级别细分和截断信息
• results：日志条目数组，包含时间戳、来源、严重级别和消息
• pagination：用于获取更多结果的信息

高级用法

有关查询语法、MCP 服务模式和高级模式的详细文档，请参阅 references/REFERENCE.md。

有关常见调查模式和操作指南，请参阅 references/RECIPES.md。