If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/apache/hertzbeat shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 21+ active contributors
• Distributed ownership (top contributor 23% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live apache/hertzbeat repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apache/hertzbeat.

What it runs against: a local clone of apache/hertzbeat — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in apache/hertzbeat | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of apache/hertzbeat. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/apache/hertzbeat.git
#   cd hertzbeat
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of apache/hertzbeat and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/hertzbeat(\\.git)?\\b" \\
  && ok "origin remote is apache/hertzbeat" \\
  || miss "origin remote is not apache/hertzbeat (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/engine/SopEngineImpl.java" \\
  && ok "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/engine/SopEngineImpl.java" \\
  || miss "missing critical file: hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/engine/SopEngineImpl.java"
test -f "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/controller/ChatController.java" \\
  && ok "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/controller/ChatController.java" \\
  || miss "missing critical file: hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/controller/ChatController.java"
test -f "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/ConversationServiceImpl.java" \\
  && ok "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/ConversationServiceImpl.java" \\
  || miss "missing critical file: hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/ConversationServiceImpl.java"
test -f "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/LlmConfig.java" \\
  && ok "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/LlmConfig.java" \\
  || miss "missing critical file: hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/LlmConfig.java"
test -f "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/McpServerServiceImpl.java" \\
  && ok "hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/McpServerServiceImpl.java" \\
  || miss "missing critical file: hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/McpServerServiceImpl.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/apache/hertzbeat"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HertzBeat is an AI-powered, real-time observability and monitoring platform built in Java and TypeScript that unifies metrics collection, alerting, and visualization—replacing traditional tools like Prometheus + Grafana. It supports 200+ protocol collectors (HTTP, SNMP, SSH, JDBC, etc.) with a unified metric schema and provides out-of-the-box dashboards, multi-tenant management, and now integrates AI capabilities via Spring AI for intelligent anomaly detection and log analysis. Monorepo structure: hertzbeat-ai/ (new AI module), hertzbeat-core/, hertzbeat-collector/ (multi-protocol agent), hertzbeat-web/ (TypeScript/React frontend), script/ deployment configs, and e2e/ test data. Backend uses Spring Boot with WebFlux for reactive I/O; frontend is TypeScript/React with Less styling; collectors are pluggable via protocol definitions in config files. State management appears centralized via Spring context.

DevOps engineers, SREs, and platform teams who need enterprise-grade monitoring without maintaining complex Prometheus + Grafana stacks. Open-source contributors building observability infrastructure, and organizations seeking AI-enhanced alerting and rapid integration of heterogeneous monitoring protocols.

Production-ready with active development. The project is Apache-incubating (indicated by .asf.yaml, NOTICE, CODE_OF_CONDUCT), has comprehensive CI/CD via GitHub Actions (backend-build-test, frontend-build-test, e2e tests), multi-language test coverage, and Docker distribution (evidenced by docker-compose.yml and Docker Hub badge in README). Currently at v2.0-SNAPSHOT with Spring AI 1.1.1 integration showing recent feature expansion.

Moderate risk from Java version constraint (Java 25 required in hertzbeat-ai module, which is bleeding-edge) creating compatibility friction. Dependencies on Spring AI 1.1.1 and Spring Boot WebFlux are maintained but rapidly evolving; the monorepo spans 6+ languages (Java, TypeScript, Rust, Python) increasing maintenance surface. Single release channel (Apache) mitigates abandonment risk, but aggressive AI feature addition (Spring AI MCP server) may introduce instability.

Active AI integration: hertzbeat-ai module with Spring AI starter for MCP (Model Context Protocol) server, indicating LLM-driven observability features in progress. Recent E2E test framework additions (monitor-*.json payloads) suggest expanded test coverage. GitHub workflows show nightly builds and license checking, pointing to quality-gate improvements. Collector native build optimization (collector-native-build.yml) suggests Rust/GraalVM native compilation work.

git clone https://github.com/apache/hertzbeat.git
cd hertzbeat
mvn clean install -DskipTests
# For frontend
cd hertzbeat-web && npm install && npm start
# For backend
cd hertzbeat-core && mvn spring-boot:run

Requires Maven 3.6+, Java 21+ (for core) / Java 25 (for AI module), Node 16+. DevContainer config available at .devcontainer/devcontainer.json.

Daily commands:

# Backend (Spring Boot)
cd hertzbeat-manager && mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Frontend (Node/TypeScript)
cd hertzbeat-web && npm install && npm start  # Runs on http://localhost:3000
# Docker compose stack (recommended for full system)
cd e2e && docker-compose up -d

Backend default port: 8081. Set environment variables for DB connection if not using H2 in-memory.

• hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/engine/SopEngineImpl.java — Core SOP (Standard Operating Procedure) execution engine that orchestrates AI-powered automation workflows—the primary entry point for AI-driven observability tasks.
• hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/controller/ChatController.java — HTTP API controller for chat/conversation interactions; defines the public interface for AI chat features.
• hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/ConversationServiceImpl.java — Manages conversation persistence and retrieval; bridges UI interactions with LLM backends and chat state.
• hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/LlmConfig.java — Centralized LLM provider configuration (OpenAI, Claude, etc.); all AI model initialization depends on this config.
• hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/McpServerServiceImpl.java — MCP (Model Context Protocol) server integration; enables dynamic tool/resource management for LLM agents.
• hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/executor/SopExecutor.java — Abstract SOP task executor; defines the contract for all SOP step implementations (LLM, Tool, etc.).
• hertzbeat-ai/pom.xml — Maven POM defining hertzbeat-ai module dependencies, versions, and build lifecycle; required for any build or dependency modification.

Add a new LLM provider (e.g., Gemini, Claude)

1. Update LLM provider enum in hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/LlmConfig.java and add provider-specific properties (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/LlmConfig.java)
2. Implement ChatClientProviderServiceImpl to add a new case in the factory method for the new provider (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/ChatClientProviderServiceImpl.java)
3. Create a new LLM client adapter class (or use existing SDK) that implements the chat/completion interface expected by SopEngineImpl (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/engine/SopEngineImpl.java)
4. Add pom.xml dependency for the new LLM provider's SDK (hertzbeat-ai/pom.xml)

Add a new SOP step executor (custom task type)

1. Create a new class extending SopExecutor abstract base class and implement execute() method (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/executor/SopExecutor.java)
2. Register the new executor in SopEngineImpl's executor registry/factory (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/engine/SopEngineImpl.java)
3. Add SOP definition model fields for the new step type in the SOP config model if needed (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/model/OutputConfig.java)
4. Write integration tests to verify the executor is called correctly within SOP workflows (hertzbeat-ai/src/test)

Add a new MCP tool or resource

1. Implement the tool handler in McpServerServiceImpl; add it to the available tools registry (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/McpServerServiceImpl.java)
2. Update McpContextHolder to store the tool's metadata and callable reference (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/config/McpContextHolder.java)
3. LLM will discover the tool via MCP protocol; no code changes needed in LlmExecutor if using standard MCP binding (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/sop/executor/LlmExecutor.java)

Add a new chat API endpoint or feature

1. Add a new @RequestMapping method in ChatController for the new endpoint (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/controller/ChatController.java)
2. Create or extend ConversationService interface with the new business logic method (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/service/impl/ConversationServiceImpl.java)
3. Extend ChatRequestContext or ChatResponseChunk DTOs if new request/response fields are needed (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/pojo/dto/ChatRequestContext.java)
4. If persistence is needed, add a new DAO interface or extend ChatConversationDao/ChatMessageDao (hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/dao/ChatConversation)

Java 25 blocker: hertzbeat-ai module requires Java 25, but core may work on Java 21—check active profile. Database init: e2e/docker-compose.yml uses TimescaleDB; local MySQL/PostgreSQL setups require manual schema import from script/sql/. Frontend dev: npm dependencies in hertzbeat-web may be outdated (no lock file visible); run npm audit fix first. Collector registration: Collectors register dynamically; check hertzbeat-collector/src/main/java/org/apache/hertzbeat/collector/collect/ for available types before adding new protocols. MCP server state: Spring AI 1.1.1 MCP integration is experimental; production use of AI features not yet recommended. Multi-language CI: License checker (.github/workflows/license-checker.yml) enforces ASL 2.0; all contributions must include proper headers.

• Protocol Pluggability (YAML-Driven Collectors) — HertzBeat's 200+ protocol support is defined as YAML configurations in define/ rather than compiled plugins; understanding this pattern is key to adding new monitored systems
• Reactive Streams (Project Reactor / WebFlux) — Backend uses Spring WebFlux and Project Reactor for non-blocking I/O; critical for understanding latency-sensitive metric collection and alert handling
• Model Context Protocol (MCP) — New Spring AI integration uses MCP for LLM-agent communication; foundational to understanding the AI feature roadmap
• Multi-Protocol Metric Normalization — HertzBeat normalizes SNMP OIDs, HTTP JSON paths, JDBC queries, etc. into unified metric schemas; understanding metric transformation is essential for adding collectors
• TimescaleDB for Time-Series Storage — Default storage backend in e2e setup; understanding time-series optimization (chunks, continuous aggregates) matters for performance tuning
• Spring AI MCP Server (Experimental) — Emerging AI-driven monitoring feature using Model Context Protocol; critical for understanding planned anomaly detection and intelligent alerting
• Monorepo Polyglot Build (Maven + npm + Rust) — Project spans Java (Maven), TypeScript (npm), and Rust (native collectors); understanding multi-language CI/CD in .github/workflows is necessary for full-stack contributions

• prometheus/prometheus — Industry-standard metrics collection alternative; HertzBeat can scrape Prometheus endpoints and provides unified replacement for Prometheus + Grafana
• grafana/grafana — UI/visualization competitor; HertzBeat includes built-in dashboards eliminating need for separate Grafana setup
• elastic/beats — Similar protocol-based data collector architecture; HertzBeat's multi-collector pattern mirrors Beats' modular design
• open-telemetry/opentelemetry-java — Complementary observability standard; HertzBeat metrics can be exported to OpenTelemetry collectors for enterprise integration
• alibaba/nacos — Often deployed alongside HertzBeat for service discovery and config management in cloud-native stacks

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for hertzbeat-ai Spring AI integration

The hertzbeat-ai module uses Spring AI 1.1.1 with MCP server support but lacks visible test coverage. Given the critical nature of AI-powered observability features and the presence of spring-boot-starter-test in dependencies, this module needs dedicated unit tests for AI model integration, MCP server handlers, and WebFlux endpoints. This directly supports the repo's OpenSSF Best Practices badge and improves codecov metrics.

• [ ] Create hertzbeat-ai/src/test/java/org/apache/hertzbeat/ai/ directory structure
• [ ] Add unit tests for MCP server endpoint handlers (test Spring AI starter-mcp-server-webmvc configuration)
• [ ] Add integration tests for WebFlux reactive endpoints used by AI features
• [ ] Add tests validating AI model responses and error handling
• [ ] Ensure test coverage reports to codecov (already integrated in repo)

Create GitHub Actions workflow for hertzbeat-ai module CI/CD

The .github/workflows/ directory contains workflows for backend, frontend, collector, and docs builds, but no dedicated workflow for the hertzbeat-ai module. With Java 25 as a requirement and Spring AI 1.1.1 dependencies, a separate workflow would catch AI-specific build failures early, ensure compatibility with newer JDK versions, and prevent integration issues before they reach the main backend-build-test.yml.

• [ ] Create .github/workflows/hertzbeat-ai-build-test.yml
• [ ] Configure Maven build steps targeting hertzbeat-ai/pom.xml with Java 25
• [ ] Add dependency verification for Spring AI version compatibility
• [ ] Integrate test reporting to codecov
• [ ] Set workflow triggers for PR changes to hertzbeat-ai/ directory and pom.xml files

Add E2E tests for AI-powered monitoring features

The e2e/ directory contains test suites for HTTP, FTP, ping, port, and website monitors but lacks tests for AI-specific features (e.g., AI-assisted alert generation, natural language monitor configuration). With the AI module now in the codebase, adding E2E tests would validate the AI features in realistic observability scenarios and ensure AI integrations work end-to-end with the collector and dashboard.

• [ ] Create e2e/data/monitor-ai-config.json with AI-assisted monitor configuration examples
• [ ] Add test cases to e2e/testsuite.yaml for AI alert recommendation workflows
• [ ] Create Docker Compose setup in e2e/ that includes AI model service (if applicable)
• [ ] Document AI feature E2E test procedures in e2e/README.md
• [ ] Integrate tests into existing monitor-e2e-test.yml GitHub Actions workflow

• Add unit tests for missing protocol collectors: hertzbeat-collector/src/main/resources/define/ has 200+ YAML definitions but corresponding test files in src/test/java/org/apache/hertzbeat/collector/collect/ are sparse. Pick one protocol (e.g., FTP, UDP, Sitemap) and write integration tests.
• Document AI feature setup in README.md: hertzbeat-ai module is new (Spring AI 1.1.1) but no Getting Started guide exists. Create AI_SETUP.md with LLM configuration, MCP server usage, and example anomaly detection rule.
• Improve frontend TypeScript strictness: hertzbeat-web has .ts files alongside .tsx but no tsconfig strict mode enforced; add "strict": true to tsconfig.json and fix the resulting type errors (likely in state management slices).

• High · Incomplete POM File - Dependency Analysis Blocked — hertzbeat-ai/pom.xml. The pom.xml file is truncated and incomplete. The junit-platform-launcher dependency section is cut off mid-declaration with '<scope>test</sco' instead of '</scope>'. This prevents complete analysis of all dependencies and their versions for known CVEs. Fix: Provide the complete pom.xml file. Ensure all dependency declarations are properly closed and validate against dependency-check tools.
• High · Java 25 Compatibility Risk — hertzbeat-ai/pom.xml (property: java.version=25). The project specifies Java 25 as the target version in hertzbeat-ai/pom.xml. Java 25 is a very recent release with limited production stability and community testing. Most enterprise dependencies may not be fully tested against Java 25, potentially introducing unknown vulnerabilities. Fix: Consider using Java 21 LTS or Java 23 as target versions for better stability and broader library compatibility. Only use Java 25 if absolutely necessary and after extensive testing.
• Medium · Spring AI MCP Server Dependency - Review Required — hertzbeat-ai/pom.xml. The project includes 'spring-ai-starter-mcp-server-webmvc' dependency. Spring AI integration with MCP (Model Context Protocol) servers requires careful security review to prevent prompt injection, model abuse, and unauthorized data access through the MCP interface. Fix: Conduct security review of MCP endpoint implementations. Implement strict input validation on all MCP protocol messages. Enforce authentication and authorization controls on MCP server endpoints. Consider implementing rate limiting.
• Medium · WebFlux Reactive Stack - Potential Resource Exhaustion — hertzbeat-ai/pom.xml. The inclusion of 'spring-boot-starter-webflux' suggests reactive/async operations. Without proper configuration, reactive systems can be vulnerable to slowloris attacks, backpressure issues, and resource exhaustion if concurrent connections aren't properly limited. Fix: Configure WebFlux thread pools, connection limits, and timeout settings in application configuration. Implement request size limits and validate backpressure handling.
• Medium · Missing Security Dependencies — hertzbeat-ai/pom.xml. The visible dependencies lack explicit security-related libraries. No evidence of spring-security, CSRF protection, or encryption libraries in the visible pom.xml section. The AI module handling chat conversations and scheduling may require stronger security controls. Fix: Add spring-boot-starter-security for authentication/authorization. Include cryptography libraries (Bouncy Castle) for sensitive data. Add input validation libraries (Hibernate Validator). Review SecurityData.java implementation.
• Medium · Potential Unencrypted Data Storage - Chat/Conversation Data — hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/dao/ChatConversationDao.java, ChatMessageDao.java. The presence of ChatConversationDao and ChatMessageDao suggest persistent storage of chat data. Without proper encryption configuration, sensitive conversation data (potentially including credentials, API keys, or system information shared in chat) could be stored in plaintext. Fix: Implement encryption at rest for all stored chat conversations. Use database-level encryption or application-level encryption. Review the SecurityData.java class to ensure proper handling of sensitive fields.
• Medium · Schedule Executor - Code Injection Risk — hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai/schedule/SopScheduleExecutor.java. The SopScheduleExecutor class suggests execution of scheduled operations based on user input. If SOP (Standard Operating Procedures) can be user-defined or templated without strict validation, this could lead to code injection or expression language injection attacks. Fix: Validate all SOP configuration inputs before execution. Use a whitelist of allowed operations. Avoid using expression languages or script evaluation. Implement sandboxing for any dynamic execution.
• Low · LLM Configuration Security — hertzbeat-ai/src/main/java/org/apache/hertzbeat/ai. The LlmConfig class likely contains configuration for language model integration. API keys, endpoints, and model parameters should be carefully secured to prevent unauthorized API usage or model manipulation. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.