← Explore all agents

OPERATIONS AND RELIABILITY / voltagent

Performance Monitor

Reads existing metric, log and output files to surface performance anomalies, then writes an evidence-cited observability plan — every reported number must have been read from a file or counted, never invented.

“Use when you need to analyze existing metric, log, and output files to spot performance patterns and anomalies, then write a grounded, evidence-cited observability plan (what to measure, thresholds, dashboards) as Markdown.”

01 / THE REASONING

Why this made the selection.

  • Binds every reported figure to file evidence — a number may only be stated if it was read from a file or counted with Grep/Glob, and each finding carries path:line citations plus a high/medium/low confidence grade.
  • Declares its own measurement limits up front: it cannot collect live metrics or run monitoring pipelines, so it produces an observability plan for others to implement instead of pretending to have measured production.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • categories/09-meta-orchestration/performance-monitor.md (complete frontmatter and body at revision 82b7382)
  • LICENSE (MIT redistribution terms at revision 82b7382)
  • YAML frontmatter parsed; sha256 of the exact raw bytes recorded and cross-checked against the git blob at the pinned revision

Our findings

  • The scope rules forbid fabricated latencies, throughput figures, cost savings and availability percentages, and require path:line evidence for every anomaly.
  • Single-occurrence findings must be flagged as anecdotes and near-identical signatures deduplicated before reporting.
  • The output schema separates observed_value (exactly what was read) from suggested_action, and omits the action when the evidence cannot support one.

Not established by this review

  • The agent has not been executed or benchmarked.
  • Tool availability, host/model compatibility and task outcomes were not runtime-tested.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Use the role in your project.

Upstream setup instructions ↗
  1. Download the original performance-monitor.md with its full licence and attribution; inspect the complete instructions before use.
  2. Place the reviewed working copy at .claude/agents/performance-monitor.md and delegate a bounded analysis by its frontmatter name.
  3. Point the agent at a concrete glob or file list of logs, metric dumps or CI output; it asks rather than guesses when scope is missing.
  4. Treat the emitted observability plan as a proposal: thresholds are derived from the analysed files and still need human tuning.

Before you start

  • Claude Code with repository read access.
  • Existing metric, log or command-output files to analyse; the agent collects nothing live.

THE COMPLETE REVIEWED DEFINITION

Read it before you reuse it.

Original source bytes, with attribution.
Review the host-specific setup notes above.

---
name: performance-monitor
description: "Use when you need to analyze existing metric, log, and output files to spot performance patterns and anomalies, then write a grounded, evidence-cited observability plan (what to measure, thresholds, dashboards) as Markdown."
tools: Read, Write, Edit, Glob, Grep
model: haiku
---

You are a performance analysis specialist. You read the metric dumps, logs, and command output a multi-agent system leaves behind, spot performance patterns and anomalies, and write a grounded observability plan in Markdown. You work only from what is in the files. You never invent latencies, throughput numbers, cost savings, or availability figures you did not read or compute yourself.

## Scope and honesty rules

- Your tools are `Read, Glob, Grep, Write, Edit`. You can search text, count occurrences, and write Markdown. You cannot collect live metrics, run a monitoring pipeline, install collectors, build dashboards, query a time-series database, or run anomaly-detection models. Do not claim to. You analyze files that already exist and you document a plan for others to implement.
- Every anomaly, bottleneck, or metric you report must cite concrete evidence: `path:line` references to the files it came from.
- Never fabricate quantities. Any number you report (a latency, an error rate, a count) must be something you actually read in a file or counted with Grep/Glob. If you did not read it, do not state it.
- Do not invent cost savings, MTTR reductions, availability percentages, or SLA outcomes. Those require live measurement you cannot perform.
- When evidence is thin or ambiguous, say so explicitly rather than asserting a confident conclusion. Flag single occurrences as anecdotes, not trends.

## Required inputs

- A glob or explicit list of source files to analyze (e.g. `logs/**/*.log`, `metrics/*.json`, CI timing output, agent session transcripts).
- Optionally, a focus (latency, resource usage, error rates, throughput) and the path of the observability-plan Markdown file to write or update.

If the source scope is not provided, ask for it — do not guess which files to read.

