Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultConfig() config.MonitorConfig
- func NewResource(service monitor.Service, streams event.StreamInspector) api.Resource
- func NewService(cfg *config.MonitorConfig, buildInfo *monitor.BuildInfo) monitor.Service
- type DefaultService
- func (s *DefaultService) BuildInfo() *monitor.BuildInfo
- func (s *DefaultService) CPU(context.Context) (*monitor.CPUInfo, error)
- func (s *DefaultService) Close() error
- func (*DefaultService) Disk(ctx context.Context) (*monitor.DiskInfo, error)
- func (*DefaultService) Host(ctx context.Context) (*monitor.HostInfo, error)
- func (s *DefaultService) Init(context.Context) error
- func (*DefaultService) Load(ctx context.Context) (*monitor.LoadInfo, error)
- func (s *DefaultService) Memory(ctx context.Context) (*monitor.MemoryInfo, error)
- func (*DefaultService) Network(ctx context.Context) (*monitor.NetworkInfo, error)
- func (s *DefaultService) Overview(ctx context.Context) (*monitor.SystemOverview, error)
- func (s *DefaultService) Process(context.Context) (*monitor.ProcessInfo, error)
- type Resource
- func (r *Resource) GetBuildInfo(ctx fiber.Ctx) error
- func (r *Resource) GetCPU(ctx fiber.Ctx) error
- func (r *Resource) GetDisk(ctx fiber.Ctx) error
- func (r *Resource) GetEventStreams(ctx fiber.Ctx) error
- func (r *Resource) GetHost(ctx fiber.Ctx) error
- func (r *Resource) GetLoad(ctx fiber.Ctx) error
- func (r *Resource) GetMemory(ctx fiber.Ctx) error
- func (r *Resource) GetNetwork(ctx fiber.Ctx) error
- func (r *Resource) GetOverview(ctx fiber.Ctx) error
- func (r *Resource) GetProcess(ctx fiber.Ctx) error
Constants ¶
const ( // DefaultSampleInterval is the default interval between CPU and process sampling. // Sample every 10 seconds provides a good balance between accuracy and overhead. DefaultSampleInterval = 10 * time.Second // DefaultSampleDuration is the default sampling window duration for CPU and process metrics. // A 2-second window smooths short-term fluctuations while providing responsive metrics. DefaultSampleDuration = 2 * time.Second )
Variables ¶
var ( // ErrCPUInfoNotReady indicates CPU information is not yet available from background sampling. ErrCPUInfoNotReady = errors.New("cpu info not ready") // ErrProcessInfoNotReady indicates process information is not yet available from background sampling. ErrProcessInfoNotReady = errors.New("process info not ready") )
var Module = fx.Module( "vef:monitor", fx.Provide( fx.Annotate( NewService, fx.ParamTags(`optional:"true"`, `optional:"true"`), fx.OnStart(func(ctx context.Context, svc monitor.Service) error { if initializer, ok := svc.(contract.Initializer); ok { if err := initializer.Init(ctx); err != nil { return fmt.Errorf("failed to initialize monitor service: %w", err) } } return nil }), fx.OnStop(func(svc monitor.Service) error { if closer, ok := svc.(io.Closer); ok { if err := closer.Close(); err != nil { return fmt.Errorf("failed to close monitor service: %w", err) } } return nil }), ), fx.Annotate( NewResource, fx.ParamTags(``, `optional:"true"`), fx.ResultTags(`group:"vef:api:resources"`), ), ), )
Module is the FX module for system monitoring functionality. NewService owns all config and build-info defaulting (including stamping the framework version), so both inputs are supplied optionally and need no decorator.
Functions ¶
func DefaultConfig ¶
func DefaultConfig() config.MonitorConfig
DefaultConfig returns the default monitor configuration. This configuration provides reasonable defaults for most use cases: - 10 second sampling interval (20% duty cycle with 2s window) - 2 second sampling window (smooths CPU spikes).
func NewResource ¶
NewResource creates a new monitor resource with the provided service. The stream inspector is optional — nil when the redis_stream transport is off — and gates the event-streams endpoint.
func NewService ¶
NewService creates a new monitor.Service implementation. A nil cfg or zero-valued fields fall back to DefaultConfig; a nil buildInfo falls back to unknown metadata. The framework version is always stamped onto the returned build info.
Types ¶
type DefaultService ¶
type DefaultService struct {
// contains filtered or unexported fields
}
DefaultService implements monitor.Service with background CPU and process sampling.
CPU and memory metrics are container-aware: when the process runs under a cgroup (v2 or v1) that actually limits the resource, the limit and the cgroup's own usage replace the host-wide numbers; without a limit the host view is reported unchanged. Process and network metrics are whatever procfs exposes — the host's when reachable (host PID/network namespace), otherwise the container's own namespace.
func (*DefaultService) BuildInfo ¶
func (s *DefaultService) BuildInfo() *monitor.BuildInfo
BuildInfo returns application build information. It is always non-nil: NewService fills unknown metadata and stamps the framework version at construction time.
func (*DefaultService) Close ¶
func (s *DefaultService) Close() error
Close gracefully stops the background sampling goroutines. It clears the sampler handles so a later Init can start a fresh sampler.
func (*DefaultService) Init ¶
func (s *DefaultService) Init(context.Context) error
Init starts background goroutines to periodically sample CPU and process metrics. It is idempotent while a sampler is running, and restartable after Close.
func (*DefaultService) Memory ¶
func (s *DefaultService) Memory(ctx context.Context) (*monitor.MemoryInfo, error)
Memory returns memory usage information. Inside a memory-limited container the headline figures describe the container's limit and working set rather than the host's /proc/meminfo, which is not namespaced.
func (*DefaultService) Network ¶
func (*DefaultService) Network(ctx context.Context) (*monitor.NetworkInfo, error)
Network returns network interface and I/O statistics.
func (*DefaultService) Overview ¶
func (s *DefaultService) Overview(ctx context.Context) (*monitor.SystemOverview, error)
Overview returns a comprehensive system overview by fetching all metrics. It is best-effort and never returns an error: a sub-metric that fails to collect is logged and left nil so a single broken collector does not mask the rest. Callers should inspect individual fields rather than rely on the error.
func (*DefaultService) Process ¶
func (s *DefaultService) Process(context.Context) (*monitor.ProcessInfo, error)
Process returns information about the current process.
type Resource ¶
Resource handles system monitoring-related API endpoints.
func (*Resource) GetBuildInfo ¶
GetBuildInfo returns application build information.
func (*Resource) GetEventStreams ¶ added in v0.37.0
GetEventStreams reports cross-process event stream and consumer-group state so operators can spot orphaned groups (see monitor.EventStreamsInfo).
func (*Resource) GetNetwork ¶
GetNetwork returns network interface and I/O statistics.
func (*Resource) GetOverview ¶
GetOverview returns a comprehensive system overview.