api

Documentation

Index

• func NewRouter(store *storage.DB, hub *ws.Hub, fwd *forwarder.Forwarder) http.Handler
• func NewRouterFull(store *storage.DB, hub *ws.Hub, fwd *forwarder.Forwarder, ...) http.Handler
• func NewRouterWithManifests(store *storage.DB, hub *ws.Hub, fwd *forwarder.Forwarder, ...) http.Handler
• type DiffResult
• type DiffSessionInfo
• type DiffSpan
• type DiffSummary
• type DropCounterProvider
• type MetricSeriesExemplar
• type MetricSeriesPoint
• type MetricSeriesResponse
• type Router
• type SettingsResponse
• type SettingsRuntime
• type SettingsService
• type SettingsUpdate
• type SourcesProvider
• type ThroughputProvider
• type UpdateCheckResult

Functions

func NewRouter

func NewRouter(store *storage.DB, hub *ws.Hub, fwd *forwarder.Forwarder) http.Handler

func NewRouterFull

func NewRouterFull(store *storage.DB, hub *ws.Hub, fwd *forwarder.Forwarder, mfs *coverage.Manifests, settings *SettingsService, tp ThroughputProvider, dc DropCounterProvider, sp SourcesProvider) http.Handler

NewRouterFull is the canonical constructor. Pass nil for any optional dependency (manifests, settings, tp, dc, sp) to disable the corresponding feature.

func NewRouterWithManifests

func NewRouterWithManifests(store *storage.DB, hub *ws.Hub, fwd *forwarder.Forwarder, mfs *coverage.Manifests) http.Handler

NewRouterWithManifests is a back-compat shim — prefer NewRouterFull.

Types

type DiffResult

type DiffResult = diff.Result

Diff types are produced by the shared internal/diff package (also used by the MCP diff_sessions tool). These aliases preserve the api.* names the HTTP layer and the `spaniel diff` CLI already use.

type DiffSessionInfo

type DiffSessionInfo = diff.SessionInfo

Diff types are produced by the shared internal/diff package (also used by the MCP diff_sessions tool). These aliases preserve the api.* names the HTTP layer and the `spaniel diff` CLI already use.

type DiffSpan

type DiffSpan = diff.Span

Diff types are produced by the shared internal/diff package (also used by the MCP diff_sessions tool). These aliases preserve the api.* names the HTTP layer and the `spaniel diff` CLI already use.

type DiffSummary

type DiffSummary = diff.Summary

Diff types are produced by the shared internal/diff package (also used by the MCP diff_sessions tool). These aliases preserve the api.* names the HTTP layer and the `spaniel diff` CLI already use.

type DropCounterProvider

type DropCounterProvider interface {
	DroppedSpansTotal() int64
	DroppedLogsTotal() int64
	DroppedMetricPointsTotal() int64
	LastDropAt() int64
}

DropCounterProvider returns process-level drop counters. Implemented by *ingestion.Pipeline via its Counters field; nil means sampling is disabled.

type MetricSeriesExemplar

type MetricSeriesExemplar struct {
	TraceID string `json:"trace_id"`
	SpanID  string `json:"span_id"`
}

type MetricSeriesPoint

type MetricSeriesPoint struct {
	TimestampNs int64                  `json:"timestamp_ns"`
	Value       float64                `json:"value"`
	Percentile  string                 `json:"percentile,omitempty"`
	Exemplars   []MetricSeriesExemplar `json:"exemplars,omitempty"`
}

MetricSeriesPoint represents one metric data point with optional exemplars. Histogram percentiles arrive bucketed into p50/p95/p99 slices on the client; gauge/counter populate only Value. Exemplars link to traces via trace_id/span_id.

type MetricSeriesResponse

type MetricSeriesResponse struct {
	Name        string              `json:"name"`
	ServiceName string              `json:"service_name"`
	Type        string              `json:"type"`
	Unit        string              `json:"unit"`
	Description string              `json:"description"`
	Points      []MetricSeriesPoint `json:"points"`
	// Traces is populated only when ?with_traces=1 is passed. Always
	// materialized as [] (never null) so the frontend type can be
	// non-optional and rendering branches stay flat.
	Traces []*storage.TraceOverlay `json:"traces"`
}

type Router

type Router struct {
	// contains filtered or unexported fields
}

type SettingsResponse

