Language / Язык: English | Русский

Alligator is an aggregator for system and software metrics. It is an incredibly versatile tool, allowing anyone to effortlessly gather and aggregate metrics from a wide array of sources, including software, operating systems, and numerous other systems in infrastructure. Its capabilities empower users to comprehensively monitor and analyze the performance and behavior of servers. By seamlessly interfacing with diverse systems and platforms, Alligator enables users to gain visibility and insight into their infrastructure and applications.

Alligator supports GNU/Linux, FreeBSD, and macOS. For installation instructions, see the distribution doc.

For more examples check URL with tests

Unit tests and coverage: testing.

alligator [-h|--help] [-v|--version] [-l <level>] [<path>]

If no path is given, the default config basename is /etc/alligator on Linux and /usr/local/etc/alligator on FreeBSD.

Alligator supports YAML, JSON or plain-text format. In examples we will consider only plain text format. For more information please refer to the detailed documentation or the tests.

When no path is passed on the command line, alligator loads the default basename (/etc/alligator on Linux, /usr/local/etc/alligator on FreeBSD). For that basename it tries, in order:

1. {basename}.json
2. {basename}.yaml
3. {basename}.conf

If {basename} is a directory, every file inside it with extensions .yaml, .json, or .conf is loaded (split configs / includes). If {basename} is a regular file, that file is parsed directly.

You can also pass an explicit path on the command line:

alligator /path/to/alligator.conf
alligator /etc/alligator.d/

Configuration can be overridden or extended with environment variables (ALLIGATOR__…). See configuration — environment variables.

Alligator has many contexts for describing the collection data:

• aggregate: Collects metrics from software using various parsers from software
• query: Generates new metrics internally through PromQL queries or database queries
• namespace: Configures metric namespaces and optional emission limits (max_emit)
• entrypoint: Receives metrics via Pushgateway, Statsd or Graphite protocols. It also configures the listen policy of ports to pass metrics to Prometheus, or make queries to the internal Alligator API
• lang: Runs functions and methods from subprograms
• x509: Obtains metrics from PEM, JKS or PKCS certificate formats
• action: Runs commands in response to the metrics behaviour. It allows for proactive monitoring policy.
• scheduler: Configures the repeat time to run lang or actions by alligator.
• resolver: Configures Alligator DNS and enables collecting metrics from DNS resolution checks
• persistence: Saves metrics to the filesystem that enable preservation metrics between restarts
• modules: Loads dynamic C libraries (files with .so extension)
• cluster: Configures the cluster using the node group
• puppeteer: Configures the HTTP site stats collector using the puppeteer
• chromecdp: Collects browser loading statistics via Chrome DevTools Protocol (no Node.js)
• threaded_loop: Configures thread pool with activated event loops for particular tasks
• grok: Parse logs in metrics like Elasticsearch’s Grok parser.
• mtail: Parse logs in metrics using mtail-compatible scripts powered by amtail.
• vrl: Remap and enrich log events with Vector Remap Language (avrl) programs.
• enrichment_table: CSV and MaxMind lookup tables for VRL (get_enrichment_table_record); see vrl
• probe: Prometheus-style blackbox probe modules served at GET /probe; see probe

Detailed information about the configuration file structure is in configuration.

Please refer to the entrypoint context explanation.

Here's an example of a simple handler that can respond to Prometheus:

entrypoint {
    handler prometheus;
    tcp 1111;
}

Please refer to the explanation of system context here.

Below is an example of a simple system context that collects CPU, baseboard, system-wide resources, memory, and network statistics:

system {
    base;
    disk;
    network;
}

Aggregator makes it possible to collect metrics from other sources or software via URL.

The aggregate context section runs periodic checks on resources and gets data, pushing it into the parser to generates metrics.

Directive format:

aggregate {
    <parser> <url> [<options>];
}

Here's a simple example of the aggregate context with blackbox checking of TCP/UDP and other resources, collecting metrics from a file and even a directory containing files, and also collect metrics from the Redis server:

aggregate_period 10s;
aggregate {
    # Blackbox checks
    blackbox tcp://google.com:80 add_label=url:google.com;
    blackbox tls://www.amazon.com:443 add_label=url:www.amazon.com;
    blackbox udp://8.8.8.8:53;
    blackbox http://yandex.ru;
    blackbox https://nova.rambler.ru/search 'env=User-agent:googlebot';
    prometheus_metrics file:///tmp/metrics-nostate.txt;
    blackbox file:///etc/ checksum=murmur3 file_stat=true calc_lines=true;
    redis tcp://localhost:6379/;
}

