admin

package
v0.1.0-alpha.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 20, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package admin provides optional, bounded observability consumers for Meldbase. It is deliberately separate from the database package: creating a DB never starts a sampler, a goroutine, or a network listener.

Index

Constants

View Source 
const PrometheusContentType = "text/plain; version=0.0.4; charset=utf-8"
View Source 
const SchemaVersion uint32 = 16

Variables

View Source 
var (
	ErrRuntimeCaptureBusy  = errors.New("meldbase admin: another runtime capture is active")
	ErrRuntimeCaptureLimit = errors.New("meldbase admin: runtime capture byte limit reached")
)
View Source 
var (
	ErrClosed          = errors.New("meldbase admin: sampler closed")
	ErrSubscriberLimit = errors.New("meldbase admin: subscriber limit reached")
)

Functions

func MarshalPrometheus 

func MarshalPrometheus(sample Sample) []byte

MarshalPrometheus renders one sampled database state using the Prometheus text exposition format 0.0.4. It emits only fixed metric names and fixed-enum labels; no application-controlled string can enter the output.

Types

type Authorizer 

type Authorizer func(*http.Request) bool

func NewBearerTokenAuthorizer 

func NewBearerTokenAuthorizer(token string) (Authorizer, error)

NewBearerTokenAuthorizer creates a constant-time Authorization header check. Tokens are intentionally not accepted in URLs, where they leak into logs and browser history.

type DiagnosticSource 

type DiagnosticSource interface {
	DiagnosticSnapshotAfter(after uint64, limit int) meldbase.DiagnosticSnapshot
}

type Handler 

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

func NewHandler 

func NewHandler(options HandlerOptions) (*Handler, error)

func (*Handler) ServeHTTP 

func (h *Handler) ServeHTTP(writer http.ResponseWriter, request *http.Request)

type HandlerOptions 

type HandlerOptions struct {
	Sampler        *Sampler
	Authorize      Authorizer
	AllowedOrigins []string
	WriteTimeout   time.Duration
	ServeDashboard bool
	ServeMetrics   bool
	Diagnostics    DiagnosticSource
}

type HealthLevel 

type HealthLevel string
const (
	HealthUnavailable HealthLevel = "unavailable"
	HealthHealthy     HealthLevel = "healthy"
	HealthDegraded    HealthLevel = "degraded"
	HealthCritical    HealthLevel = "critical"
)

func (HealthLevel) Severity 

func (level HealthLevel) Severity() (uint64, bool)

Severity maps stable health enums to aggregate metric values: healthy=0, degraded=1, critical=2. Unavailable is intentionally omitted by exporters.

type HealthSignals 

type HealthSignals struct {
	DatabaseClosed               bool `json:"databaseClosed"`
	WritesDisabled               bool `json:"writesDisabled"`
	ReactiveQueuePressure        bool `json:"reactiveQueuePressure"`
	ReactiveQueueOverflow        bool `json:"reactiveQueueOverflow"`
	SlowConsumer                 bool `json:"slowConsumer"`
	PersistentFreeSpaceDiscarded bool `json:"persistentFreeSpaceDiscarded"`
	CommitRetentionPressure      bool `json:"commitRetentionPressure"`
	IndexBuildFailed             bool `json:"indexBuildFailed"`
	IndexBuildRetentionPressure  bool `json:"indexBuildRetentionPressure"`
	StorageQuotaExhausted        bool `json:"storageQuotaExhausted"`
	StorageLimitRejected         bool `json:"storageLimitRejected"`
	CommitCoordinatorPressure    bool `json:"commitCoordinatorPressure"`
	CommitCoordinatorRejected    bool `json:"commitCoordinatorRejected"`
	PrimaryWriteFenceRejected    bool `json:"primaryWriteFenceRejected"`
	DurabilityFailure            bool `json:"durabilityFailure"`
	RollbackAnchorDegraded       bool `json:"rollbackAnchorDegraded"`
	TelemetryDeliveryDropped     bool `json:"telemetryDeliveryDropped"`
	TransportBusy                bool `json:"transportBusy"`
	RPCOutcomeUnknown            bool `json:"rpcOutcomeUnknown"`
	WorkerProtocolFailure        bool `json:"workerProtocolFailure"`
}

HealthSignals is a fixed-cardinality explanation of the current assessment. Event signals describe increases during the latest sample window; state signals remain set while the underlying condition remains true.

type HealthStatus 

type HealthStatus struct {
	Overall    HealthLevel   `json:"overall"`
	Database   HealthLevel   `json:"database"`
	Durability HealthLevel   `json:"durability"`
	Storage    HealthLevel   `json:"storage"`
	Realtime   HealthLevel   `json:"realtime"`
	Telemetry  HealthLevel   `json:"telemetry"`
	Transport  HealthLevel   `json:"transport"`
	Signals    HealthSignals `json:"signals"`
}

type Rates 

