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/open-falcon/falcon-plus 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 all four use cases

• 53+ active contributors
• Distributed ownership (top contributor 17% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{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 open-falcon/falcon-plus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/open-falcon/falcon-plus.

What it runs against: a local clone of open-falcon/falcon-plus — 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 open-falcon/falcon-plus | 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 ≤ 773 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of open-falcon/falcon-plus. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/open-falcon/falcon-plus.git
#   cd falcon-plus
#
# 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 open-falcon/falcon-plus and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "open-falcon/falcon-plus(\\.git)?\\b" \\
  && ok "origin remote is open-falcon/falcon-plus" \\
  || miss "origin remote is not open-falcon/falcon-plus (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 "common/model/rpc.go" \\
  && ok "common/model/rpc.go" \\
  || miss "missing critical file: common/model/rpc.go"
test -f "common/backend_pool/rpc_backends.go" \\
  && ok "common/backend_pool/rpc_backends.go" \\
  || miss "missing critical file: common/backend_pool/rpc_backends.go"
test -f "common/db/db.go" \\
  && ok "common/db/db.go" \\
  || miss "missing critical file: common/db/db.go"
test -f "cmd/start.go" \\
  && ok "cmd/start.go" \\
  || miss "missing critical file: cmd/start.go"
test -f "common/model/strategy.go" \\
  && ok "common/model/strategy.go" \\
  || miss "missing critical file: common/model/strategy.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 773 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~743d)"
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/open-falcon/falcon-plus"
  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).

Open-Falcon (Falcon+) is an enterprise-grade distributed monitoring and alerting system written primarily in Go that collects metrics from agents, stores them in TSDB/InfluxDB/Prometheus backends, evaluates alert rules via the Judge component, and manages alert workflows through Portal and Dashboard UIs. It solves the problem of monitoring large-scale infrastructure by providing a scalable, modular architecture for metric collection, storage, querying, and alarm management across thousands of hosts. Modular monorepo organized by component: cmd/ contains CLI entry points (start, stop, reload, restart, monitor, check), common/ houses shared data models (model/), database logic (db/), RPC backends (backend_pool/), and a Go SDK (sdk/) for external integrations. Each component (agent, judge, graph, transfer, portal) likely has its own module directory (inferred from common/model files like judge.go, graph.go, transfer.go) that consumes these shared types.

DevOps engineers, SREs, and infrastructure teams running large distributed systems who need to monitor thousands of servers with custom alerting rules, metric dashboards, and multi-tenant alert management (via UIC—User Identity & Control). The codebase is maintained by the open-falcon community but the README now recommends Nightingale for new k8s/microservices deployments.

Production-ready but aging: Go 1.15 minimum (released 2020), supports MySQL and Redis backends, has Travis CI configured, includes database migration schemas, and follows semantic versioning (VERSION file exists). However, the README explicitly recommends users migrate to Nightingale for modern cloud-native setups, suggesting this project is in maintenance mode rather than active feature development.

Moderate risk: heavy dependency on legacy Beego v1.8.3 framework (unmaintained), Go module version is outdated (1.15), last major activity appears focused on Prometheus integration rather than core features, and the project's own maintainers recommend alternatives. Single-maintainer risk is present given the recommendation to move to Nightingale; breaking changes are unlikely but dependency vulnerabilities are a concern.

The project is in maintenance/recommendation mode. The README prominently features a notice recommending users upgrade to Nightingale (cloud-native) or Categraf (collector). The visible work appears to be backwards compatibility and Prometheus/InfluxDB integration (evidenced by prometheus.go, influxdb.go in models), but no active feature work is apparent from the file structure.

mkdir -p $GOPATH/src/github.com/open-falcon
cd $GOPATH/src/github.com/open-falcon
git clone https://github.com/open-falcon/falcon-plus.git
cd falcon-plus
# Initialize MySQL databases
mysql -h 127.0.0.1 -u root -p < scripts/mysql/db_schema/1_uic-db-schema.sql
mysql -h 127.0.0.1 -u root -p < scripts/mysql/db_schema/2_portal-db-schema.sql
mysql -h 127.0.0.1 -u root -p < scripts/mysql/db_schema/3_dashboard-db-schema.sql
mysql -h 127.0.0.1 -u root -p < scripts/mysql/db_schema/4_graph-db-schema.sql
mysql -h 127.0.0.1 -u root -p < scripts/mysql/db_schema/5_alarms-db-schema.sql
# Start Redis
redis-server
# Build all modules
make all

Daily commands: After prerequisites (Redis, MySQL initialized): make all builds all modules. Individual modules appear to use standard Go binary execution (referenced in cmd/ entry points). Exact daemon startup inferred from cmd files: ./cmd/start.go, ./cmd/monitor.go suggest binaries in root or bin/ after compilation. Docker images available (Dockerfile, Dockerfile.module, Dockerfile_arm64) for containerized deployment.

• common/model/rpc.go — Defines RPC data structures and interfaces used across all monitoring components for inter-service communication.
• common/backend_pool/rpc_backends.go — Manages RPC backend connections and routing; critical for service discovery and failover logic.
• common/db/db.go — Database abstraction layer connecting all components to MySQL; handles schema initialization and queries.
• cmd/start.go — Main entry point for falcon services; orchestrates initialization of all modules and config loading.
• common/model/strategy.go — Strategy/alert rule data model; core to the alerting pipeline that all monitoring logic depends on.
• common/sdk/sender/sender.go — SDK for agents to push metrics to transfer; primary ingestion path for monitoring data.
• config/falcon2p8s.json — Configuration template showing integration architecture with Prometheus and InfluxDB backends.

Add a new metric collection type to agents

1. Define metric type constants in common/model/metric.go (common/model/metric.go)
2. Create collection plugin in agent module that produces MetricValue structs (common/model/metric.go)
3. Use common/sdk/sender/sender.go PushMetric() API to submit metrics (common/sdk/sender/sender.go)
4. Update agent config template to expose collection parameters (config/agent.json)

Add a new alerting strategy rule type

1. Extend strategy.go with new rule struct and evaluation logic (common/model/strategy.go)
2. Add rule persistence schema update in common/db/db.go ORM models (common/db/db.go)
3. Define RPC method in common/model/rpc.go for Judge to fetch new rule types (common/model/rpc.go)
4. Implement evaluation in Judge module using the new RPC contract (common/model/rpc.go)

Add support for a new time-series backend (e.g., VictoriaMetrics)

1. Create new backend pool handler similar to tsdb_backends.go pattern (common/backend_pool/tsdb_backends.go)
2. Extend common/model/rpc.go with new backend RPC methods (common/model/rpc.go)
3. Add backend connection config to common/db/db.go initialization (common/db/db.go)
4. Register backend in Transfer module using backend pool routing (common/backend_pool/tsdb_backends.go)

Deploy a new monitoring component to Kubernetes

1. Create service YAML in docker/k8s-cluster/modules/ following falcon-agent.yaml pattern (docker/k8s-cluster/modules/falcon-agent.yaml)
2. Add config template in config/ directory for the new service (config/agent.json)
3. Use Dockerfile.module to build container, setting SERVICE env var (Dockerfile.module)
4. Reference backend services via K8s DNS and update RPC endpoints (common/backend_pool/rpc_backends.go)

• Go + Beego/Gin — Low-latency, high-concurrency monitoring requires efficient I/O; Go's goroutines handle thousands of concurrent metric pushes and RPC calls.
• MySQL with ORM (GORM) — Centralized storage for alert rules, agent registrations, and strategy configuration; ACID compliance ensures consistency across distributed services.
• RPC over TCP — Inter-service communication must be fast and reliable; avoids HTTP overhead for high-frequency internal calls.
• Redis (garyburd/redigo) — Optional caching layer for metric queries and rule lookups to reduce database load; session/state persistence for API.
• InfluxDB/TSDB Backend — Purpose-built time-series storage; optimizes compression and query performance for high-cardinality metrics over retention windows.
• Docker & Kubernetes support — Enterprise deployments require orchestration; modular containerization allows scaling individual components independently.

• Asynchronous metric batching (linkedlist sender)

  • Why: Minimizes agent lock contention and network overhead; reduces backpressure from slow collectors
  • Consequence: Brief metric delivery delay (~seconds); not suitable for sub-second alerting; requires careful TTL tuning to avoid data loss on agent crash

• Pull-based rule fetching vs push-based rule distribution

  • Why: Simpler deployment; no need for config change notification channels; Judge/Transfer poll rules on startup and interval
  • Consequence: Stale rules for up to polling interval (typically seconds); rule changes have observable propagation delay

• Monolithic model files (rpc.go, strategy.go) shared across services

  • Why: Single source of truth for contracts; avoids duplication and versioning mismatches
  • Consequence: Tight coupling; changes to data model require coordinated deploys; no independent service evolution

• Synchronous RPC calls in alert evaluation path

  • Why: Ensures alert decisions use current metrics and strategy state; simpler reasoning about alert consistency
  • Consequence: Judge latency blocked on Graph/TSDB response time; slow backend = slow alerting; difficult to scale under high cardinality

• Single MySQL database for all state

  • Why: Simplified operations; ACID guarantees simplify concurrent updates to rules and agent registry
  • Consequence: Database becomes bottleneck at scale; no horizontal scaling of rule storage; master-slave replication adds complexity for HA

• Real-time log aggregation (metrics-only; use ELK/Loki for logs)
• Multi-tenancy support (no built-in tenant isolation)
• GraphQL API (HTTP/RPC only; REST through api module)
• Agent auto-discovery beyond heartbeat mechanism
• Built-in authentication/RBAC (relies on network isolation or reverse proxy)
• Distributed tracing (no trace collection or propagation)
• Query federation across multiple TSDB backends (single backend per transfer instance)

1. Database initialization is mandatory: all 5 SQL schemas (1_uic through 5_alarms) must be loaded in order before first run—missing any schema causes silent failures in that module. 2) Redis and MySQL must be running: common/db/db.go and SDK assume these services are available; no fallback or in-memory mode. 3) $GOPATH must be set correctly: the clone path (github.com/open-falcon/falcon-plus) is hardcoded in import paths; cloning to other paths breaks builds. 4) RPC communication assumes localhost or configured backend endpoints: no service discovery; each component needs static IP:port config pointing to Judge, Graph, Transfer, etc. 5) go.mod references v1.15: upgrading Go may cause dependency conflicts (Beego v1.8.3 is very old). 6) InfluxDB and Prometheus backends are optional but RPC types are required: you cannot run Judge without understanding model/judge.go even if using Prometheus backend.

