Official documentation: https://book.open-falcon.org/zh_0_2/usage/nodata.html

API reference: http://open-falcon.org/falcon-plus/

Agent Overview

Once the agent is deployed on a machine and properly configured with heartbeat (hbs) and transfer settings, it automatically starts collecting metrics and sending data to the backend.

Host Groups and Machine Registration

When adding machines to a host group via the portal, errors may occur if the target machine does not exist in the host table of the portal database. The agent’s heartbeat (hbs) configuraton is responsible for populating this table. Every minute, the agent sends a heartbeat to hbs containing its IP, hostname, and agent version. The hbs process then writes this data into the host table. If the table remains empty, verify that the agent-to-hbs communication path is functional.

Agent Configuration

The agent configuration file (cfg.json) controls how metrics are collected and forwarded. Below is a sample configuraton with explanations for each section.

{
    "debug": true,
    "hostname": "",
    "ip": "",
    "plugin": {
        "enabled": false,
        "dir": "./plugin",
        "git": "https://github.com/open-falcon/plugin.git",
        "logs": "./logs"
    },
    "heartbeat": {
        "enabled": true,
        "addr": "127.0.0.1:6030",
        "interval": 60,
        "timeout": 1000
    },
    "transfer": {
        "enabled": true,
        "addrs": [
            "127.0.0.1:8433",
            "127.0.0.1:8433"
        ],
        "interval": 60,
        "timeout": 1000
    },
    "http": {
        "enabled": true,
        "listen": ":1988"
    },
    "collector": {
        "ifacePrefix": ["eth", "em"]
    },
    "ignore": {
        "cpu.busy": true,
        "mem.swapfree": true
    }
}

• debug: Controls verbose logging. Set to false in production.
• hostname: Used as the endpoint when sending metrics. If empty, the system hostname is used.
• ip: IP address sent to hbs during heartbeat. Leave empty for auto-detection, or set explicitly.
• plugin: Enable/disable custom plugin collection. When enabled, the agent fetches scripts from the specified git repo.
• heartbeat: Connection details for hbs (heartbeat server). Set enabled: true and provide the hbs RPC address.
• transfer: Addresses of transfer servers. Multiple addresses provide redundancy. The agent sends collected data here.
• http: HTTP listener for pushing metrics via the /v1/push endpoint. Port 1988 is typical.
• collector.ifacePrefix: Network interfaces to monitor. Only interfaces with prefixes matching the list are polled (e.g., eth, em). Empty string collects all interfaces.
• ignore: List of built-in metrics to skip. Over 200 metrics are collected by default; this block suppresses unwanted ones.

Pushing Custom Metrics via HTTP API

You can push arbitrary metrics to the agent using its HTTP endpoint. The following curl command demonstrates the required payload format.

timestamp=$(date +%s)
curl -X POST -d "[{\"metric\": \"app.request.count\", \"endpoint\": \"web-server-01\", \"timestamp\": $timestamp, \"step\": 60, \"value\": 100, \"counterType\": \"GAUGE\", \"tags\": \"project=myapp,env=prod\"}]" http://127.0.0.1:1988/v1/push

Field Descriptions

• metric: The name of the measurement (e.g., cpu.idle, memory.free).
• endpoint: Identifies the subject of the metric (e.g., the hostname).
• timestamp: Unix epoch time in seconds.
• value: The numeric value of the metric (float64).
• step: The collection interval in seconds (important for alert rules).
• counterType: Either GAUGE (store as-is) or COUNTER (stored as rate: (current - previous) / interval).
• tags: Comma-separated key=value pairs for additional context (e.g., dc=us-east,service=web). Can be empty.

Production Configuration Example

cat agent/config/cfg.json
{
    "debug": false,
    "hostname": "",
    "ip": "",
    "plugin": {
        "enabled": false,
        "dir": "./plugin",
        "git": "https://github.com/open-falcon/plugin.git",
        "logs": "./logs"
    },
    "heartbeat": {
        "enabled": true,
        "addr": "falcon-server-ip:6030",
        "interval": 60,
        "timeout": 1000
    },
    "transfer": {
        "enabled": true,
        "addrs": [
            "falcon-server-ip:8433"
        ],
        "interval": 60,
        "timeout": 1000
    },
    "http": {
        "enabled": false,
        "listen": "127.0.0.1:1988",
        "backdoor": false
    },
    "collector": {
        "ifacePrefix": ["eth", "em"],
        "mountPoint": []
    },
    "default_tags": {},
    "ignore": {
        "cpu.busy": true,
        "df.bytes.free": true,
        "df.bytes.total": true,
        "df.bytes.used": true,
        "df.bytes.used.percent": true,
        "df.inodes.total": true,
        "df.inodes.free": true,
        "df.inodes.used": true,
        "df.inodes.used.percent": true,
        "mem.memtotal": true,
        "mem.memused": true,
        "mem.memused.percent": true,
        "mem.memfree": true,
        "mem.swaptotal": true,
        "mem.swapused": true,
        "mem.swapfree": true
    }
}

In a production setup, debug is set to false, HTTP listener is disabled, and many built-in disk/memory metrics are suppressed to reduce overhead. Adjust the addr and addrs fields to point to your actual hbs and transfer server IPs.

Windows Agent

For Windows machines, use the community-maintained agent port at: https://github.com/freedomkk-qfeng/windows-agent