Quickstart

This is the shortest verified local path from a checkout to queryable Lightmetrics data. It uses the development demo harness, not a production deployment.

Prerequisites

Install these tools and make sure they are on PATH:

Rust toolchain with cargo
openssl
curl
MinIO server binary as minio
either AWS CLI as aws or the MinIO client as mc

The demo script exits with code 2 and names the missing tool if a prerequisite is absent.

Start The Demo

From the repository root:

scripts/lightmetrics-demo restart

The command builds lm-collector and lm-agent, creates local demo tokens and TLS material, starts MinIO, starts the collector query/frontend server, and starts an agent loop that sends heartbeat batches through ingest.

Default local endpoints:

Endpoint	Default
Console	`http://127.0.0.1:18080/console`
Query API	`http://127.0.0.1:18080/api/v1/query`
Ingest API	`https://localhost:18443/ingest/v1/batch`
MinIO API	`http://127.0.0.1:19000`
MinIO console	`http://127.0.0.1:19001`

Default generated state:

Path	Use
`/tmp/lightmetrics-demo/query-token`	Bearer token for private query/API calls.
`/tmp/lightmetrics-demo/agent-token`	Bearer token used by the demo agent for ingest.
`/tmp/lightmetrics-demo/server.toml`	Generated collector config.
`/tmp/lightmetrics-demo/agent.toml`	Generated agent config.
`/tmp/lightmetrics-demo/logs/`	MinIO, collector, and agent logs.

Check Status

scripts/lightmetrics-demo status

Expected service lines after a successful start:

minio: running pid=<pid>
collector: running pid=<pid>
agent: running pid=<pid>

The status output also prints the console URL and the query token file path.

Query A Metric

QUERY_TOKEN="$(cat /tmp/lightmetrics-demo/query-token)"
curl -fsS \
  -H "Authorization: Bearer $QUERY_TOKEN" \
  "http://127.0.0.1:18080/api/v1/query?query=lmagent_up"

Expected response shape:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "lmagent_up",
          "agent_id": "demo-agent"
        },
        "value": [0, "1"]
      }
    ]
  }
}

The timestamp and labels may contain additional fields such as boot_id and host.

Inspect Logs

scripts/lightmetrics-demo logs

This prints the tail of the generated MinIO, collector, and agent logs under /tmp/lightmetrics-demo/logs/.

Stop The Demo

scripts/lightmetrics-demo stop
scripts/lightmetrics-demo status

Expected service lines after stopping:

minio: stopped
collector: stopped
agent: stopped

The generated demo directory remains under /tmp/lightmetrics-demo so later starts can reuse generated tokens and TLS material. Delete that directory only when the demo state, generated certificates, and tokens are no longer needed.

Isolated Runs

Use environment overrides when default ports or paths are already in use:

LIGHTMETRICS_DEMO_DIR=/tmp/lightmetrics-demo-alt \
LIGHTMETRICS_DEMO_QUERY_ADDR=127.0.0.1:18180 \
LIGHTMETRICS_DEMO_INGEST_ADDR=127.0.0.1:18543 \
LIGHTMETRICS_DEMO_MINIO_ADDR=127.0.0.1:19100 \
LIGHTMETRICS_DEMO_MINIO_CONSOLE_ADDR=127.0.0.1:19101 \
LIGHTMETRICS_DEMO_MINIO_BUCKET=lightmetrics-alt \
scripts/lightmetrics-demo restart

Use the same overrides for status, logs, and stop.

Common Failures

Symptom	Check
`missing required tool`	Install the named prerequisite and rerun `scripts/lightmetrics-demo restart`.
Port bind failure	Use the environment overrides above or stop the process already using the port.
MinIO bucket setup failure	Confirm `aws` or MinIO `mc` is installed and points to the expected binary.
Query returns an empty vector immediately after start	Wait one agent interval, then retry. The default agent interval is 5 seconds.
Collector or agent does not stay running	Run `scripts/lightmetrics-demo logs` and inspect `/tmp/lightmetrics-demo/logs/collector.log` and `agent.log`.

Current Limits

The demo is a development harness. It is not a hardened deployment topology and does not replace installation, Docker, admin, or production operations guides. Current system limits are tracked in docs/limitations.md.

Publication Boundary

Development harness