• Time-Series Database (TSDB) Abstraction — Falcon+ abstracts storage via backend_pool/tsdb_backends.go to support InfluxDB, Prometheus, and native TSDB interchangeably—understanding this pattern is essential to adding new backends or swapping storage engines
• RPC (Remote Procedure Call) for Inter-Component Communication — All Falcon+ components (agent, judge, graph, transfer, portal) communicate via RPC using message types in common/model/rpc.go; understanding RPC is required to trace data flow or add new components
• Alert Rule Evaluation via Judge Component — The Judge component evaluates expressions (common/model/expression.go) against incoming metrics to fire alerts; this is the core anomaly-detection logic and requires understanding expression parsing and threshold comparison
• Backend Pool Pattern — common/backend_pool/ implements a connection pool abstraction across RPC backends (Judge, Graph, TSDB) with failover logic; essential for understanding Falcon+'s scalability and multi-backend routing
• Agent-Collector-Transfer-Judge Pipeline — Falcon+ architecture follows a four-stage data pipeline (Agent collects → Transfer aggregates → Judge evaluates → outputs alerts); understanding this flow is critical to debugging end-to-end metric delivery issues
• SDK for Metrics Instrumentation — common/sdk/sender implements client-side buffering, batching, and retry logic for external applications pushing metrics; developers integrating Falcon+ need to understand this queue-based design to avoid blocking or data loss
• Multi-Tenant Alert Management (UIC) — User Identity & Control (UIC) module manages role-based access, alert contacts, and notification routing; understanding how alerts flow from Judge → UIC → notification channels is essential for ops teams

