Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion evals/btrace-observability.json
Original file line number Diff line number Diff line change
Expand Up @@ -141,12 +141,32 @@
"list_jvms",
"pid",
"duration",
"list_probes",
"exit_probe"
],
"mustAvoid": [
"grantAll=true"
],
"rubric": "Use the local MCP workflow: identify the PID, deploy a bounded latency probe, and explicitly remove it with exit_probe."
"rubric": "Use the local MCP workflow: identify the PID, check for probes left running with list_probes, deploy a bounded latency probe, and explicitly remove it with exit_probe."
},
{
"id": "mcp-leftover-probe",
"prompt": "Yesterday an assistant session used the BTrace MCP server on my local JVM and I think it detached from a probe instead of stopping it. Is anything still running, and how do I get rid of it?",
"requiredSkills": [
"btrace-observability",
"btrace-mcp-operations",
"btrace-probe-lifecycle"
],
"mustMention": [
"list_jvms",
"list_probes",
"pid",
"btrace -r"
],
"mustAvoid": [
"kill -9"
],
"rubric": "Find the target PID, list detached probes with list_probes, explain that the MCP server cannot stop a probe it did not deploy in this session, and hand the operator the CLI reconnect command to stop it without killing the target JVM."
},
{
"id": "legacy-libs-migration",
Expand Down
2 changes: 0 additions & 2 deletions plugins/btrace-observability/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,5 +36,3 @@ at its masked JAR:
```sh
BTRACE_JAR=/path/to/btrace/btrace-dist/build/resources/main/v<version>/libs/btrace.jar ./gradlew e2eTest
```

The `list_probes` case is disabled because the BTrace client exits the JVM after listing probes.
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@
import java.util.function.LongPredicate;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Test;
Expand Down Expand Up @@ -204,9 +203,6 @@ void exitProbeRemovesTheInstrumentation() throws Exception {

@Test
@Order(9)
@Disabled(
"BTrace Client.connectAndListProbes calls System.exit(0) after the reply, which terminates"
+ " the MCP server process; needs a BTrace client change")
void listProbesReportsTheRunningProbe() throws Exception {
Map<String, Object> result = tool("list_probes");
assertSuccess(result);
Expand Down
21 changes: 13 additions & 8 deletions plugins/btrace-observability/skills/btrace-mcp-operations/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,17 @@ description: Use when an AI client should operate BTrace through the BTrace MCP
# MCP Operations

The BTrace MCP server offers structured local-JVM operations such as `list_jvms`, `deploy_oneliner`,
`deploy_script`, `send_event`, `detach_probe`, and `exit_probe`. It is suitable when the AI client
and target JVM are on the same host and the operator wants an auditable conversational workflow.

Do not call `list_probes`. The current BTrace client exits the process after returning the probe
list, which terminates the MCP server and drops every open probe session, so `send_event` and
`exit_probe` can no longer reach probes deployed earlier. Track each deployment yourself instead:
target PID, agent port, probe class or oneliner, and observation window.
`deploy_script`, `list_probes`, `send_event`, `detach_probe`, and `exit_probe`. It is suitable when
the AI client and target JVM are on the same host and the operator wants an auditable conversational
workflow.

`list_probes` reports only probes that were detached with `detach_probe` and are still running on
the target; probes deployed in the current session that are still attached do not appear. Call it
before deploying, so probes left behind by an earlier session are found rather than stacked on, and
after any `detach_probe` to confirm what is still running. The MCP server cannot reconnect to or
stop a listed probe: report it to the operator, who can reconnect with `btrace -r <probe-id> <PID>`
and stop it. Track your own deployments yourself: target PID, agent port, probe class or oneliner,
and observation window.

Deployment results include only the probe's initial output; no tool returns what the probe prints
afterwards. When the operator needs ongoing results, have the probe write them somewhere they can
Expand All @@ -22,7 +26,8 @@ read, such as exported counters (`@Export` fields, read with `jcmd <PID> PerfCou
boundaries. For those cases, first use `btrace-runtime-access` to place the client/server in the
target environment.
- Treat deployment and cleanup as one operation: record the target PID and call `exit_probe` after
the observation window.
the observation window. Prefer `exit_probe` over `detach_probe`; a detached probe keeps running
and is visible afterwards only through `list_probes`.
- Use the server's `diagnose_slow_endpoint`, `find_exception_source`, and `profile_method` prompts
as starting workflows, then apply the other plugin skills for scope and data safety.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ condition.
2. Attach with an explicit output file when a durable incident record is required:
`btrace -v -o trace.log <PID> Probe.java`.
3. Exercise the scenario or observe only for the agreed window.
4. Check active probes with `btrace -lp <PID>`; reconnect only when intentionally continuing an
existing probe with `btrace -r <probe-id> <PID>`.
4. List probes that a client detached from and that are still running with `btrace -lp <PID>` (the
`list_probes` tool when working through the BTrace MCP server); reconnect only when
intentionally continuing an existing probe with `btrace -r <probe-id> <PID>`.
5. Stop/remove the probe at the end of the window, archive or delete the output according to policy,
and remove temporary probe files from the target host/container/pod.

Expand Down
3 changes: 2 additions & 1 deletion plugins/perf-engineer/skills/perf-engineer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ capability, record its actual command/tool identity in the session manifest.
Confirm target identity, Java/runtime boundary, source repository and base commit, dirty-worktree
state, available tools, recording window, output location, sensitivity policy, and profiling/live
instrumentation approval. Check for existing async-profiler/JFR/BTrace sessions or conflicts before
attaching; ask before stopping or reconfiguring one.
attaching (for BTrace, the BTrace MCP server's `list_probes` tool or `btrace -lp <PID>` lists
detached probes still running); ask before stopping or reconfiguring one.

Create a session manifest and local supervisor. The supervisor owns child processes, leases, durable
stop, timeout enforcement, cleanup, and state transitions. On restart, list active/orphaned sessions;
Expand Down
Loading