Skip to content

Latest commit

 

History

History
466 lines (357 loc) · 18.2 KB

configuration.md

File metadata and controls

466 lines (357 loc) · 18.2 KB

Configuration

StatLite supports Spring Boot Actuator, Quarkus Micrometer metrics, and Micronaut Micrometer metrics targets. Applications can also expose the fixed StatLite Metrics v1 JSON profile, with ready-to-use integration guides for FastAPI, Express, Django, Go net/http, and Gin. Depending on the integration and available signals, StatLite monitors application status, traffic, latency, CPU, and runtime memory without a full observability stack. StatLite is not a Prometheus/Grafana replacement.

Basic configuration

Create statlite.yaml in the directory where you run StatLite:

server.listen, storage.sqlite_path, and polling.interval are required.

server:
  listen: "127.0.0.1:9090"

storage:
  sqlite_path: "./statlite.sqlite"

polling:
  interval: "30s"

targets:
  - name: "my-app"
    type: "spring"
    url: "https://example.com/actuator"

Run statlite, then open http://127.0.0.1:9090. This configuration monitors one Spring Boot application, stores its history in a local SQLite database, and polls it every 30 seconds.

If you already have a configuration, copy only the target entry into its targets list. Run statlite from the directory containing statlite.yaml, or select the file with --config as shown below.

The sections below explain target discovery, alternate configuration paths, authentication, retention, polling, and other options.

StatLite loads statlite.yaml by default. Override with --config:

./statlite --config examples/actuator.yaml
# or, with an installed binary:
statlite --config /etc/statlite/config.yaml

See docs/integrations.md for the supported integration matrix and first-class targets. For applications using StatLite Metrics v1, see Integrate an application with StatLite for framework guides and examples. These integrations expose a /statlite/metrics endpoint; configuration only tells StatLite where to poll it. See examples/ for starter templates (Actuator, Micronaut, StatLite Metrics, multi-target, self-monitoring) and the Quarkus demo config and examples/spring-actuator-demo/ for a standalone Spring Boot demo app.

Discover a target with inspect

Start with an application's base HTTP or HTTPS URL without a query string or fragment:

statlite inspect 'http://localhost:8080'

Untyped inspection recognizes Spring, StatLite Metrics v1, and Quarkus at their conventional paths. It also accepts a direct StatLite Metrics v1 URL. To inspect a Quarkus application base URL or an exact Quarkus metrics URL, select the type:

statlite inspect --type quarkus 'http://localhost:9000'
statlite inspect --type quarkus 'http://localhost:9000/q/metrics'

See the Quarkus target reference for bounded compatibility and exact/custom endpoint resolution.

Micronaut requires explicit typed inspection:

statlite inspect --type micronaut 'http://localhost:8080'
statlite inspect --type micronaut 'http://localhost:8080/prometheus'
statlite inspect --type micronaut 'http://localhost:8080/service'

See the Micronaut target reference for endpoint resolution, compatibility, and inspection limits. Inspection checks metrics and does not request health; configure authenticated targets manually with the shared Basic Auth block. Compatibility with the supported metrics contract does not prove Micronaut framework identity.

On success, plain inspect prints the recognized capabilities, a minimal configuration, and commands to create or add it. The suggested target gets a stable <type>-<host>-<port> name. Override it with --name if needed; target names identify stored history, so keep the name stable.

To write a new config or add the detected target to an existing one:

statlite inspect 'http://localhost:8080' --create-config ./statlite.yaml
statlite inspect 'http://localhost:8080' --add-to-config ./statlite.yaml
statlite inspect 'http://localhost:9000' --type quarkus --name orders --add-to-config /etc/statlite/statlite.yaml

The options also work before the URL. Both write modes require an explicit destination path and one confidently detected target. --create-config PATH refuses an existing path and does not create parent directories. The relative storage.sqlite_path in a newly created config resolves from the config file's directory. --add-to-config PATH requires an existing file with targets: as its last top-level section and a normal list. Duplicate target names or endpoint URLs are rejected. A YAML ... document terminator also prevents automatic append. If an existing target's name or endpoint uses an environment variable, add the new target manually because inspect cannot safely check for conflicts. For other layouts, copy the suggested entry manually. Restart StatLite after adding a target so it reads the updated config.

--add-to-config updates the file in place and does not provide atomic replacement semantics. For production configuration changes, edit a copy and deploy it using your normal replacement procedure.

Important

Quote URLs containing ? or &. Untyped inspection does not accept a query string. Plain inspection is bounded and read-only: it does not load configuration, create state, start monitoring, or accept authentication options. Invalid, unreachable, unrecognized, or ambiguous targets fail without printing configuration or changing a config file.

Server

server:
  listen: "127.0.0.1:9090"

Keep listen on loopback for local access. For remote access, use a VPN, SSH tunnel, or authenticating reverse proxy. Inside a container, listening on a non-loopback address is normal; restrict the published host port. See Security and Remote Access for the access model and examples.

Storage

storage:
  sqlite_path: "./statlite.sqlite"
  # Default is 90 days when omitted; set to 0 for unlimited retention.
  retention_days: 90

