Diagnostics API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The Diagnostics API provides profiling and runtime statistics endpoints for performance analysis and troubleshooting. The primary endpoint generates Go pprof profiles from running grid modules.

Source: src/grid/client/rest.go

Authentication

All endpoints require JWT cookie or API token authentication.

Endpoints

Method	Path	Description	Auth required
POST	/internal/v1/pprof	Generate a profiling snapshot for a grid module	JWT + API token

---

POST /internal/v1/pprof

Generate a Go pprof profile from a running grid module. The response is a gzip-compressed binary profile file that can be analyzed with standard Go profiling tools.

Request:

POST /internal/v1/pprof
Content-Type: application/json
Authorization: Bearer <token>

{
  "client": "node-uuid",
  "module": "grid.client",
  "profile": "cpu"
}

Request fields:

Field	Type	Required	Description
client	string	Yes	Grid client node ID to profile
module	string	No	Module name (default: grid.client)
profile	string	Yes	Profile type to collect

Available profile types:

Profile	Description
cpu	CPU usage profile (30-second sample)
allocs	Memory allocation profile
heap	Heap memory profile
goroutine	Goroutine stack traces
block	Blocking profile
mutex	Mutex contention profile
threadcreate	Thread creation profile

Response (200): Binary gzip-compressed pprof data.

Response headers:

Header	Value
Content-Disposition	attachment; filename=hydden-{profile}-{timestamp}.out
Content-Type	application/octet-stream

Usage with Go tools:

# Download profile
curl -X POST "https://portal/internal/v1/pprof" \
  -H "Authorization: Bearer <token>" \
  -d '{"client":"node-uuid","profile":"cpu"}' \
  -o cpu.out

# Analyze with pprof
go tool pprof cpu.out

---

Grid Runtime Statistics (gRPC only)

The grid module also exposes runtime statistics via gRPC (no REST surface). These are defined in src/grid/api/grid_api.proto:

Available via gRPC:

Message	Fields	Description
Stats	nID, disk, version, error, runtime, component, uptime	Node runtime statistics
DiskStats	total, free	Disk usage statistics
Runtime	version, maxProcs, arch, oS, env	Go runtime information

These statistics are used internally by the grid cluster management layer and are not exposed via REST.

---

Error Responses

Status	Description
400	Invalid request body or unknown profile type
403	Authentication failed or insufficient permissions
404	Target node not found or offline
500	Profiling failed (target module unresponsive)

Related Topics

• Dashboard Widgets API — System resource metrics (CPU, memory, disk)
• Audit API — Audit logs and metrics