unkin-agent
ee2f270abc
The RPM's /usr/bin/chcat conflicts with SELinux's policycoreutils-python-utils on Fedora. Per Ben: remove the symlink entrypoints entirely and ship only the chlog binary with cat/tail/grep subcommands. - Remove chcat/chtail/chgrep symlinks and their completions from nfpm.yaml, build-rpm.sh and the Makefile - Remove the argv[0] dispatch in main.go; subcommands are unchanged - Update the completion test to cover chlog only - Update README usage to chlog cat|tail|grep
70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# clickhouse-tools
|
|
|
|
CLI tools for the ClickHouse log store (`logs.raw`): one binary, `chlog`, with
|
|
three subcommands:
|
|
|
|
| Command | Does |
|
|
|--------------|------|
|
|
| `chlog cat` | Print logs oldest-first over a bounded time range |
|
|
| `chlog tail` | Follow logs live (2s poll, overlap + dedupe so nothing is lost or repeated) |
|
|
| `chlog grep` | Search log messages (substring, `-i`, `--regex`) |
|
|
|
|
(Earlier releases also shipped `chcat`/`chtail`/`chgrep` symlinks; they were
|
|
dropped because `/usr/bin/chcat` conflicts with SELinux's
|
|
`policycoreutils-python-utils` package.)
|
|
|
|
## Why time bounds everywhere
|
|
|
|
`logs.raw` has no text index and holds ~281M rows/day (3-day TTL). An unbounded
|
|
message scan takes ~1 minute and the server kills queries at 120s. Every query
|
|
these tools issue is therefore time-bounded — the default range is the last
|
|
hour (`--since 1h`) — and `chlog grep` refuses a search wider than 6h with no
|
|
`--namespace`/`--host`/`--app` filter unless you pass `--force`.
|
|
|
|
All user input travels as ClickHouse HTTP `{name:Type}` parameters; nothing is
|
|
ever interpolated into SQL text.
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
chlog cat -n logging --since 30m
|
|
chlog cat --host web01 --since 2h --until 1h --format logfmt
|
|
chlog tail -n media --app jellyfin
|
|
chlog grep -n kube-system -i "connection refused" --since 4h
|
|
chlog grep --app vector --regex 'timed? ?out' --since 1d
|
|
chlog grep --fields req_id=42 -n api "payment"
|
|
```
|
|
|
|
### Common flags
|
|
|
|
- `--since` / `--until` — duration ago (`15m`, `1h`, `2d`, `1w`) or RFC3339;
|
|
default `--since 1h`, `--until` now
|
|
- `-n/--namespace`, `--host`, `--pod`, `--container`, `--app` (labels['app']),
|
|
`--severity` (case-insensitive), `--stream`, `--source`
|
|
- `--limit` — max rows (default 10000 for cat/grep; tail is unlimited)
|
|
- `--format text|json|logfmt` — text is `ts ns/pod msg` (host for vm rows),
|
|
colored only on a TTY (`NO_COLOR` respected)
|
|
|
|
### chlog grep extras
|
|
|
|
- pattern is a substring by default; `-i` case-insensitive; `--regex` RE2 (`match()`)
|
|
- `--fields key=value` (repeatable) filters the structured `fields` map
|
|
- `--force` overrides the wide-unfiltered-search guard
|
|
|
|
## Connection
|
|
|
|
| Env | Default |
|
|
|-----|---------|
|
|
| `CH_URL` | `http://clickhouse-logs.logging.svc.cluster.local:8123` |
|
|
| `CH_USER` | `logreader` |
|
|
| `CH_PASSWORD` | (empty) |
|
|
|
|
## Build and release
|
|
|
|
```sh
|
|
make build # dist/chlog
|
|
make test # go test -race ./...
|
|
make rpm # nfpm RPM with binary + bash/zsh/fish completions
|
|
make patch # tag + push next vX.Y.Z → CI releases RPM to artifactapi rpm-internal
|
|
```
|