Documentation
¶
Overview ¶
Package monitoring generates monitoring-stack configuration files for the nSelf CLI. Prometheus, Loki, Promtail, and Alertmanager configs are all built here and written into the target project's `monitoring/` directory by `nself build` when MONITORING_ENABLED=true.
This package owns *config generation*, not the docker-compose service definitions (those live in docker-compose.monitoring.yml — or, soon, the nself-monitoring free plugin).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderLokiYAML ¶
func RenderLokiYAML(cfg *LokiConfig) ([]byte, error)
RenderLokiYAML returns loki.yml bytes for cfg.
func RenderPrometheusYAML ¶
func RenderPrometheusYAML(cfg *PrometheusConfig) ([]byte, error)
RenderPrometheusYAML returns the rendered prometheus.yml bytes for cfg. Targets are emitted in stable order (alphabetical by job name) so repeated builds produce byte-identical output — critical for snapshot tests and for avoiding noisy diffs in generated config.
func RenderPromtailYAML ¶
func RenderPromtailYAML(cfg *PromtailConfig) ([]byte, error)
RenderPromtailYAML returns promtail.yml bytes for cfg.
Types ¶
type LokiConfig ¶
type LokiConfig struct {
// RetentionPeriod is how long logs are kept. Loki accepts Go-style
// durations (e.g. "720h" = 30d, "2160h" = 90d).
RetentionPeriod string
// MaxChunkAge caps how long a chunk can stay open before forced flush.
MaxChunkAge string
// MultiTenantEnabled, when true, runs Loki in multi-tenant mode with
// per-tenant isolation. Each nSelf project becomes a tenant.
MultiTenantEnabled bool
// RuleEngineEnabled turns on the Loki rule engine for log-based alerts.
RuleEngineEnabled bool
}
LokiConfig captures the fields needed to render loki.yml.
func DefaultLokiConfig ¶
func DefaultLokiConfig() *LokiConfig
DefaultLokiConfig returns the settings nSelf uses out of the box: 7-day retention, single-tenant, rule engine on. Matches the "5-minute first dashboard" onboarding promise while keeping disk usage bounded on small VPS.
type PrometheusConfig ¶
type PrometheusConfig struct {
// ScrapeInterval is the global default (e.g. "15s").
ScrapeInterval string
// EvaluationInterval is how often Prometheus evaluates alert rules.
EvaluationInterval string
// ExternalLabels apply to every time series (useful for multi-cluster).
ExternalLabels map[string]string
// AlertmanagerURL is the Alertmanager host:port; empty disables alerting.
AlertmanagerURL string
// RuleFiles are paths (inside the container) to load alert rules from.
RuleFiles []string
// Targets is the full list of scrape targets.
Targets []ScrapeTarget
}
PrometheusConfig captures everything needed to render prometheus.yml.
func Defaults ¶
func Defaults() *PrometheusConfig
Defaults returns a PrometheusConfig with nSelf's out-of-the-box settings. Callers append their own targets via `cfg.Targets = append(...)` before rendering.
type PromtailConfig ¶
type PromtailConfig struct {
// LokiURL is the Loki push endpoint. Inside the docker network this is
// typically "http://loki:3100/loki/api/v1/push".
LokiURL string
// TenantID is the X-Scope-OrgID sent with every push. Empty in
// single-tenant mode; required when Loki is multi-tenant.
TenantID string
// ProjectName is the nSelf project name; attached as a static label on
// every line so operators can distinguish multiple projects on one host.
ProjectName string
}
PromtailConfig captures the fields needed to render promtail.yml. Promtail reads Docker container logs and ships them to Loki with labels that let Grafana filter by plugin, tenant, and service.
func DefaultPromtailConfig ¶
func DefaultPromtailConfig(projectName string) *PromtailConfig
DefaultPromtailConfig returns the settings nSelf uses out of the box.
type ScrapeTarget ¶
type ScrapeTarget struct {
// JobName uniquely identifies the target in Prometheus. Use the plugin
// name (e.g. "ai", "mux") or the service name (e.g. "postgres", "nginx").
JobName string
// ServiceName is the docker-compose service name resolved via the Docker
// network DNS. Prometheus scrapes <ServiceName>:<Port><Path>.
ServiceName string
// Port is the plugin's HTTP port as declared in plugin.json.
Port int
// Path is the metrics endpoint. Defaults to /metrics if empty.
Path string
// Interval overrides the global scrape_interval when set. Empty = global.
Interval string
// Labels are additional static labels attached to every scraped series.
// Common use: {"plugin": "ai", "tier": "pro"}.
Labels map[string]string
}
ScrapeTarget describes one plugin or service that Prometheus should scrape. Every nSelf plugin exposes /metrics on its HTTP port; admins may add custom services with the same contract via ScrapeTargets in the monitoring config.
func BuiltinTargets ¶
func BuiltinTargets() []ScrapeTarget
BuiltinTargets returns the monitoring targets that ship with every nSelf stack: Prometheus itself, node-exporter, cadvisor, postgres-exporter, etc. Plugin targets are appended by the caller.
func TargetFromPlugin ¶
func TargetFromPlugin(name string, port int, tier string) ScrapeTarget
TargetFromPlugin builds a ScrapeTarget for a plugin declared with the given name, port, and tier ("free" or "pro"). It sets sensible labels so the Grafana dashboards can filter by plugin and tier.
Source Files