Installation

Lightmetrics currently installs from source-built Rust binaries. There are no published packages, installer scripts, systemd units, Homebrew formulae, or Docker images in this repository. Treat this guide as the manual binary layout for local or lab deployments; operator-owned container usage is covered in docs/docker.md, and production operations details remain planned in docs/admin-guide.md.

Build Binaries

From the repository root:

cargo build --locked --release -p lm-collector -p lm-agent

Built binaries:

Staged Layout

Use a staging directory to verify the install layout without writing to system paths:

STAGE=/tmp/lightmetrics-install
install -d "$STAGE/usr/local/bin"
install -d "$STAGE/etc/lightmetrics/tls"
install -d "$STAGE/etc/lightmetrics/dashboards.d"
install -d "$STAGE/var/lib/lightmetrics/spool"
install -d "$STAGE/var/lib/lightmetrics/cache"
install -d "$STAGE/var/lib/lightmetrics/queue"
install -m 0755 target/release/lm-collector "$STAGE/usr/local/bin/lm-collector"
install -m 0755 target/release/lm-agent "$STAGE/usr/local/bin/lm-agent"
install -m 0640 config/server.toml "$STAGE/etc/lightmetrics/server.toml"
install -m 0640 config/agent.toml "$STAGE/etc/lightmetrics/agent.toml"

This staging command verifies file placement only. The copied sample configs still contain production-style /etc/lightmetrics and /var/lib/lightmetrics paths and must be edited before running from the staged tree.

For a real host install, use the same layout under /usr/local/bin, /etc/lightmetrics, and /var/lib/lightmetrics, normally owned by a dedicated service user or by root plus a restricted service group. The repository does not create that user for you.

Runtime Paths

Token Files

Token files are secrets. Do not put token values in committed config files or terminal transcripts.

Collector ingest token file shape:

[[tokens]]
agent_id = "local-agent"
token = "<agent bearer token>"

The agent’s auth_token_file must contain the same token value for that agent_id. The query token file is a plain text bearer token used by the private query/UI API.

Dashboard Definitions

The collector ships built-in dashboard definitions from typed TOML files. Custom definitions are optional and are loaded from [dashboards].definition_files and [dashboards].definition_dirs in server.toml. Configured files and .toml files in configured directories are read during lm-collector --check-config and collector startup; parse errors, duplicate custom IDs, and implicit built-in overrides fail the check before the private console serves those definitions from GET /api/v1/dashboards.

TLS Files

The collector ingest listener requires TLS files configured under [ingest.tls] in server.toml. The repository does not provision public certificates or private keys for installed hosts. The local demo generates short-lived development certificates only for /tmp/lightmetrics-demo.

If the agent connects to a collector certificate signed by a private CA, set tls_ca_cert_file in agent.toml to a readable CA bundle path such as /etc/lightmetrics/ca.pem.

Configuration Checks

Validate the collector config without starting listeners:

/usr/local/bin/lm-collector --check-config /etc/lightmetrics/server.toml

Parse the agent config and encode a heartbeat batch without opening the queue or uploading:

/usr/local/bin/lm-agent /etc/lightmetrics/agent.toml

Agent log limits must stay aligned with collector ingest limits. In particular, agent max_log_message_bytes must be no higher than collector ingest.max_log_message_bytes, and agent max_logs_per_batch must be no higher than collector ingest.max_logs_per_batch. The agent also uses max_alerts_per_batch = 1 by default for local queue-pressure drop reporting; keep it no higher than collector ingest.max_alerts_per_batch, or set it to 0 when the collector cannot accept alert records.

Linux host telemetry adds a metric-limit floor for collector configs. The built-in agent heartbeat emits up to 107 scalar series, CPU and network metric series use up to two labels, process-enumeration metric series use up to three labels, and generated log records use up to four attributes. Custom collector configs must keep ingest.max_series_per_batch >= 107 and ingest.max_labels_per_series >= 4, with ingest.max_label_key_bytes >= 14 and ingest.max_label_value_bytes >= 64 for built-in metric labels and log attributes. Collector config validation enforces that floor. The sample config/server.toml defaults of 2048 series, 32 labels, 128 key bytes, and 512 value bytes satisfy that requirement.

For single-collector object landing, keep ingest.acceptance = "local_spool" and add an [object_store] section. The collector acknowledges after durable local spool acceptance, keeps private query results backed by the spool before landing, and uploads accepted batches to the object store in the background every ingest.object_landing_interval_ms milliseconds. The sample default is 60000. In s3_manifest mode, the accepted manifest remains part of the acknowledgement path; the interval setting does not delay active-active acceptance.

Manual Runtime Commands

Start the collector in the foreground:

/usr/local/bin/lm-collector /etc/lightmetrics/server.toml

Run one agent collection/upload cycle:

/usr/local/bin/lm-agent --once /etc/lightmetrics/agent.toml

Run repeated agent collection/upload cycles in the foreground:

/usr/local/bin/lm-agent --daemon /etc/lightmetrics/agent.toml

Flush already queued agent batches without collecting new data:

/usr/local/bin/lm-agent --flush /etc/lightmetrics/agent.toml

The repository does not provide a production service supervisor or service unit files. --daemon is a foreground process; use an external supervisor for restart policy, log capture, and stop/start orchestration.

Upgrade Procedure

1. Stop the external supervisor or foreground processes.
2. Back up /etc/lightmetrics and the state directories under /var/lib/lightmetrics.
3. Build the new binaries with cargo build --locked --release -p lm-collector -p lm-agent.
4. Replace lm-collector and lm-agent in the installed binary directory.
5. Review config changes against config/server.toml, config/agent.toml, and docs/limitations.md.
6. Run lm-collector --check-config /etc/lightmetrics/server.toml.
7. Run lm-agent /etc/lightmetrics/agent.toml.
8. Restart the external supervisor or foreground processes.

There is no migration tool yet. Schema/config compatibility and release-specific upgrade notes are planned for docs/release-upgrade-notes.md.

Unsupported Package Formats

The repository currently does not ship:

• .deb or .rpm packages
• systemd unit files
• Homebrew or other package-manager formulae
• published Docker/container images
• Windows service definitions
• automated TLS or token provisioning

Operator-owned container usage is documented separately in docs/docker.md.