LeeSeokBln/faultbrief

# faultbrief **English** · [한국어](#한국어) 将 Linux 日志转化为故障简报。只需一条命令，无需 daemon，无需配置。 ``` faultbrief --since 1h ``` faultbrief 读取 journald、syslog 和 nginx 日志，并通过规则引擎检测故障 信号： - **特征（Signatures）** — 21 种精选的已知异常模式（OOM kill、磁盘已满、 systemd unit 故障、nginx upstream 错误等） - **突增（Spikes）** — 与前一个基线窗口相比的频率异常 （5 分钟时间桶，带有最小计数保护的 z-score） - **新模式** — 基线中从未见过的日志模板 （可变掩码指纹） LLM 是**可选的**：`--llm` 会在规则引擎报告的基础上添加 AI 故障简报 （Anthropic API 或任何兼容 OpenAI 的 endpoint， 包括本地 Ollama）。即使没有它，faultbrief 仍然是一个完整的工具。 ## 安装 ### 从源码安装 ``` go install github.com/LeeSeokBln/faultbrief/cmd/faultbrief@latest ``` 或者为了方便起见设置别名： ``` alias brief=faultbrief ``` ### 从发布 tarball 安装 从 [GitHub Releases](https://github.com/LeeSeokBln/faultbrief/releases) 下载最新的发布版本， 解压并添加到你的 PATH 中： ``` tar xzf faultbrief_*_linux_amd64.tar.gz sudo mv faultbrief /usr/local/bin/ ``` 支持的平台：Linux (amd64, arm64), macOS (amd64, arm64)。 ## 使用方法 ``` faultbrief [flags] Flags: --since DURATION analysis window size (e.g. 30m, 1h, 1d; default "1h") --until DURATION skip the most recent span (e.g. 10m; default "0") --baseline DURATION baseline span before the window (default "24h") --format FORMAT output format: text, md, json (default "text") --lang LANG report language: en, ko (default "en") --min-severity SEV minimum finding severity to report: debug, info, notice, warning, error, critical (default "info") --llm add an LLM incident briefing --source NAMES limit sources: journald, syslog, nginx, nginx-access, nginx-error (default: all detected) --syslog-path PATHS syslog file paths/globs (default: /var/log/syslog*, /var/log/messages*) --nginx-access-path PATHS nginx access log paths/globs (default: /var/log/nginx/access.log*) --nginx-error-path PATHS nginx error log paths/globs (default: /var/log/nginx/error.log*) --rules FILES extra signature rule YAML files --use-cache remember templates across runs, so "new pattern" means new-ever, not just new-vs-yesterday --no-color disable colored output --config PATH config file (default ~/.config/faultbrief/config.yaml) Commands: version print version Exit codes (cron/CI friendly): 0 no findings — logs look healthy 1 findings detected 2 runtime error (bad flags, no readable sources, ...) ``` 读取 `/var/log` 通常需要属于 `adm` 组或使用 sudo。 ## 输出示例 来自测试夹具的简略实际输出（显示了 8 项发现中的 3 项）： ``` FAULTBRIEF — incident brief Window: 2026-07-07 09:00 → 2026-07-07 10:00 (baseline: previous 24h0m0s) Sources: journald ✓ (1) · syslog ✓ (69) · nginx-access ✓ (260) · nginx-error ✓ (3) Records: 104 · Findings: 8 [CRITICAL] signature oom-kill — OOM killer terminated a process (×2) first: 09:12:00 · last: 09:14:00 · unit: kernel · syslog matched 2 time(s) > Out of memory: Killed process 1234 (myapp) total-vm:204800kB hint: free -h; dmesg | grep -i oom; check the unit's memory limits [ERROR] spike nginx-5xx-rate — nginx 5xx error rate is high (×12) first: 09:00:00 · last: 10:00:00 · unit: nginx · nginx-access 12 of 60 requests failed (20.0%), baseline 0.0% [ERROR] spike 2fa0ade5fedf824e — error: pg query timeout after ms (×30) first: 09:00:00 · last: 09:58:00 · unit: myapp · syslog 30 occurrences (2.5/bucket) vs baseline 0.02/bucket — z=5.0, ×50.0 > error: pg query timeout after 5000 ms ``` 每项发现都会说明*为什么*被提出：匹配的规则，或是突增背后的准确 计数和 z-score。 ## LLM 简报（可选） 使用 `--llm` 启用 AI 故障摘要。规则引擎报告始终 完整输出 —— 如果 LLM 调用失败，你除了摘要之外什么都不会失去。 ### Anthropic API ``` export ANTHROPIC_API_KEY=sk-ant-... faultbrief --since 1h --llm ``` ### OpenAI API ``` export OPENAI_API_KEY=sk-... export FAULTBRIEF_LLM_PROVIDER=openai export FAULTBRIEF_LLM_MODEL=gpt-4o-mini faultbrief --since 1h --llm ``` ### 本地 Ollama（无需云服务） ``` export FAULTBRIEF_LLM_PROVIDER=openai export FAULTBRIEF_LLM_BASE_URL=http://localhost:11434 export FAULTBRIEF_LLM_MODEL=llama3 faultbrief --since 1h --llm ``` 设置也可以存放在 `~/.config/faultbrief/config.yaml` 中： ``` lang: ko llm: provider: openai base_url: http://localhost:11434 model: llama3 ``` 优先级：flags > 环境变量 > 配置文件 > 默认值。 ## 自定义规则 在 YAML 文件中添加你自己的特征： ``` - id: my-app-crash title: "My app crashed" severity: critical source: syslog # optional: journald, syslog, nginx-access, nginx-error, any contains: "my-app: segmentation fault" hint: "coredumpctl list; check the last deploy" example: "my-app: segmentation fault at 0x0" - id: slow-query title: "Database query over limit" severity: error regex: "query took \\d+ms, exceeded" hint: "EXPLAIN ANALYZE the query; check missing indexes" example: "db: query took 5000ms, exceeded limit" ``` 使用 `--rules ./my-rules.yaml` 加载。每条规则只能包含 `contains`/`regex` 中的 确切一项。内置规则始终会被加载。 ## 注意事项与限制 - nginx **error** 日志时间戳不带时区；faultbrief 会按照计算机的本地时间解析它们。 请在产生错误日志的主机上（或使用匹配的 TZ）分析错误日志 —— 跨时区复制的日志将会错过时间窗口。 - nginx **access** 日志仅在默认的 `combined` 格式下进行解析。 计划在未来支持自定义 `log_format`。 - 对于远程 LLM endpoint 请使用 `https`；`http` 基础 URL 适用于像 Ollama 这样的 环回服务（API key 和日志摘录将被发送到该 URL）。 ## 韩语 리눅스 로그를 장애 브리핑으로. 명령어 하나, 데몬 없음, 사전 설정 없음. ``` faultbrief --since 1h ``` faultbrief는 journald·syslog·nginx 로그를 읽어 **규칙 엔진**으로 장애 신호를 탐지합니다: - **시그니처** — 엄선된 21종의 알려진 장애 패턴 (OOM kill, 디스크 풀, systemd 유닛 실패, nginx 업스트림 에러 등) - **스파이크** — 직전 베이스라인 구간 대비 빈도 이상 (5분 버킷, z-score + 최소 건수 가드로 오탐 방지) - **신규 패턴** — 베이스라인에 없던 로그 템플릿 (숫자/IP/UUID/경로를 마스킹한 핑거프린트 비교) LLM은 **옵션**입니다. `--llm`을 붙이면 규칙 엔진 리포트 위에 AI 장애 브리핑이 추가됩니다 (Anthropic API 또는 OpenAI 호환 엔드포인트 — 로컬 Ollama 포함). LLM 없이도 faultbrief는 그 자체로 완결된 도구입니다. ### 安装 #### 从源码 ``` go install github.com/LeeSeokBln/faultbrief/cmd/faultbrief@latest ``` 짧게 쓰고 싶다면: ``` alias brief=faultbrief ``` #### Release Tarball [GitHub Releases](https://github.com/LeeSeokBln/faultbrief/releases)에서 받아서 PATH에 추가: ``` tar xzf faultbrief_*_linux_amd64.tar.gz sudo mv faultbrief /usr/local/bin/ ``` 지원 플랫폼: Linux (amd64, arm64), macOS (amd64, arm64). ### 使用方法 ``` faultbrief [플래그] 플래그: --since 기간 분석 구간 크기 (예: 30m, 1h, 1d; 기본 "1h") --until 기간 가장 최근 구간 제외 (예: 10m; 기본 "0") --baseline 기간 분석 구간 직전의 베이스라인 길이 (기본 "24h") --format 포맷 출력 포맷: text, md, json (기본 "text") --lang 언어 리포트 언어: en, ko (기본 "en") --min-severity 심각도 이 심각도 이상만 리포트: debug, info, notice, warning, error, critical (기본 "info") --llm LLM 장애 브리핑 추가 --source 이름들 소스 제한: journald, syslog, nginx, nginx-access, nginx-error (기본: 자동 감지 전부) --syslog-path 경로들 syslog 파일 경로/글롭 (기본 /var/log/syslog*, /var/log/messages*) --nginx-access-path 경로들 nginx access 로그 경로/글롭 (기본 /var/log/nginx/access.log*) --nginx-error-path 경로들 nginx error 로그 경로/글롭 (기본 /var/log/nginx/error.log*) --rules 파일들 사용자 시그니처 규칙 YAML 추가 --use-cache 실행 간 템플릿 기억 — "신규 패턴"이 "어제 대비 신규"가 아니라 "역대 최초"를 뜻하게 됨 --no-color 컬러 출력 끄기 --config 경로 설정 파일 (기본 ~/.config/faultbrief/config.yaml) 명령: version 버전 출력 종료 코드 (cron/CI 연동용): 0 발견 없음 — 로그 정상 1 발견 있음 2 실행 에러 (잘못된 플래그, 읽을 수 있는 소스 없음 등) ``` `/var/log`를 읽으려면 보통 `adm` 그룹 소속이거나 sudo가 필요합니다. ### 输出示例 테스트 픽스처 기준 실제 출력 (8건 중 3건 발췌): ``` FAULTBRIEF — 장애 브리핑 분석 구간: 2026-07-07 09:00 → 2026-07-07 10:00 (베이스라인: 직전 24h0m0s) 소스: journald ✓ (1) · syslog ✓ (69) · nginx-access ✓ (260) · nginx-error ✓ (3) 레코드: 104 · 발견: 8 [심각] 시그니처 oom-kill — OOM killer terminated a process (×2) 최초: 09:12:00 · 최종: 09:14:00 · 유닛: kernel · syslog matched 2 time(s) > Out of memory: Killed process 1234 (myapp) total-vm:204800kB 힌트: free -h; dmesg | grep -i oom; check the unit's memory limits [에러] 스파이크 nginx-5xx-rate — nginx 5xx error rate is high (×12) 최초: 09:00:00 · 최종: 10:00:00 · 유닛: nginx · nginx-access 12 of 60 requests failed (20.0%), baseline 0.0% [에러] 스파이크 2fa0ade5fedf824e — error: pg query timeout after ms (×30) 최초: 09:00:00 · 최종: 09:58:00 · 유닛: myapp · syslog 30 occurrences (2.5/bucket) vs baseline 0.02/bucket — z=5.0, ×50.0 > error: pg query timeout after 5000 ms ``` 모든 발견에는 **왜 잡혔는지**가 붙습니다: 매칭된 규칙, 또는 스파이크의 정확한 건수와 z-score. ### LLM 简报（可选） `--llm`으로 AI 장애 요약을 켭니다. 규칙 엔진 리포트는 항상 전체 출력되며, LLM 호출이 실패해도 요약만 빠질 뿐 아무것도 잃지 않습니다. #### Anthropic API — 韩语简报 ``` export ANTHROPIC_API_KEY=sk-ant-... faultbrief --since 1h --lang ko --llm ``` `--lang ko`면 AI 브리핑도 한국어로 나옵니다: 상황 요약, 원인 가설, 영향 범위, 다음 확인 커맨드 순. #### OpenAI API ``` export OPENAI_API_KEY=sk-... export FAULTBRIEF_LLM_PROVIDER=openai export FAULTBRIEF_LLM_MODEL=gpt-4o-mini faultbrief --since 1h --lang ko --llm ``` #### 本地 Ollama — 无需云服务 ``` export FAULTBRIEF_LLM_PROVIDER=openai export FAULTBRIEF_LLM_BASE_URL=http://localhost:11434 export FAULTBRIEF_LLM_MODEL=llama3 faultbrief --since 1h --lang ko --llm ``` 설정 파일(`~/.config/faultbrief/config.yaml`)로도 가능: ``` lang: ko llm: provider: openai base_url: http://localhost:11434 model: llama3 ``` 우선순위: 플래그 > 환경변수 > 설정 파일 > 기본값. ### 用户规则 자기 서비스 전용 시그니처를 YAML로 추가: ``` - id: my-app-crash title: "우리 앱 크래시" severity: critical source: syslog # 생략 가능: journald, syslog, nginx-access, nginx-error, any contains: "my-app: segmentation fault" hint: "coredumpctl list; 마지막 배포 확인" example: "my-app: segmentation fault at 0x0" - id: slow-query title: "DB 쿼리 시간 초과" severity: error regex: "query took \\d+ms, exceeded" hint: "EXPLAIN ANALYZE 실행; 인덱스 누락 확인" example: "db: query took 5000ms, exceeded limit" ``` `--rules ./my-rules.yaml`로 로드. 규칙마다 `contains`/`regex` 중 정확히 하나만. 내장 규칙은 항상 함께 로드됩니다. ### 注意事项与限制 - nginx **error** 로그 타임스탬프에는 타임존이 없어 실행 머신의 로컬 시간으로 해석합니다. 에러 로그는 생성된 서버(또는 같은 TZ)에서 분석하세요. - nginx **access** 로그는 기본 `combined` 포맷만 지원합니다. 커스텀 `log_format`은 추후 지원 예정. - 원격 LLM 엔드포인트는 `https`를 쓰세요. `http`는 Ollama 같은 로컬 서비스용입니다 (API 키와 로그 발췌가 해당 URL로 전송됨). ### cron 集成示例 매시간 검사해서 발견이 있으면 메일로: ``` 0 * * * * faultbrief --since 1h --lang ko --format md > /tmp/brief.md || \ [ $? -eq 1 ] && mail -s "faultbrief: 발견 있음" ops@example.com < /tmp/brief.md ``` ## 许可证 MIT — 见 [LICENSE](LICENSE)。

标签：AI风险缓解, EVTX分析, Petitpotam, 云计算, 异常检测, 故障排查, 日志审计, 规则引擎, 运维工具