• ccfos/nightingale — Official successor recommended in the README; cloud-native drop-in replacement for Prometheus alerting and Falcon+ management with modern architecture
• flashcatcloud/categraf — Companion telemetry collector recommended alongside Nightingale; replaces Falcon+ agent for modern deployments with multi-backend support (Prometheus, M3DB, VictoriaMetrics, InfluxDB, TDengine)
• prometheus/prometheus — Alternative time-series backend that Falcon+ can use via its Prometheus integration (common/model/prometheus.go); many users migrate from Falcon+ to pure Prometheus + Alertmanager
• influxdata/influxdb — Optional TSDB backend supported by Falcon+ via backend_pool abstraction and influxdb.go model; common alternative to native TSDB for metrics storage
• grafana/grafana — Visualization companion often paired with Falcon+ for dashboarding; Falcon+ Graph module predates modern Grafana but users often use both in hybrid setups

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 common/utils package functions

The common/utils directory contains utility functions (date.go, formatter.go, tags.go, md5.go) but only has test coverage for md5_test.go and tags_test.go. The func.go, formatter.go, date.go, and map.go files lack unit tests. This is critical for a monitoring system where data formatting and utilities are foundational. Adding tests would prevent regressions in core utilities used across all modules.

• [ ] Create common/utils/date_test.go with tests for date parsing/formatting functions
• [ ] Create common/utils/formatter_test.go with tests for metric/event formatting logic
• [ ] Create common/utils/map_test.go with tests for map utility functions
• [ ] Expand common/utils/func_test.go to cover additional functions in func.go
• [ ] Ensure tests cover edge cases relevant to monitoring (timezone handling, large numbers, special characters in tags)

