trace_attach

[external]

Collects a bounded EventPipe nettrace from CoreCLR, or an ETW profile from a verified Windows Framework IIS worker.

Before you use this tool

ETW requires acknowledgeSensitive=true and acknowledgeMachineWideCapture=true. It captures machine-wide ETW data for at most 30 seconds; EventPipe remains the default.

Try it locally in the GliderTrace playground

Parameters

Name	Type	Required	Description
processId	number	Yes	Process id paired with targetId from the same fresh trace_list_processes result.
targetId	string	Yes	Copy targetId from the same fresh inventory item as processId. Refresh inventory after an identity error.
durationMs	number	No	Capture duration in milliseconds. EventPipe clamps to 1000..120000; ETW clamps to 1000..30000. Defaults to 10000. Default: `10000`
label	string	No	Optional short label for the stored session, for example nightly-baseline. Use it to find the session again with trace_list_sessions. Maximum 128 characters.
backend	string	No	Capture backend: eventpipe (default) or etw. The ETW profile requires Windows. Default: `"eventpipe"`
profile	string	No	Use framework-iis-cold-start for ETW capture.
acknowledgeSensitive	boolean	No	Confirm that raw ETL can contain request values and secrets. Default: `false`
acknowledgeMachineWideCapture	boolean	No	Confirm that kernel CPU and provider events can include other processes. Default: `false`

Examples

Replace sample paths and symbol keys with values from your workspace.

Collect a short nettrace from a process

Arguments 
{
  "processId": 12345,
  "targetId": "COPY_FROM_FRESH_INVENTORY",
  "durationMs": 10000
}

Full MCP request

Full MCP request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "trace_attach",
    "arguments": {
      "processId": 12345,
      "targetId": "COPY_FROM_FRESH_INVENTORY",
      "durationMs": 10000
    }
  }
}

Response Notes

Returns a stored session with a nettrace or sensitive ETL artifact and normalized evidence. ETW reports provider, loss, clock, stack, and process identity coverage; missing events do not prove absence.

From GliderTrace 1.0.0: targetId is required alongside processId. First call trace_list_processes and copy both values from the same fresh item. Replace the example token; do not construct one from the PID. Check the operation capability and obtain permission for the selected target. Missing, stale, unreadable, and unsupported targets are rejected before capture. Refresh inventory after an identity error.

The server checks process start time before capture and again before collector invocation. The collector still accepts a PID, so these checks cannot eliminate replacement during handoff. The session summary retains targetId, targetStartedAt, targetRuntimeFamily, backend, targetValidation, and targetIdentityScope. EventPipe, dump, and GC dump capture require CoreCLR. A Windows ETW profile from GliderTrace 1.1.0 adds bounded capture for a verified Framework IIS worker.

GliderTrace 1.0.0 returns compact JSON for every tool. Result fields appear beside success; there is no response-format parameter. success describes the tool call. Check the process or session status and exitCode separately. Scalar results and fields that conflict with reserved names appear under result.

To migrate an envelope consumer, read response.sessionId instead of response.data.sessionId. Stored sessions and exported files keep their formats. --max-response-chars limits response text to 60,000 UTF-16 characters by default. Use 0 to disable it, or at least 1,000. This limit counts text characters, not transport bytes or tokens.

outputLimit.truncated marks omitted response detail. It does not change capture completeness. Use the returned next tool and arguments when available. Do not repeat a command or feedback submission to recover omitted output. For event pages, keep the filters and cursor while reducing limit.

For session details, set includeArtifacts and includeTopFindings to false to reduce output. Check error, actionable meta, warnings, and coverage before drawing conclusions. Internal diagnostics stay in local server logs.