More information about the aggregate directive can be found in aggregate.

• rsyslog
• PostgreSQL
• MongoDB
• redis
• clickhouse
• zookeeper
• kafka
• memcached
• beanstalkd
• gearmand
• haproxy
• blackbox
• uwsgi
• nats
• riak
• rabbitmq
• eventstore
• Celery flower
• powerdns
• apache httpd
• druid
• couchbase
• couchdb
• mogilefs
• moosefs
• kubernetes
• prometheus_metrics
• json_query
• squid
• bind (nameD)
• gdnsd
• tftp
• unbound
• dnsmasq
• syslog-ng
• elasticsearch
• opentsdb
• openvpn
• opennebula
• openstack
• openclaw
• hadoop
• snmp
• aerospike
• lighttpd
• ipmi
• keepalived
• mysql
• monit
• nginx
• nsd
• ntp
• nvidia-smi
• auditd
• cassandra
• sentinel
• patroni
• pgbouncer
• odyssey
• pgpool
• varnish
• wazuh
• freeradius

It's a directive that specifies the directory for saving metrics between restarts.

persistence {
    directory /var/lib/alligator;
}

The modules context allows loading .so files into memory.

modules {
	postgresql /usr/lib64/libpq.so;
	mysql /usr/lib/libmysqlclient.so;
}

This feature is typically used in parsers or for lang contexts.

The resolver in Alligator provides flexible DNS configuration. It allows using DNS servers other than the OS default and adds DNS resolution metrics. See DNS resolver.

Please refer to the explanation of x509 context.

Alligator checks certificate expiry on the filesystem (x509 context) and on TLS connections (aggregate, entrypoint). Optional CRL and OCSP revocation checks apply to aggregate TLS probes, mTLS entrypoints, and filesystem collectors. Metrics include x509_cert_expire_days, x509_cert_revocation_status, and ocsp_requests_total.

Walkthrough config: misc/examples/ocsp/alligator.conf.

Here is an explanation of query context.

Here is an explanation of namespace context and max_emit.

Lang loads a shared library (.so) to collect metrics (C/C++/Go/Rust).

Actions run commands in response to scheduler triggers or metric behaviour, and can export data to external databases. See action.

The scheduler is a tool that specifies settings to repeatedly run lang and action resources.

Cluster enables multi-node metric synchronization. See cluster.

Puppeteer collects HTTP site load statistics. See puppeteer.

Chromecdp collects browser loading statistics from Chrome or Chromium headless without Node.js or the Puppeteer npm package. Alligator starts Chrome once, connects over the Chrome DevTools Protocol (CDP) via a local WebSocket, and crawls each configured URL in an isolated incognito context on every collection cycle. Metrics are written directly into the alligator metric store with Prometheus-style names (chromecdp_*).

Requirements: a Chrome/Chromium binary with CDP support (for example chromium-browser or chromium-headless on EL7/EL8).

chromecdp {
    executable /usr/bin/chromium-browser;
    port 9222;
    log_level off;
    concurrency 25;
    batch_size 2;
    batch_interval 1s;

    https://example.com {
        timeout        10s;
        ttl            120s;
        console_events true;
        add_label {
            team    sre;
            service web-check;
        }
        metricstransform {
            include ^chromecdp_.*$ match_type regexp label source regex '^https?://([^/]+).*$' replacement '$1';
        }
    }
}

Emitted metrics include page availability, per-resource HTTP status, load duration and size, Chrome performance counters, Resource Timing API timings, and optional console or JavaScript error counters. Module options include concurrency, batch_size, batch_interval, setup_budget, and post_nav_budget for parallel batched crawls. Per-URL options (timeout, ttl, add_label, metricstransform, log_level, screenshot) match the puppeteer context where applicable. Crawl timing follows the global aggregate_period; a new full cycle starts only after the previous one completes.

With log_level off (default), alligator suppresses Chrome’s own stderr noise (D-Bus, GPU, and similar messages). Set log_level info or higher to see Chrome startup diagnostics when debugging.

Full documentation: chromecdp.md. Comparison with puppeteer is described there as well.

Threaded loop enables the thread pools with activated event loops for particular tasks. Here is an explanation.

Enables parsing log entries into metrics using Elasticsearch-style Grok patterns. See the detailed explanation

Enables parsing log entries into metrics with mtail-compatible programs in the C runtime. See the detailed explanation

Enables remapping and enriching log events with Vector Remap Language (avrl) programs. See the detailed explanation