type SettingsResponse struct {
	Port           int      `json:"port"`
	DBPath         string   `json:"db_path"`
	RetentionDays  int      `json:"retention_days"`
	MaxSessions    int      `json:"max_sessions"`
	MaxDBSizeMB    int      `json:"max_db_size_mb"`
	OTLPGRPCPort   int      `json:"otlp_grpc_port"`
	OTLPHTTPPort   int      `json:"otlp_http_port"`
	NoBrowser      bool     `json:"no_browser"`
	Forward        []string `json:"forward"`
	BindAddressV4  string   `json:"bind_address_v4"`
	BindAddressV6  string   `json:"bind_address_v6"`
	ForwardSample  float64  `json:"forward_sample"`
	SourceRPS      float64  `json:"source_rps"`
	SourceBurst    int      `json:"source_burst"`
	TLSEnabled     bool     `json:"tls_enabled"`
	BearerTokenSet bool     `json:"bearer_token_set"`
	SelfMonitor    bool     `json:"self_monitor"`
	MCPEnabled     bool     `json:"mcp_enabled"`
	MCPAllowWrites bool     `json:"mcp_allow_writes"`

	Runtime SettingsRuntime `json:"runtime"`
}

SettingsResponse is the JSON shape returned by GET /api/settings. Persistable fields live at the top level; read-only info is under Runtime.

type SettingsRuntime

type SettingsRuntime struct {
	PID          int    `json:"pid"`
	UptimeNs     int64  `json:"uptime_ns"`
	Version      string `json:"version"`
	Channel      string `json:"channel"`
	ConfigPath   string `json:"config_path"`
	OTLPGRPCPort int    `json:"otlp_grpc_port"`
	OTLPHTTPPort int    `json:"otlp_http_port"`
	DBSizeBytes  int64  `json:"db_size_bytes"`
}

SettingsRuntime is everything the UI shows but never writes back.

type SettingsService

type SettingsService struct {
	Viper          *viper.Viper
	ConfigPath     string // path to the file Save() will write
	Version        string
	StartedAt      time.Time
	OTLPGRPCPort   int
	OTLPHTTPPort   int
	TLSEnabled     bool
	BearerTokenSet bool
	MCPEnabled     bool
	MCPAllowWrites bool

	// LiveGRPCPort / LiveHTTPPort return the port currently bound (0 = stopped).
	// When nil the startup values above are used (tests / minimal configs).
	LiveGRPCPort func() int
	LiveHTTPPort func() int

	// SetLiveGRPCPort / SetLiveHTTPPort hot-swap the running OTLP listener.
	// Called by applySettings when the port config changes; nil = no-op.
	SetLiveGRPCPort func(int) error
	SetLiveHTTPPort func(int) error

	// SetSelfMonitor enables or disables self-telemetry without a restart.
	// When enabled, Spaniel sends its own traces/metrics to its own OTLP gRPC
	// port. nil = setting is persisted but takes effect on next restart only.
	SetSelfMonitor func(bool) error

	// GithubClient is injected in tests to stub the GitHub API. nil = use
	// http.DefaultClient.
	GithubClient *http.Client
	// contains filtered or unexported fields
}

SettingsService is everything the settings endpoints need that isn't already on the Router (storage, hub, etc.). main.go builds one of these after viper has been bootstrapped and hands it to Router.SetSettingsService.

type SettingsUpdate

type SettingsUpdate struct {
	Port          *int      `json:"port,omitempty"`
	DBPath        *string   `json:"db_path,omitempty"`
	RetentionDays *int      `json:"retention_days,omitempty"`
	MaxSessions   *int      `json:"max_sessions,omitempty"`
	MaxDBSizeMB   *int      `json:"max_db_size_mb,omitempty"`
	OTLPGRPCPort  *int      `json:"otlp_grpc_port,omitempty"`
	OTLPHTTPPort  *int      `json:"otlp_http_port,omitempty"`
	NoBrowser     *bool     `json:"no_browser,omitempty"`
	Forward       *[]string `json:"forward,omitempty"`
	BindAddressV4 *string   `json:"bind_address_v4,omitempty"`
	BindAddressV6 *string   `json:"bind_address_v6,omitempty"`
	ForwardSample *float64  `json:"forward_sample,omitempty"`
	SourceRPS     *float64  `json:"source_rps,omitempty"`
	SourceBurst   *int      `json:"source_burst,omitempty"`
	SelfMonitor   *bool     `json:"self_monitor,omitempty"`
}

SettingsUpdate is the writable subset accepted by PUT /api/settings. Pointer fields let clients send partial updates — nil = "leave as-is".

type SourcesProvider

type SourcesProvider interface {
	Sources() []storage.SourceStats
}

SourcesProvider returns per-source ingest stats. Implemented by *ingestion.Pipeline.

type ThroughputProvider

type ThroughputProvider interface {
	Throughput() storage.Throughput
}

ThroughputProvider returns live per-second ingest rates. Implemented by *ingestion.Pipeline; nil means no live rates are available.

type UpdateCheckResult

type UpdateCheckResult struct {
	Current         string `json:"current"`
	Latest          string `json:"latest"`
	Channel         string `json:"channel"`
	IsOutdated      bool   `json:"is_outdated"`
	ReleaseNotesURL string `json:"release_notes_url"`
	CheckedAtNs     int64  `json:"checked_at_ns"`
	Error           string `json:"error,omitempty"`
}

UpdateCheckResult is the JSON shape returned by POST /api/settings/check-updates.