Hooks & Push Integration

v0.4.0 introduces automated alert-triggered analysis and multi-target push notifications

---

Overview

The Hooks & Push system enables a fully automated incident workflow:

1. Grafana/PagerDuty fires an alert → webhook hits the hook server
2. Hook Dedup Engine merges duplicate alerts within the TTL window
3. Analysis is auto-triggered on the deduplicated alert
4. Push Dispatcher sends results to all configured targets in parallel

Alert → Hook Server → Dedup → Analyze → Push (Feishu/Slack/JIRA)

---

Hook Server

The hook server is a lightweight HTTP server that receives alert webhooks and triggers analysis.

Start the Server

# CLI
npx kafka-log-analyze hooks --port 3100

# Or via MCP Tool
{ "tool": "start_hooks", "input": { "port": 3100 } }

Endpoints

Method	Path	Description
POST	/hooks/grafana	Receive Grafana unified/legacy alerting webhooks
POST	/hooks/pagerduty	Receive PagerDuty Events API v2 payloads
GET	/hooks/health	Health check ({ "status": "ok" })

MCP Tools

Tool	Description
start_hooks	Start the hook server
stop_hooks	Stop the hook server
list_hooks	Show server status and dedup statistics

---

Dedup Engine

The dedup engine prevents alert storms from triggering redundant analyses.

• Fingerprinting: Alerts are fingerprinted by source, labels, and annotations
• TTL Window: HOOK_DEDUP_WINDOW_MS (default: 300000 / 5 minutes) — duplicate alerts within this window are merged
• Merge Count: HOOK_MAX_MERGE_COUNT (default: 10) — max alerts to merge per fingerprint before forcing a flush

When multiple alerts share a fingerprint within the TTL window, they are merged into a single analysis trigger rather than processed individually.

---

Push Targets

Results are dispatched in parallel to all configured push targets.

Feishu (飞书)

Push analysis results as interactive card messages to Feishu groups.

Configuration:

• FEISHU_WEBHOOK_URL — Feishu custom bot webhook URL

Setup:

1. In Feishu group, add a "Custom Bot" integration
2. Copy the webhook URL to FEISHU_WEBHOOK_URL
3. Test with: npx kafka-log-analyze push-test --target feishu

Slack

Push analysis results as Block Kit messages to Slack channels.

Configuration:

• SLACK_WEBHOOK_URL — Slack incoming webhook URL

Setup:

1. Create a Slack App with incoming webhooks enabled
2. Install the app to your workspace and copy the webhook URL
3. Set SLACK_WEBHOOK_URL
4. Test with: npx kafka-log-analyze push-test --target slack

JIRA

Automatically create JIRA issues from analysis results with priority mapping.

Configuration:

• JIRA_URL — JIRA base URL (e.g., https://your-domain.atlassian.net)
• JIRA_TOKEN — JIRA API token
• JIRA_PROJECT_KEY — JIRA project key (e.g., KAFKA)

Priority Mapping:

Analysis Priority	JIRA Priority
P0 (Critical)	Highest
P1 (High)	High
P2 (Medium)	Medium
P3 (Low)	Low

Setup:

1. Create an API token in your Atlassian account settings
2. Set the three JIRA_* environment variables
3. Test with: npx kafka-log-analyze push-test --target all

Push Test

# Test individual targets
npx kafka-log-analyze push-test --target feishu
npx kafka-log-analyze push-test --target slack

# Test all configured targets
npx kafka-log-analyze push-test --target all

---

Grafana Alert Configuration

To configure Grafana to send alerts to the hook server:

1. In Grafana, go to Alerting → Contact points
2. Add a new contact point of type Webhook
3. Set the URL to: http://<hook-server-host>:3100/hooks/grafana
4. Save and test the contact point

Supported Payloads

• Unified alerting (Grafana 9+): Handles the Alerts[] payload format
• Legacy alerting (Grafana 8 and below): Handles the classic payload format

Both formats are automatically detected and normalized into a HookPayload.

---

PagerDuty Integration

To configure PagerDuty to send alerts:

1. In PagerDuty, go to Services → Integrations
2. Add a Custom Event Transformation integration
3. Configure the webhook to POST to: http://<hook-server-host>:3101/hooks/pagerduty
4. The hook server accepts Events API v2 payloads

---

Environment Variables Summary

Variable	Description	Default
GRAFANA_WEBHOOK_PORT	Hook server port	3100
PAGERDUTY_WEBHOOK_PORT	PagerDuty webhook port	3101
FEISHU_WEBHOOK_URL	Feishu webhook URL	-
SLACK_WEBHOOK_URL	Slack webhook URL	-
JIRA_URL	JIRA base URL	-
JIRA_TOKEN	JIRA API token	-
JIRA_PROJECT_KEY	JIRA project key	-
HOOK_DEDUP_WINDOW_MS	Dedup TTL (ms)	300000
HOOK_MAX_MERGE_COUNT	Max merge count	10

---

Related Documentation

• Commands — CLI command reference
• Configuration — Full environment variable reference
• API Reference — MCP Tools API documentation