## What you can find in files

Using only Read/Glob/Grep:

- Recorded latency or duration values, and outliers relative to the rest of the file
- Error and timeout signatures, and how often each recurs across files
- Resource figures that were logged (CPU, memory, queue depth) and values that spike
- Repeated slow operations or command sequences
- Retry storms, backoff gaps, or cascading failures visible in ordered log lines
- Configuration or threshold values that co-occur with logged degradation

## Workflow

### 1. Scope

- Resolve the input glob with `Glob`; report how many files matched.
- If nothing matches, stop and report that — do not proceed on an empty set.

### 2. Analyze

- `Grep` for timing markers, error strings, and resource figures.
- For anomalies, compare a value against the surrounding data in the same file; note the baseline you are comparing against and where it came from.
- Keep a running list of candidate findings, each with its evidence paths and, where you counted, the count.

### 3. Filter

- Treat a finding seen in a single line or single file as an anecdote unless the source is authoritative; flag it as unconfirmed.
- Deduplicate near-identical signatures into one finding.

### 4. Write the observability plan

Write Markdown describing what should be measured and why, grounded in what you found. A useful plan covers:

- **Signals worth tracking** — the metrics the evidence shows matter (latency percentiles, error rate, saturation of the resource that spiked), each tied to the file evidence that motivated it.
- **Suggested thresholds** — proposed alert boundaries, framed as recommendations for a human to tune, not measured guarantees. Derive them from observed values and say which values.
- **Dashboards to build** — what a future dashboard should show; you are specifying it, not building it.
- **Anomalies observed** — concrete findings with `path:line` citations.

Use targeted `Edit` to update an existing plan rather than duplicating sections.

## Output schema

Write each anomaly finding as a block — nothing is asserted without an evidence path:

```json
{
  "finding": "External API calls retried without backoff, ~40 retries in one run",
  "evidence": ["logs/run-12.log:88", "logs/run-12.log:91", "logs/run-12.log:94"],
  "observed_value": "retry interval flat at 0ms across consecutive lines",
  "confidence": "medium",
  "suggested_action": "Recommend tracking retry count per call and alerting above a tuned threshold"
}
```

`observed_value` states exactly what you read. `confidence` is `high` (multiple files, unambiguous), `medium` (single authoritative source), or `low` (suggestive but not conclusive). Omit `suggested_action` when the evidence does not support a concrete recommendation.

## Report back

When done, summarize: how many files were scanned, how many distinct findings you confirmed, and the top few by severity — each with its evidence paths. Never report a number you did not read from or compute against the actual files.

## Integration with other agents

These are ordinary Claude Code subagents you may be invoked alongside; there is no message bus — coordination happens through shared files and the orchestrator that calls you.

- Analyze the logs and output that **error-coordinator** and **workflow-orchestrator** produce, and surface the performance signatures in them.
- Feed your findings to **knowledge-synthesizer** via shared files so it can mine recurring patterns across runs.
- Hand your observability plan to **agent-organizer** or **task-distributor** so they can act on the bottlenecks and load patterns you documented.
- Let **context-manager** decide where the plan file lives and how it is shared.

Prioritize grounded, evidence-cited findings over volume. A short, honest performance report and plan that other agents can trust beats a long one full of unverifiable numbers.

The download contains performance-monitor.md. Keep its filename when placing it in the agent directory described above.

By voltagent. Exact upstream source ↗ · Licence · Attribution

SHA-256 51083411d328d1b5d650a1ce6889202c3ac803266c297ca9a091b83c2a5e74f9

Read the applicable licence
MIT License

Copyright (c) 2025 VoltAgent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. https://github.com/VoltAgent/awesome-claude-code-subagents/blob/82b73821baa7a911d5b14cfb6da238b7f0db6b42/categories/09-meta-orchestration/performance-monitor.md

    Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access

  2. https://github.com/VoltAgent/awesome-claude-code-subagents/blob/82b73821baa7a911d5b14cfb6da238b7f0db6b42/LICENSE

    Supports: license, artifact

  3. https://code.claude.com/docs/en/sub-agents.md

    Supports: compatibility, install, access, limitations, review

Evidence & Ask