type Rates struct {
	Valid                      bool    `json:"valid"`
	WindowSeconds              float64 `json:"windowSeconds"`
	CommitsPerSecond           float64 `json:"commitsPerSecond"`
	ChangesPerSecond           float64 `json:"changesPerSecond"`
	QueriesPerSecond           float64 `json:"queriesPerSecond"`
	FailedQueriesPerSecond     float64 `json:"failedQueriesPerSecond"`
	DocumentsExaminedPerSecond float64 `json:"documentsExaminedPerSecond"`
	DocumentsReturnedPerSecond float64 `json:"documentsReturnedPerSecond"`
	PublishedChangesPerSecond  float64 `json:"publishedChangesPerSecond"`
	DeltaDeliveriesPerSecond   float64 `json:"deltaDeliveriesPerSecond"`
	WALBytesPerSecond          float64 `json:"walBytesPerSecond"`
	PageCacheHitRatio          float64 `json:"pageCacheHitRatio"`
	DocumentCacheHitRatio      float64 `json:"documentCacheHitRatio"`
	RPCRequestsPerSecond       float64 `json:"rpcRequestsPerSecond"`
	RPCFailuresPerSecond       float64 `json:"rpcFailuresPerSecond"`
	RPCBusyPerSecond           float64 `json:"rpcBusyPerSecond"`
	RPCRatesValid              bool    `json:"rpcRatesValid"`
}

Rates contains process-session rates derived from two adjacent snapshots. Valid is false for the first sample and after a database reopen or counter reset. Ratios are cumulative for the current process session.

type RuntimeCaptureKind 

type RuntimeCaptureKind string
const (
	RuntimeCPUProfile  RuntimeCaptureKind = "cpu"
	RuntimeHeapProfile RuntimeCaptureKind = "heap"
	RuntimeTrace       RuntimeCaptureKind = "trace"
)

type RuntimeCaptureOptions 

type RuntimeCaptureOptions struct {
	// Duration applies to CPU profiles and runtime traces. Zero selects ten
	// seconds. Heap snapshots are immediate and require zero.
	Duration time.Duration
}

type RuntimeCaptureResult 

type RuntimeCaptureResult struct {
	Kind      RuntimeCaptureKind
	StartedAt time.Time
	Duration  time.Duration
	Bytes     int64
	Truncated bool
}

type RuntimeProfiler 

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

RuntimeProfiler owns bounded process-runtime captures. It does not start a listener or retain capture bytes. The caller owns authorization, the output writer and its lifetime. CPU profiles and runtime traces add process-wide overhead and should be enabled only for short diagnostic windows.

func NewRuntimeProfiler 

func NewRuntimeProfiler(options RuntimeProfilerOptions) (*RuntimeProfiler, error)

func (*RuntimeProfiler) Capture 

func (profiler *RuntimeProfiler) Capture(ctx context.Context, writer io.Writer, kind RuntimeCaptureKind, options RuntimeCaptureOptions) (result RuntimeCaptureResult, resultErr error)

func (*RuntimeProfiler) Stats 

func (profiler *RuntimeProfiler) Stats() RuntimeProfilerStats

type RuntimeProfilerOptions 

type RuntimeProfilerOptions struct {
	MaxDuration time.Duration
	MaxBytes    int64
}

type RuntimeProfilerStats 

type RuntimeProfilerStats struct {
	Active    uint64
	Attempts  uint64
	Completed uint64
	Failed    uint64
	Bytes     uint64
}

type Sample 

type Sample struct {
	Version  uint32                  `json:"version"`
	Sequence uint64                  `json:"sequence"`
	Stats    meldbase.DBStats        `json:"stats"`
	Rates    Rates                   `json:"rates"`
	Sampler  SamplerStatus           `json:"sampler"`
	Health   HealthStatus            `json:"health"`
	Server   *meldserver.ServerStats `json:"server,omitempty"`
}

Sample is an immutable point in the admin stream. Version identifies the admin snapshot schema, not the database storage format.

type Sampler 

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

Sampler periodically reads DB.Stats and retains a fixed-size history. Each subscriber has a single replaceable slot, so a slow consumer can never block sampling or database work.

func NewSampler 

func NewSampler(source StatsSource, options SamplerOptions) (*Sampler, error)

func (*Sampler) Close 

func (s *Sampler) Close() error

func (*Sampler) History 

func (s *Sampler) History() []Sample

func (*Sampler) Latest 

func (s *Sampler) Latest() (Sample, bool)

func (*Sampler) Status 

func (s *Sampler) Status() SamplerStatus

func (*Sampler) Subscribe 

func (s *Sampler) Subscribe(ctx context.Context) (*Subscription, error)

type SamplerOptions 

type SamplerOptions struct {
	Interval       time.Duration
	HistorySize    int
	MaxSubscribers int
	Server         ServerStatsSource
}

type SamplerStatus 

type SamplerStatus struct {
	Samples           uint64 `json:"samples"`
	Subscribers       uint64 `json:"subscribers"`
	DroppedDeliveries uint64 `json:"droppedDeliveries"`
	HistorySamples    uint64 `json:"historySamples"`
}

type ServerStatsSource 

type ServerStatsSource interface {
	Stats() meldserver.ServerStats
}

type StatsSource 

type StatsSource interface {
	Stats() meldbase.DBStats
}

StatsSource is implemented by *meldbase.DB.

type Subscription 

type Subscription struct {
	C <-chan Sample
	// contains filtered or unexported fields
}

func (*Subscription) Close 

func (s *Subscription) Close()

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.