sqlite_path must be writable by the StatLite process.

Relative sqlite_path values resolve from the directory in the config path supplied to StatLite, independent of the directory where StatLite is started. If that config path is a symbolic link, its directory is used rather than the directory containing the link target. Absolute paths, including environment-expanded absolute paths, are used as written. This differs from releases before v0.4.3, which resolved relative paths from the process working directory. During the compatibility window, StatLite warns and continues with the new path when it finds history only at the previous working-directory-relative location; it does not automatically open or move the old database file.

Runtime SQLite files (*.sqlite, *.sqlite-shm, *.sqlite-wal) should not be committed.

Retention

StatLite keeps SQLite history for 90 days by default. On startup, and then every 24 hours while running, it deletes poll snapshots older than the configured retention window; related metric samples and collector events are removed automatically.

Set retention_days: 0 to disable cleanup and keep history indefinitely. Existing SQLite files are pruned on the first startup after retention is enabled unless retention is set to 0.

Polling

polling:
  interval: "30s"
  timeout: "10s"
  • interval: how often each target is polled (positive Go duration, required).
  • timeout: per-poll HTTP timeout (positive Go duration; default 10s if omitted).

Use 30s or longer for production deployments. Shorter intervals increase HTTP requests, SQLite writes, and database growth, and are best reserved for explicitly labeled local demos.

Each target is polled immediately on startup. If that first poll succeeds and needs a new counter baseline because the target has no stored history or starts a new application run, StatLite makes one follow-up poll after three seconds, or after the configured interval when it is shorter. Gauge-only targets and targets with a compatible stored baseline use the configured interval normally.

Targets

At least one target is required. Names must be unique.

Target URLs must use http:// or https://, include a host, and omit fragments; Caddy, Quarkus, Micronaut, and StatLite Metrics URLs may include queries, and canonical target URLs do not support embedded credentials.

Caddy HTTP metrics

targets:
  - name: app-via-caddy
    type: caddy
    url: http://127.0.0.1:2019/metrics
    host: app.example.com

url is the exact metrics endpoint and host is required, matching the Caddy host label exactly. See the Caddy onboarding guide for per_host, HTTPS setup, private Docker endpoints, diagnostics, and limitations. Optional Basic Auth is supported; health and host-resource options are not. Caddy targets require manual configuration.

Spring Boot Actuator

targets:
  - name: "my-app"
    type: "spring"
    url: "https://example.com/actuator"
    metrics_source: "auto"
    auth:
      type: "basic"
      username: "admin"
      password: "change-me"

url is the Spring management base URL. StatLite derives the health and metrics endpoints from it. type may be omitted for compatibility with older Spring configurations, but new configuration should use explicit type: "spring".

metrics_source accepts auto, prometheus, or actuator and defaults to auto when omitted. auto prefers a compatible Spring Prometheus endpoint and falls back to Actuator metrics only when the endpoint is absent or returns a valid but incompatible exposition. Authentication, transient, malformed, and resource-limit failures are retried without changing sources. Once selected, the source remains fixed until the target collector is recreated. Health is collected independently from the Actuator health endpoint. If health retrieval fails but at least one independently usable metric sample is collected, the poll remains successful, health stays unavailable, and StatLite records a focused warning. If no usable metric sample is collected, the poll fails even when health responded.

actuator_base_url is deprecated; use url. See Deprecations and compatibility for its temporary compatibility behavior.

Missing optional metrics are handled gracefully: values may appear as null or charts may show gaps instead of failing the whole poll.

Host metrics are disabled for Spring targets by default. In the common single-host setup, monitor host CPU, memory, and disk through the statlite-self target instead. For a remote Spring Boot application where running StatLite on that host is undesirable, enable Actuator host collection for that target:

targets:
  - name: "remote-app"
    type: "spring"
    url: "https://remote.example.com/actuator"
    collect_host_metrics: true

This adds polls for system.cpu.usage, disk.free, and disk.total. The resulting CPU and disk values describe the execution environment visible to the Spring Boot process, which may be a container rather than the physical host.

See the Spring target reference for source selection, health, remote host metrics, and the Spring demo.

Quarkus Micrometer metrics

targets:
  - name: "orders"
    type: "quarkus"
    url: "http://localhost:9000/q/metrics"

url is the exact metrics endpoint, normally /q/metrics. Optional SmallRye Health is collected independently; unavailable health does not discard valid metrics or synthesize stored application health. Successful metrics collection without explicit health can display UP with a collection-based dashboard hint.

See the Quarkus target reference for health derivation and overrides, compatibility, normalized metrics, and the tested setup.

Micronaut Micrometer metrics

targets:
  - name: "orders"
    type: "micronaut"
    url: "http://localhost:8080/prometheus"

Use explicit type: "micronaut"; omitted type still defaults to Spring. url is the exact metrics endpoint, normally /prometheus. The application requires management and Micrometer configuration.

See the Micronaut target reference for application setup, tested versions, metric mapping, and optional management/JDBC health.

Basic Auth