Add integration tests for common/model data structures with database layer

The common/model directory defines critical data structures (strategy.go, event.go, metric.go, agent.go) and common/db/db.go provides database connectivity, but there are no visible integration tests validating that these models correctly serialize/deserialize with the MySQL backend. This is essential for a monitoring system where data integrity directly impacts alerting reliability.

• [ ] Create common/model/integration_test.go testing strategy model CRUD operations via common/db
• [ ] Add tests for event.go serialization and storage to ensure alert data isn't corrupted
• [ ] Test agent.go model persistence and retrieval from MySQL backend
• [ ] Add tests validating metric.go model handles various data types and edge cases (NaN, Inf, very large timestamps)
• [ ] Include tests for template.go model relationship integrity with strategy

Add GitHub Actions CI workflow for Go module dependency and security scanning

The repo uses .travis.yml (Travis CI) but the go.mod shows outdated dependencies (Go 1.15, beego v1.8.3 from 2016, gorm v0.0.0 with invalid version). There's no visible automated scanning for vulnerable dependencies or Go module tidiness. Adding a GitHub Actions workflow would catch supply chain issues early, especially critical for an enterprise monitoring system handling sensitive infrastructure data.

• [ ] Create .github/workflows/go-security.yml with Go 1.20+ latest stable version testing
• [ ] Add 'go mod tidy' and 'go mod verify' checks to catch module inconsistencies
• [ ] Integrate govulncheck (golang.org/x/vuln/cmd/govulncheck) to scan for known vulnerabilities
• [ ] Add golangci-lint step to detect code quality issues across cmd/, common/, and config modules
• [ ] Configure the workflow to fail on any go.mod/go.sum discrepancies or high-severity CVEs

