Documentation
¶
Overview ¶
Package metrics provides Prometheus metrics for the klaus server.
These metrics cover the server-side view of prompt handling, process lifecycle, and cost tracking. They complement the Claude Code CLI's native OpenTelemetry telemetry (claude_code.* namespace) with server-level observability in the klaus_* namespace.
Index ¶
Constants ¶
const ( StatusStarting = "starting" StatusIdle = "idle" StatusBusy = "busy" StatusCompleted = "completed" StatusStopped = "stopped" StatusError = "error" )
Process status label values exposed via ProcessStatusGauge. They mirror claude.AllProcessStatuses (verified by sync_test.go).
Variables ¶
var AllStatuses = []string{StatusStarting, StatusIdle, StatusBusy, StatusCompleted, StatusStopped, StatusError}
AllStatuses is the complete list of process status labels used by the ProcessStatusGauge. It must match claude.AllProcessStatuses -- a cross- package test in sync_test.go enforces this at test time.
var MessagesTotal = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: namespace, Name: "messages_total", Help: "Total number of stream-json messages processed.", }, []string{"type"})
MessagesTotal counts messages processed from the Claude subprocess.
var ProcessRestartsTotal = promauto.NewCounter(prometheus.CounterOpts{
Namespace: namespace,
Name: "process_restarts_total",
Help: "Total number of automatic persistent process restarts.",
})
ProcessRestartsTotal counts automatic restarts of the persistent subprocess.
var ProcessStatusGauge = promauto.NewGaugeVec(prometheus.GaugeOpts{ Namespace: namespace, Name: "process_status", Help: "Current process status (1 for active status, 0 for others).", }, []string{labelStatus})
ProcessStatusGauge is a gauge indicating the current process state. Only the label matching the active status is set to 1; all others are 0.
var PromptDurationSeconds = promauto.NewHistogramVec(prometheus.HistogramOpts{ Namespace: namespace, Name: "prompt_duration_seconds", Help: "Duration of prompt execution in seconds.", Buckets: prometheus.ExponentialBuckets(1, 2, 12), }, []string{labelStatus, "mode"})
PromptDurationSeconds tracks the end-to-end duration of prompt execution.
var PromptsTotal = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: namespace, Name: "prompts_total", Help: "Total number of prompt invocations.", }, []string{labelStatus, "mode"})
PromptsTotal counts the number of prompt invocations.
var SessionCostUSDTotal = promauto.NewCounter(prometheus.CounterOpts{
Namespace: namespace,
Name: "session_cost_usd_total",
Help: "Cumulative session cost in USD.",
})
SessionCostUSDTotal tracks cumulative cost from stream-json total_cost_usd.
var ToolCallsTotal = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: namespace, Name: "tool_calls_total", Help: "Total number of tool calls made by the Claude agent.", }, []string{"tool_name"})
ToolCallsTotal counts tool invocations by the Claude subprocess. The tool_name label values come from the Claude CLI's finite built-in tool set (Bash, Read, Edit, etc.). A cardinality guard (maxToolNameLabels) prevents unbounded series growth if user-defined tools are ever forwarded through this path; excess tool names are bucketed under "other".
Functions ¶
func RecordCost ¶
func RecordCost(delta float64)
RecordCost adds a cost increment to the cumulative cost counter. For persistent-mode processes where TotalCost is a running total, the caller must compute the delta before calling this function.
func RecordStreamMessage ¶
func RecordStreamMessage(msgType, subtype, toolName string)
RecordStreamMessage records per-message Prometheus metrics from a parsed stream-json message. The caller passes the raw string values of the message fields to avoid a circular import on pkg/claude.
func SetProcessStatus ¶
func SetProcessStatus(status string)
SetProcessStatus sets the process status gauge, setting the given status to 1 and all others to 0. The update is atomic with respect to concurrent callers.
Types ¶
This section is empty.
Source Files