auth:
  type: "basic"
  username: "${STATLITE_ACTUATOR_USERNAME}"
  password: "${STATLITE_ACTUATOR_PASSWORD}"

Only basic is supported. The same auth block applies to Quarkus and Micronaut metrics and health endpoints as well as Spring endpoints. Prefer environment variables for credentials, so they are not stored in plaintext YAML. Export them before starting StatLite (or set them with your service manager):

export STATLITE_ACTUATOR_USERNAME="admin"
export STATLITE_ACTUATOR_PASSWORD="replace-with-a-secret"
statlite --config /etc/statlite/config.yaml

StatLite expands environment variables across the entire YAML file once at startup, before it parses the config. Both $VAR and ${VAR} work; unset variables expand to an empty string. Shell-style defaults such as ${VAR:-default} are not supported. Use $${ for a literal ${ in the config. Restart StatLite after changing an environment variable.

Plaintext credentials still work as a fallback. Restrict config file permissions when they are present:

chmod 600 /etc/statlite/config.yaml
chown statlite:statlite /etc/statlite/config.yaml

StatLite strips credentials from source endpoints before showing them in the dashboard or API responses.

StatLite Metrics v1

targets:
  - name: "python-demo"
    type: "statlite-metrics"
    url: "http://127.0.0.1:8000/statlite/metrics"

Applications using type: statlite-metrics expose the fixed statlite-metrics/v1 JSON profile. See StatLite Metrics v1 for the complete response format, field semantics, and implementation guidance. StatLite performs one bounded JSON GET per poll; Basic Auth is not part of v1.

StatLite self-monitoring

Self-monitoring lets StatLite monitor its own application, process, and local resources by polling its /statlite/metrics endpoint. The statlite-self target reports CPU, memory, and filesystem resources visible to the StatLite process, including the filesystem containing its SQLite database. Local host metrics are unavailable on Windows; see limitations.

StatLite host monitoring dashboard

Save this configuration to statlite.yaml:

server:
  listen: "127.0.0.1:9090"

storage:
  sqlite_path: "./statlite-self.sqlite"

polling:
  interval: "30s"

targets:
  - name: "statlite-self"
    type: "statlite-metrics"
    url: "http://127.0.0.1:9090/statlite/metrics"

Then run:

statlite

Open http://127.0.0.1:9090 to see the statlite-self target.

To use a different port, change both server.listen and the target url. To add self-monitoring to an existing configuration, copy only the target entry into its targets list and match the URL to that instance's listening address.

type: "statlite-metrics" polls the fixed statlite-metrics/v1 JSON profile. To monitor another StatLite instance, set the target URL to that instance's /statlite/metrics endpoint.

For a remote application, a central StatLite instance cannot obtain that machine's host resources unless the application emits the optional host fields in statlite-metrics/v1 or another StatLite instance runs on the remote host.

Dashboard URL state

Selected target and time range are stored in the query string, so you can bookmark a view:

/?target=catalog-api&range=1h

API notes

  • The read-only /api/v1/status, /api/v1/events, and /api/v1/metrics endpoints are the supported external automation API. See the External API reference for fields, bounds, examples, and access assumptions. Other dashboard /api/* routes are internal and are not a compatibility contract.
  • /healthz exposes process version and storage readiness. Monitored-target poll failures do not mark the process unhealthy; SQLite failure does (status: "error", HTTP 503). Use /api/v1/status for target collection and reported application/dependency health.

Example files

File Purpose
statlite.yaml (repo root) Default Quick Start that monitors StatLite itself
examples/actuator.yaml Single Spring Boot Actuator target with Basic Auth placeholders
examples/micronaut.yaml Exact Micronaut Prometheus endpoint with optional management health
examples/statlite.yaml Monitor another StatLite instance with statlite-metrics
examples/multi-target.yaml Illustrative multi-target mix (Actuator + StatLite Metrics + self)
examples/quarkus-metrics-demo/ Pinned Quarkus Micrometer metrics fixture and traffic recipe
examples/spring-actuator-demo/ Standalone Spring Boot demo app that emits Actuator and Micrometer metrics

Systemd

A starter unit is in statlite.service.example. Point ExecStart at your binary and config path. Installers do not install this unit automatically.

View existing history without polling

--no-poll is a troubleshooting convenience for inspecting existing SQLite history in the dashboard, not a separate supported operating mode; behavior of other interfaces in this mode is not part of the supported contract.

Use --no-poll with a normal YAML configuration to serve the dashboard from existing SQLite history without contacting any configured target:

statlite --config /etc/statlite/config.yaml --no-poll

This mode disables startup, periodic, and manual debug polling. It also skips retention cleanup, shows stored history outside the configured retention window, and freezes dashboard time ranges at the newest stored poll. When the database has no polls, the dashboard uses the current time instead.

For troubleshooting chart optimizations, the CLI-only --raw-series flag bypasses dashboard sampling and aggregation, returning the full-resolution series within the effective requested range. Normal retention clamping applies while polling is enabled. It can be combined with --no-poll; counter/restart semantics still apply, but long ranges require more server and browser work.