docs/agent-tools.json - master - dpavlov/ignite-firefighter

docs/agent-tools.json
299 строк11 KB
Dmitriy Pavlov
Improve first-pass reports and analyzers
09 июн 2026, 00:21
09 июн 2026, 00:21a47aa4e
{
  "schemaVersion": "ignff.agent-tools/v1",
  "project": "ignite-firefighter",
  "principles": [
    "The first pass is inventory only: discover artifacts, classify them, extract lightweight metadata, and group by probable node.",
    "Artifact analyzers must be runnable independently and in parallel after the inventory report identifies interesting files.",
    "Tools must avoid loading large logs, heap dumps, or binary files fully into memory."
  ],
  "commands": [
    {
      "name": "scan",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff scan <incident-dir> --out <report.md>",
      "defaultOutput": "ignff-report.md in the scanned directory",
      "inputs": [
        {
          "name": "incident-dir",
          "type": "directory",
          "required": true
        },
        {
          "name": "--out",
          "type": "markdown-file",
          "required": false
        }
      ],
      "outputs": [
        {
          "type": "markdown",
          "description": "Inventory report with artifact classification and probable node grouping."
        }
      ],
      "sideEffects": [
        "Writes only the requested report file."
      ]
    },
    {
      "name": "tools",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff tools --format json",
      "outputs": [
        {
          "type": "json",
          "description": "Machine-readable command manifest for agent planning."
        }
      ],
      "sideEffects": []
    },
    {
      "name": "report",
      "implemented": true,
      "parallelSafe": false,
      "invocation": "./ignff report <incident-dir> [--out-dir <dir>] [--format html|machine|both] [--threads <n>] [--tools-config <file>]",
      "purpose": "Run the first-pass inventory, discover local helper tools, run supported analyzers in parallel, and generate a linked report bundle.",
      "inputs": [
        {
          "name": "incident-dir",
          "type": "directory",
          "required": true
        },
        {
          "name": "--out-dir",
          "type": "directory",
          "required": false,
          "default": "ignff-report inside incident-dir"
        },
        {
          "name": "--format",
          "type": "enum",
          "required": false,
          "values": ["html", "machine", "both"],
          "default": "both"
        },
        {
          "name": "--threads",
          "type": "integer",
          "required": false,
          "default": "max(4, availableProcessors / 2)"
        },
        {
          "name": "--tools-config",
          "type": "properties-file",
          "required": false,
          "default": ".ignff-tools.properties inside out-dir"
        }
      ],
      "outputs": [
        {
          "type": "html/machine",
          "description": "Linked cluster report bundle. Browser-oriented HTML is written under out-dir/html. Machine-oriented Markdown and JSON sidecars are written under out-dir/machine when --format machine or --format both is selected. Empty analyzer directories are not created."
        }
      ],
      "sideEffects": [
        "Writes report files under out-dir.",
        "Writes or updates .ignff-tools.properties unless --tools-config points elsewhere."
      ]
    },
    {
      "name": "analyze-log",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff analyze-log <ignite-log> --format json",
      "purpose": "Summarize Ignite server/thick-client log markers, knowledge-base signals, retained evidence events, feature usage, topology/exchange/rebalance/discovery markers, warning/error filters, JVM pause detector lines, and cautious node mode classification.",
      "inputs": [
        {
          "name": "ignite-log",
          "type": "file",
          "required": true
        }
      ],
      "outputs": [
        {
          "type": "json",
          "schemaVersion": "ignff.analyze-log/v1",
          "description": "Streaming Ignite log signal inventory with markerCounts, mappedSignals, featureSignals, nodeMode, and retainedEvents. It does not infer incident root cause."
        }
      ],
      "sideEffects": []
    },
    {
      "name": "analyze-gc",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff analyze-gc <gc-log> --format json",
      "purpose": "Summarize GC pauses, full GC events, concurrent events, heap transitions, high live heap events, and longest pauses.",
      "inputs": [
        {
          "name": "gc-log",
          "type": "file",
          "required": true
        }
      ],
      "outputs": [
        {
          "type": "json",
          "schemaVersion": "ignff.analyze-gc/v1",
          "description": "Lightweight streaming GC log summary. It does not infer incident root cause."
        }
      ],
      "sideEffects": []
    },
    {
      "name": "analyze-heap-dump",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff analyze-heap-dump <dump.hprof> --format json [--mat-path <ParseHeapDump>] [--mat-out-dir <dir>] [--mat-timeout-minutes <n>] [--no-mat]",
      "purpose": "Run local Eclipse MAT suspects/overview when ParseHeapDump is discovered or configured; otherwise produce a privacy-preserving HPROF top-level inventory by scanning record headers once and skipping heap payload bytes.",
      "inputs": [
        {
          "name": "dump.hprof",
          "type": "file",
          "required": true
        },
        {
          "name": "--mat-path",
          "type": "file",
          "required": false,
          "description": "Path to Eclipse MAT ParseHeapDump.sh/.bat. If omitted, ignite-firefighter uses local tool discovery."
        },
        {
          "name": "--mat-out-dir",
          "type": "directory",
          "required": false,
          "description": "Directory where local MAT report artifacts are written."
        },
        {
          "name": "--mat-timeout-minutes",
          "type": "integer",
          "required": false,
          "default": 60
        },
        {
          "name": "--no-mat",
          "type": "flag",
          "required": false
        }
      ],
      "outputs": [
        {
          "type": "json",
          "schemaVersion": "ignff.analyze-heap-dump/v1",
          "description": "Heap dump inventory with MAT execution status and coarse HPROF record metadata. ignite-firefighter JSON does not extract application object values, strings, fields, or class names."
        }
      ],
      "sideEffects": [
        "May write or update .ignff-tools.properties next to the heap dump when --mat-path is omitted.",
        "When MAT runs, writes local MAT suspects/overview artifacts under --mat-out-dir or a local .ignff-mat directory."
      ]
    },
    {
      "name": "analyze-jfr",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff analyze-jfr <recording.jfr> --format json [--node-id <uuid>] [--consistent-id <id>] [--host <host>] [--bucket-seconds <n>]",
      "purpose": "Summarize JFR CPU samples, blocking, file IO, socket IO, GC, safepoints, allocation pressure, exceptions, Ignite-specific signals, and time buckets for RCE correlation.",
      "inputs": [
        {
          "name": "recording.jfr",
          "type": "file",
          "required": true
        },
        {
          "name": "--node-id",
          "type": "string",
          "required": false,
          "description": "Binds the primary recording sample to the Ignite node id being analyzed."
        },
        {
          "name": "--consistent-id",
          "type": "string",
          "required": false,
          "description": "Binds the primary recording sample to the Ignite consistent id being analyzed."
        },
        {
          "name": "--host",
          "type": "string",
          "required": false,
          "description": "Binds the primary recording sample to the host being analyzed."
        },
        {
          "name": "--bucket-seconds",
          "type": "integer",
          "required": false,
          "default": 60
        }
      ],
      "outputs": [
        {
          "type": "json",
          "schemaVersion": "ignff.analyze-jfr/v1",
          "description": "Streaming JFR signal inventory with nodeBinding and timeBuckets. It does not infer incident root cause."
        }
      ],
      "sideEffects": []
    },
    {
      "name": "analyze-thread-dump",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff analyze-thread-dump <thread-dump-or-log> --format json",
      "purpose": "Suppress normal idle worker stacks and retain only anomalous thread dump signals plus secondary cluster activity signals such as exchange, rebalance, checkpoint/WAL, SQL/query, discovery/communication, transactions, compute, and cache operations.",
      "inputs": [
        {
          "name": "thread-dump-or-log",
          "type": "file",
          "required": true,
          "description": "Standalone thread dump or a text log that may contain embedded thread dump sections."
        }
      ],
      "outputs": [
        {
          "type": "json",
          "schemaVersion": "ignff.analyze-thread-dump/v1",
          "description": "Streaming thread dump signal inventory with anomalies, clusterActivity, featureSignals, and state counts. It does not infer incident root cause."
        }
      ],
      "sideEffects": []
    },
    {
      "name": "analyze-nmon",
      "implemented": true,
      "parallelSafe": true,
      "invocation": "./ignff analyze-nmon <nmon-file> --format json",
      "purpose": "Summarize NMON host-level samples for CPU busy/wait, memory pressure, disk busy/read/write, network throughput, sample coverage, and section availability.",
      "inputs": [
        {
          "name": "nmon-file",
          "type": "file",
          "required": true,
          "description": "NMON CSV-style host monitoring file."
        }
      ],
      "outputs": [
        {
          "type": "json",
          "schemaVersion": "ignff.analyze-nmon/v1",
          "description": "Streaming NMON host metric summary. It does not infer incident root cause."
        }
      ],
      "sideEffects": []
    },
    {
      "name": "analyze-hs-err",
      "implemented": false,
      "parallelSafe": true,
      "plannedInvocation": "./ignff analyze-hs-err <hs_err_pid.log> --format json",
      "purpose": "Extract crash signal, problematic frame, JVM version, native library, process info, and memory context."
    },
    {
      "name": "analyze-heap-histogram",
      "implemented": false,
      "parallelSafe": true,
      "plannedInvocation": "./ignff analyze-heap-histogram <histogram> --format json",
      "purpose": "Rank object classes, detect Ignite-heavy structures, and compare histograms when multiple snapshots are available."
    }
  ]
}