diagnostics

The diagnostics domain has 12 actions. On the meta surface they are all reached through arcane_diagnostics; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
`diagnostics.actors`	Get actor diagnostics for an environment	read
`diagnostics.actors_stream`	Sample actor diagnostics of all environments	read
`diagnostics.goroutines`	Get goroutine diagnostics for an environment	read
`diagnostics.pprof_cmdline`	Get the server command line	read
`diagnostics.pprof_cpu_profile`	Capture a CPU profile	read
`diagnostics.pprof_index`	List pprof profiles	read
`diagnostics.pprof_profile`	Get a runtime profile	read
`diagnostics.pprof_symbol`	Resolve program counters to symbols	read
`diagnostics.pprof_trace`	Capture an execution trace	read
`diagnostics.run_command`	Run a diagnostics command	read
`diagnostics.server_logs`	Get Arcane server logs	read
`diagnostics.snapshot`	Get server diagnostics	read

Actions

`diagnostics.actors`

Get actor diagnostics for an environment

Returns Francis actor host, actor type, and run queue diagnostics for one environment.

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "actors"
Individual tool: arcane_diagnostics_actors
Arcane route: GET /api/environments/{id}/diagnostics/actors
Operation ID: get-environment-actor-diagnostics
Since: Arcane v2.15.0
Usage: environmentId comes from environment.list. A remote environment is answered by its agent. The result has ready (false with empty data while the actor runtime starts), hosts, actorTypes (active actors, pending jobs and alarms, dead and completed job counts, up to 10 recent instances and failures with lastError) and runs counted by status. Use diagnostics.actors_stream to see every environment at once. Investigate failed runs with job.list_runs.
Related actions: environment.list, diagnostics.actors_stream, job.list_runs, job.list

`diagnostics.actors_stream`

Sample actor diagnostics of all environments

Sample the live actor (background worker) diagnostics of every environment, as pushed by Arcane’s actors diagnostics stream

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "actors_stream"
Individual tool: arcane_diagnostics_actors_stream
Arcane route: GET /api/diagnostics/actors/stream (WebSocket)
Operation ID: ws-diagnostics-actors-stream
Since: Arcane v2.15.0
Usage: Each sample is a list with one entry per environment (local first, then every active remote one), each with environmentId, environmentName, ready, hosts, actorTypes, runs by status and an error string when that environment could not be reached. Arcane pushes on connect and then every 10 seconds, so keep samples=1 unless you want to watch changes. Use diagnostics.actors for a single environment. Needs the diagnostics read permission.
Related actions: diagnostics.actors, environment.list, job.list_runs

`diagnostics.goroutines`

Get goroutine diagnostics for an environment

Returns the live goroutines grouped by identical stack, largest group first.

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "goroutines"
Individual tool: arcane_diagnostics_goroutines
Arcane route: GET /api/environments/{id}/diagnostics/goroutines
Operation ID: get-environment-goroutine-diagnostics
Since: Arcane v2.16.0
Usage: environmentId comes from environment.list. A remote environment reports its agent’s goroutines. Returns total, capturedAt and groups of goroutines sharing an identical stack (count, label naming the entry function, frames with function, file and line), largest first: a quick way to spot pile-ups without administrator rights. For raw pprof output use diagnostics.pprof_profile with name goroutine (global administrators only).
Related actions: diagnostics.snapshot, diagnostics.run_command, diagnostics.pprof_profile, environment.list

`diagnostics.pprof_cmdline`

Get the server command line

Return the Arcane server process’s command line (pprof cmdline, global administrators only)

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "pprof_cmdline"
Individual tool: arcane_diagnostics_pprof_cmdline
Arcane route: GET /api/debug/pprof/cmdline
Operation ID: pprof-cmdline
Usage: Returns the process arguments as text in content, separated by NUL bytes. Use diagnostics.snapshot for the Go version, OS and uptime instead.
Related actions: diagnostics.pprof_index, diagnostics.snapshot

`diagnostics.pprof_cpu_profile`

Capture a CPU profile

Capture a CPU profile of the Arcane server for a number of seconds and return it as a base64 pprof protobuf (global administrators only)

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "pprof_cpu_profile"
Individual tool: arcane_diagnostics_pprof_cpu_profile
Arcane route: GET /api/debug/pprof/profile
Operation ID: pprof-profile
Usage: Blocks for the whole capture (default 30 s) and returns a gzipped pprof file for go tool pprof. Keep seconds below arcane-mcp’s request timeout (60 s unless ARCANE_MCP_TIMEOUT changes it). Only one CPU profile can run at a time on the server.
Related actions: diagnostics.pprof_symbol, diagnostics.pprof_trace, diagnostics.pprof_profile, diagnostics.snapshot

`diagnostics.pprof_index`

List pprof profiles

Return the Go pprof index of the Arcane server: the available runtime profiles and their counts (global administrators only)

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "pprof_index"
Individual tool: arcane_diagnostics_pprof_index
Arcane route: GET /api/debug/pprof/
Operation ID: pprof-index
Usage: Returns the pprof index as an HTML page in content, listing each profile name with its count. Use it to see which profile names exist before calling diagnostics.pprof_profile. All pprof actions require a global administrator.
Related actions: diagnostics.pprof_profile, diagnostics.pprof_cpu_profile, diagnostics.pprof_trace, diagnostics.goroutines

