@primafuture/telemetry-stack 0.1.0

package/README.md

@@ -0,0 +1,235 @@
+# @primafuture/telemetry-stack
+
+Reusable telemetry stack.
+
+This package does not contain Grafana, Loki, Tempo, Mimir, MinIO, Redpanda, Alloy, or Prometheus binaries. It contains a Docker Compose recipe and a small CLI that starts those Docker images for you.
+
+## Requirements
+
+- Node.js 18+
+- Docker
+- Docker Compose plugin
+
+## Quick Start
+
+Run a development telemetry stack and store its data in `./data/telemetry`:
+
+```bash
+npx @primafuture/telemetry-stack up ./data/telemetry
+```
+
+Open Grafana:
+
+```bash
+npx @primafuture/telemetry-stack open ./data/telemetry grafana
+```
+
+Stop the stack:
+
+```bash
+npx @primafuture/telemetry-stack down ./data/telemetry
+```
+
+## Local Development
+
+From this package directory:
+
+```bash
+node bin/telemetry-stack.mjs doctor
+node bin/telemetry-stack.mjs config /tmp/telemetry-stack-test
+node bin/telemetry-stack.mjs up /tmp/telemetry-stack-test
+```
+
+## Commands
+
+```bash
+telemetry-stack init <data-dir> [options]
+telemetry-stack up <data-dir> [options]
+telemetry-stack down <data-dir> [options]
+telemetry-stack restart <data-dir> [options]
+telemetry-stack ps <data-dir> [options]
+telemetry-stack logs <data-dir> [service] [options]
+telemetry-stack open <data-dir> [target] [options]
+telemetry-stack config <data-dir> [options]
+telemetry-stack doctor
+```
+
+`<data-dir>` is where the stack stores runtime data and the instance config. Use a different directory for a different instance.
+
+Common options:
+
+```text
+--name <name>        Override Docker Compose project name.
+--mode <dev|prod>    Instance mode for newly created config. Default: dev.
+```
+
+Port options:
+
+```text
+--grafana-port <port>           Default: 3000
+--otlp-grpc-port <port>         Default: 4317
+--otlp-http-port <port>         Default: 4318
+--tempo-port <port>             Default: 3200
+--loki-port <port>              Default: 3100
+--prometheus-port <port>        Default: 9090
+--mimir-port <port>             Default: 9009
+--minio-console-port <port>     Default: 9001
+--redpanda-port <port>          Default: 9092
+--redpanda-console-port <port>  Default: 8080
+--alloy-port <port>             Default: 12345
+```
+
+Logs options:
+
+```text
+--follow, -f       Follow log output. Only for logs.
+--tail <lines>     Number of log lines to show. Only for logs.
+```
+
+## Modes
+
+The stack has two modes:
+
+- `dev`: default mode. Uses simple non-secure credentials, enables anonymous Grafana Admin, and binds public ports to `0.0.0.0`.
+- `prod`: single-node production-oriented mode. Generates random credentials, disables anonymous Grafana, enables the login form, and binds public ports to `127.0.0.1`.
+
+Create an instance config without starting containers:
+
+```bash
+telemetry-stack init ./data/telemetry --mode prod
+```
+
+The instance config is stored here:
+
+```text
+<data-dir>/telemetry-stack.env
+```
+
+Generated service configs are stored here:
+
+```text
+<data-dir>/generated-configs/
+```
+
+For `prod`, find the Grafana admin user and password in `telemetry-stack.env`. The generated configs can also contain credentials, so do not commit the data directory. The `prod` mode is still single-node and not high availability. Put a reverse proxy, SSH tunnel, or private network in front of it if it needs remote access.
+
+## Multiple Instances
+
+The simplest command uses default ports:
+
+```bash
+telemetry-stack up ./data/telemetry
+```
+
+If another stack already uses those ports, override them:
+
+```bash
+telemetry-stack up ./data/telemetry-project-b \
+  --grafana-port 3300 \
+  --otlp-grpc-port 14317 \
+  --otlp-http-port 14318 \
+  --tempo-port 13200 \
+  --loki-port 13100 \
+  --prometheus-port 19090 \
+  --mimir-port 19009 \
+  --minio-console-port 19001 \
+  --redpanda-port 19092 \
+  --redpanda-console-port 18080 \
+  --alloy-port 22345
+```
+
+Project name is derived automatically from the absolute data directory. If you need a specific Docker Compose project name:
+
+```bash
+telemetry-stack up ./data/telemetry --name my-telemetry
+```
+
+## Logs
+
+Follow all stack logs:
+
+```bash
+telemetry-stack logs ./data/telemetry --follow --tail 100
+```
+
+Follow one service:
+
+```bash
+telemetry-stack logs ./data/telemetry alloy --follow --tail 100
+```
+
+Useful service names:
+
+```text
+alloy
+tempo
+loki
+prometheus
+mimir
+grafana
+minio
+redpanda
+redpanda-console
+```
+
+## Smoke Test
+
+The stack no longer generates fake telemetry by default. To test the log path, send one OTLP HTTP log record to Alloy:
+
+```bash
+TS="$(date +%s%N)"
+
+curl -sS -X POST http://localhost:4318/v1/logs \
+  -H 'Content-Type: application/json' \
+  -d "{
+    \"resourceLogs\": [{
+      \"resource\": {
+        \"attributes\": [{
+          \"key\": \"service.name\",
+          \"value\": {\"stringValue\": \"telemetry-smoke-test\"}
+        }]
+      },
+      \"scopeLogs\": [{
+        \"scope\": {\"name\": \"manual-curl\"},
+        \"logRecords\": [{
+          \"timeUnixNano\": \"${TS}\",
+          \"severityText\": \"INFO\",
+          \"body\": {\"stringValue\": \"hello from telemetry-stack smoke test\"},
+          \"attributes\": [{
+            \"key\": \"log_type\",
+            \"value\": {\"stringValue\": \"smoke_test\"}
+          }]
+        }]
+      }]
+    }]
+  }"
+```
+
+Query it from Loki:
+
+```bash
+curl -G 'http://localhost:3100/loki/api/v1/query' \
+  --data-urlencode 'query={service_name="telemetry-smoke-test"}'
+```
+
+## Useful URLs
+
+Default ports:
+
+- Grafana: `http://localhost:3000`
+- Tempo: `http://localhost:3200`
+- Loki: `http://localhost:3100`
+- Prometheus: `http://localhost:9090`
+- Mimir: `http://localhost:9009`
+- MinIO Console: `http://localhost:9001`
+- Redpanda Console: `http://localhost:8080`
+- OTLP gRPC: `localhost:4317`
+- OTLP HTTP: `http://localhost:4318`
+
+## Notes
+
+- `dev` is for local development and demos.
+- `prod` is a safer single-node mode, not a full HA observability platform.
+- Grafana runs with anonymous Admin access only in `dev` mode by default.
+- Grafana runtime data is stored under `<data-dir>/grafana`.
+- Docker images are pinned by digest in `stack/docker-compose.yaml`.