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時間のログ」のような検索を依頼した場合：

1. シンプルな検索をデフォルトにする：時間引数を付けずに logs 'error' を実行します
2. 取得後に結果を絞り込む：エージェントが結果から古いエントリを除外できます
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 を参照してください。