`diagnostics.pprof_profile`

Get a runtime profile

Return a named Go runtime profile of the Arcane server (goroutine, heap, allocs, block, mutex, threadcreate), as text or as a base64 pprof protobuf (global administrators only)

Kind: read
Required parameters: name
Meta tool: arcane_diagnostics with "action": "pprof_profile"
Individual tool: arcane_diagnostics_pprof_profile
Arcane route: GET /api/debug/pprof/{name}
Operation ID: pprof-named
Usage: Profile names come from diagnostics.pprof_index. debug=1 returns readable text in content (debug=2 gives full goroutine stacks). debug 0 returns a gzipped pprof file. seconds returns the difference over that interval (supported for every one of these profiles) and cannot be combined with debug, which Go rejects with ‘seconds and debug params are incompatible’. For a grouped goroutine summary use diagnostics.goroutines.
Related actions: diagnostics.pprof_index, diagnostics.pprof_symbol, diagnostics.goroutines, diagnostics.pprof_cpu_profile

`diagnostics.pprof_symbol`

Resolve program counters to symbols

Resolve program counter addresses of the Arcane server to function names (pprof symbol, global administrators only)

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "pprof_symbol"
Individual tool: arcane_diagnostics_pprof_symbol
Arcane route: GET /api/debug/pprof/symbol
Arcane route: POST /api/debug/pprof/symbol
Operation ID: pprof-symbol
Usage: Take the 0x addresses from a diagnostics.pprof_profile debug=1 dump. With addresses the content lists each address with its function name. Without them it returns only num_symbols.
Related actions: diagnostics.pprof_profile, diagnostics.pprof_cpu_profile

`diagnostics.pprof_trace`

Capture an execution trace

Capture a Go execution trace of the Arcane server for a number of seconds and return it base64-encoded (global administrators only)

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "pprof_trace"
Individual tool: arcane_diagnostics_pprof_trace
Arcane route: GET /api/debug/pprof/trace
Operation ID: pprof-trace
Usage: Blocks for the capture (default 1 s) and returns a binary trace for go tool trace. Traces grow quickly, so keep seconds small. Use diagnostics.pprof_cpu_profile to find where CPU time goes instead of scheduling and latency detail.
Related actions: diagnostics.pprof_cpu_profile, diagnostics.pprof_profile, diagnostics.pprof_index

`diagnostics.run_command`

Run a diagnostics command

Run a diagnostics command on the Arcane server: a goroutine leak scan, a text dump of a runtime profile, or a timed profile capture

Kind: read
Required parameters: command
Meta tool: arcane_diagnostics with "action": "run_command"
Individual tool: arcane_diagnostics_run_command
Arcane route: GET /api/diagnostics/stream (WebSocket)
Operation ID: ws-diagnostics-command
Usage: leakScan needs only the diagnostics read permission and returns leakReport (count, profile text, scannedAt). dump and profile fail with ‘profiles require a global administrator’ otherwise. dump returns the named profile as debug=2 text (full stacks for goroutine). profile returns it base64-encoded in data, and seconds only matters for name ‘profile’ (CPU profile) or ‘trace’, since Arcane snapshots every other profile immediately and rejects ‘cpu’ as unknown. For downloadable pprof files prefer diagnostics.pprof_profile, diagnostics.pprof_cpu_profile or diagnostics.pprof_trace.
Related actions: diagnostics.snapshot, diagnostics.goroutines, diagnostics.pprof_profile, diagnostics.pprof_cpu_profile

`diagnostics.server_logs`

Get Arcane server logs

Return the Arcane server’s own recent log entries, optionally listening for new ones for a few seconds

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "server_logs"
Individual tool: arcane_diagnostics_server_logs
Arcane route: GET /api/diagnostics/logs/stream (WebSocket)
Operation ID: ws-diagnostics-logs-stream
Usage: These are Arcane’s own backend logs, not a container’s (use container.logs for those). Arcane first replays its in-memory backlog of up to 1000 recent entries, then streams new ones until seconds elapse or maxLines entries arrive. The result has count, entries (time, level, message, attrs) and why collection stopped. The backlog is replayed oldest first, so when it holds more than maxLines (default 500) you get the oldest entries: raise maxLines above 1000 to reach the newest. Needs the diagnostics read permission.
Related actions: diagnostics.snapshot, event.list, container.logs

`diagnostics.snapshot`

Get server diagnostics

Return a snapshot of the Arcane server’s runtime diagnostics: goroutines, memory, WebSocket connections and background workers

Kind: read
Required parameters: none
Meta tool: arcane_diagnostics with "action": "snapshot"
Individual tool: arcane_diagnostics_snapshot
Arcane route: GET /api/diagnostics/stream (WebSocket)
Operation ID: ws-diagnostics-stream
Usage: Server-wide (no environmentId). Needs the diagnostics read permission, not an administrator. Arcane pushes one snapshot on connect and then one every 2 seconds, so samples=1 returns at once. Each sample’s snapshot holds runtime (goroutines, leakedGoroutines, goVersion, uptimeSeconds), memory, gc and websocket connection metrics. Follow up with diagnostics.goroutines to see where goroutines sit or diagnostics.run_command leakScan to check for leaks.
Related actions: diagnostics.goroutines, diagnostics.run_command, diagnostics.server_logs, system.stats