API Overview

kprobe exposes a gRPC API for querying the causal graph, retrieving timeline data, managing replay sessions, and streaming live kernel events. The API is defined in Protocol Buffers and serves both the dashboard and any external integrations.

Transport

The API server exposes gRPC on port 8080 by default. It speaks gRPC over HTTP/2.

For browser clients (the dashboard), the API also exposes an HTTP/WebSocket server on port 8081. Live event streaming is available at ws://localhost:8081/ws. During console development, Vite proxies /ws, /auth, and /api to localhost:8081.

Authentication

In local development, the HTTP login endpoint accepts the configured development credentials, defaulting to admin / admin. gRPC requests require an authorization: Bearer ... metadata value; the default development token is dev-token.

In production Kubernetes deployments, the API server is not exposed externally by default. It is accessed via kubectl port-forward or through an internal service mesh. If you expose it externally, configure authentication via the Helm values:

api:
  auth:
    enabled: true
    type: bearer
    secret: your-secret-here

Core concepts

Requests and transactions

The primary query unit is an application operation identified by a request ID, transaction ID, trace ID, or other domain-specific identifier. Causal graph queries, timeline queries, and replay sessions are anchored to that identifier.

Events

Every piece of data kprobe captures is an event. Events have:

  • timestamp_ns — nanosecond Unix timestamp
  • pid — process ID
  • tid — thread ID
  • cpu — CPU core
  • event_type — one of TCPSend, TCPRecv, SyscallRead, SyscallWrite, SchedSwitch, PageFault
  • duration_ns — event duration in nanoseconds
  • application_context — correlated request or transaction ID, service name, trace ID, and operation metadata when available

Causal graph

A directed graph of events where edges represent causal relationships. Returned as an adjacency list of nodes and edges. Each edge has a latency_contribution_ns field representing its weight in the causal analysis.

gRPC services

The current API exposes two gRPC services:

ServicePurpose
KprobeServiceQuery causal graphs, retrieve event timelines, and stream live events
ReplayServiceCreate and manage replay sessions

See the gRPC Reference for full method documentation.

WebSocket streaming

The WebSocket endpoint streams live kernel events to the dashboard in real time. Connect to ws://localhost:8081/ws. Events are pushed as JSON messages as they arrive from the API broadcast hub.