• Add unit tests for common/model/strategy.go and common/model/expression.go: these define core alert rule parsing/evaluation but have no visible test files in the structure; write tests validating strategy JSON unmarshaling and expression evaluation logic.
• Document the RPC protocol in api-standard.md with concrete examples for each message type in common/model/rpc.go (e.g., show sample JSON for MetricValue, Judge request/response, Graph query)—currently api-standard.md exists but is sparse.
• Add integration test or example showing end-to-end metric flow from SDK push (common/sdk/sender) → Transfer → Graph → Judge with sample Docker Compose configuration similar to docker/README.md but with all 5 components.

• Critical · Outdated and Vulnerable Dependencies — go.mod dependencies. Multiple dependencies are significantly outdated and contain known vulnerabilities: beego v1.8.3 (from 2016), gorm v0.0.0-20170703134954 (from 2017), and other packages from 2015-2017 era. These versions have numerous documented CVEs including SQL injection, authentication bypass, and denial of service vulnerabilities. Fix: Update all dependencies to their latest stable versions. Priority updates: github.com/astaxie/beego (upgrade to v2.x or replace with maintained alternatives), github.com/jinzhu/gorm (upgrade to gorm.io/gorm v1.x+), and other outdated packages.
• High · Hardcoded Database Credentials in Docker Compose — docker-compose.yml. Database credentials are hardcoded in docker-compose.yml with MYSQL_ROOT_PASSWORD set to 'root' and connection strings visible in plaintext environment variables. This exposes sensitive information in version control and deployment configurations. Fix: Use Docker secrets or environment files (.env files that are gitignored) to manage sensitive credentials. Replace hardcoded values with placeholder variables loaded from secure secret management systems.
• High · SQL Injection Risk via Raw SQL Queries — common/db/db.go, common/model/*.go. The presence of SQL-related models and database operations (common/model and common/db) combined with outdated GORM version (v0.0.0-20170703134954) indicates high risk of SQL injection vulnerabilities. Older GORM versions have inadequate parameterization protections. Fix: Audit all database queries for proper parameterized statement usage. Upgrade GORM to latest version (gorm.io/gorm). Implement input validation and use ORM features exclusively, avoiding raw SQL concatenation.
• High · Unvalidated RPC Communication — docker-compose.yml, common/backend_pool/rpc_backends.go. Multiple RPC endpoints exposed (HBS_RPC, TRANSFER_RPC, JUDGE_RPC) in docker-compose.yml without apparent authentication or TLS encryption. RPC services can be targets for unauthorized access and data manipulation. Fix: Implement TLS encryption for all RPC connections. Add authentication mechanisms (API keys, mutual TLS) to RPC endpoints. Restrict RPC port exposure to internal networks only.
• High · Exposed Ports Without Authentication — Dockerfile (EXPOSE 8433 8080). Dockerfile exposes ports 8433 and 8080 without documented authentication requirements. Dashboard and API ports are directly accessible, potentially allowing unauthorized access to monitoring data and system controls. Fix: Implement authentication and authorization for all exposed ports. Use API gateways with rate limiting and authentication. Document security requirements for port access. Consider running services behind reverse proxies with TLS.
• High · Go Module Dependency with Empty Version — go.mod (github.com/toolkits/conn_pool v0.0.0-). github.com/toolkits/conn_pool v0.0.0- has an incomplete version constraint, which may resolve to an unpredictable version or fail during builds, creating supply chain risks. Fix: Specify complete semantic version constraints for all dependencies. Complete the version for toolkits/conn_pool or pin to a specific release tag.
• Medium · Missing Security Headers Configuration — cmd/start.go, common/model/rpc.go. No visible security headers configuration (X-Frame-Options, X-Content-Type-Options, CSP, etc.) in HTTP server setup. The API and dashboard may be vulnerable to clickjacking and content-type sniffing attacks. Fix: Implement comprehensive HTTP security headers in all HTTP server configurations. Add middleware for X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Content-Security-Policy, and Strict-Transport-Security headers.
• Medium · Potential Command Injection in Shell Scripts — ``. Shell scripts for configuration generation (config/confgen.sh, docker/confgen4docker.sh, docker/k8s-cluster/build.sh) may be vulnerable to command injection if environment variables are not properly quoted or validated. 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.