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.
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.yamlSee 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.
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.yamlThe 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:
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:
sqlite_path: "./statlite.sqlite"
# Default is 90 days when omitted; set to 0 for unlimited retention.
retention_days: 90sqlite_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.
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:
interval: "30s"
timeout: "10s"interval: how often each target is polled (positive Go duration, required).timeout: per-poll HTTP timeout (positive Go duration; default10sif 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.
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.
targets:
- name: app-via-caddy
type: caddy
url: http://127.0.0.1:2019/metrics
host: app.example.comurl 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.
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: trueThis 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.
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.
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.
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.yamlStatLite 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.yamlStatLite strips credentials from source endpoints before showing them in the dashboard or API responses.
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.
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.
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:
statliteOpen 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.
Selected target and time range are stored in the query string, so you can bookmark a view:
/?target=catalog-api&range=1h
- The read-only
/api/v1/status,/api/v1/events, and/api/v1/metricsendpoints 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. /healthzexposes 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/statusfor target collection and reported application/dependency health.
| 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 |
A starter unit is in statlite.service.example. Point ExecStart at your binary and config path. Installers do not install this unit automatically.
--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-pollThis 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.
