93 lines
2.7 KiB
Markdown
93 lines
2.7 KiB
Markdown
# Log Guardian
|
|
|
|
Private Loki-backed service for log monitoring, alerting, and guarded remediation.
|
|
|
|
Current implementation includes the Phase 1 foundations:
|
|
|
|
- watches configured LogQL rules;
|
|
- records incidents when thresholds are met;
|
|
- enforces per-rule cooldowns;
|
|
- protects the UI with basic auth while leaving `/healthz` open;
|
|
- provides Loki label/query diagnostics;
|
|
- supports UI-configurable alert channels with real ntfy delivery;
|
|
- keeps remediation in dry-run by default;
|
|
- includes local-only Ollama analysis support, disabled by default.
|
|
|
|
## Run locally
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
# edit env values, then export them or use your shell dotenv helper
|
|
go run ./cmd/server
|
|
```
|
|
|
|
Open <http://localhost:8080>.
|
|
|
|
## Configuration
|
|
|
|
| Variable | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `LOG_GUARDIAN_ADDR` | `:8080` | HTTP listen address. |
|
|
| `LOG_GUARDIAN_DATA_PATH` | `/data/config.json` | Local JSON config. |
|
|
| `LOG_GUARDIAN_POLL_INTERVAL` | `1m` | Rule evaluation interval. |
|
|
| `LOG_GUARDIAN_DRY_RUN_ACTIONS` | `true` | Prevents real remediation actions. |
|
|
| `LOG_GUARDIAN_AUTH_USERNAME` / `LOG_GUARDIAN_AUTH_PASSWORD` | empty | Required basic auth credentials for UI/API routes except `/healthz`. |
|
|
| `LOKI_URL` | `http://loki:3100` | Loki base URL. |
|
|
| `LOKI_TENANT_ID` | empty | Optional Loki tenant header. |
|
|
| `LOKI_USERNAME` / `LOKI_PASSWORD` | empty | Optional basic auth. |
|
|
| `LOG_GUARDIAN_ANALYSIS_PROVIDER` | `none` | `none` or local-only `ollama`. |
|
|
| `LOG_GUARDIAN_OLLAMA_URL` / `LOG_GUARDIAN_OLLAMA_MODEL` | `http://ollama:11434` / `llama3.1` | Local Ollama analysis config. |
|
|
|
|
## Initial Loki setup
|
|
|
|
A starter Loki + Promtail stack is in `deploy/loki/`:
|
|
|
|
```sh
|
|
cd deploy/loki
|
|
docker compose up -d
|
|
```
|
|
|
|
Promtail is configured to discover Docker containers and attach useful labels:
|
|
|
|
- `container`
|
|
- `service`
|
|
- `stack`
|
|
- `stream`
|
|
|
|
Example LogQL rules:
|
|
|
|
```logql
|
|
{service="api"} |= "error"
|
|
{stack="second-brain"} |~ "(?i)(panic|fatal|exception)"
|
|
{container=~".*postgres.*"} |= "database system is ready"
|
|
```
|
|
|
|
## Deploy in Portainer
|
|
|
|
Use `deploy/portainer-stack.yml` with values from `deploy/portainer.env.example`.
|
|
|
|
Keep this set while testing:
|
|
|
|
```text
|
|
LOG_GUARDIAN_DRY_RUN_ACTIONS=true
|
|
LOG_GUARDIAN_ANALYSIS_PROVIDER=none
|
|
```
|
|
|
|
## Build and validate
|
|
|
|
```sh
|
|
make ci-fast
|
|
```
|
|
|
|
## Safety model
|
|
|
|
Automatic remediation is intentionally constrained:
|
|
|
|
1. A rule must match.
|
|
2. The configured threshold must be exceeded.
|
|
3. The action must be explicitly enabled on that rule.
|
|
4. Global dry-run must be disabled.
|
|
5. Future AI recommendations are advisory unless a rule explicitly allows a matching action type.
|
|
|
|
Do not enable production remediation until a later phase explicitly approves concrete action types and guardrails.
|