Skip to content

Latest commit

 

History

History
179 lines (130 loc) · 9.14 KB

README.md

File metadata and controls

179 lines (130 loc) · 9.14 KB
Raw

Prometheus Heartbeat Exporter - lightweight configurable multithreaded smokeping written on Golang

Go Report Card Codecov CircleCI GitHub release (latest by date) PkgGoDev GitHub Contributor Covenant

heartbeat is a lightweight configurable multithreaded Prometheus Heartbeat Exporter that helps you monitor your services with minimal overhead. Built for Prometheus - the popular open-source monitoring and alerting system, it provides essential health metrics about your infrastructure.

Inspired by the principles of smokeping, heartbeat offers robust monitoring capabilities that allow you to measure the latency and availability of your services over time. With features like fast performance, easy setup, and efficient multi-target monitoring, heartbeat makes it simple to track service availability and response times. Perfect for both small deployments and large-scale infrastructures, it seamlessly integrates into your existing Prometheus ecosystem while keeping resource usage low.

Table of Contents

Features

  • Lightweight and efficient Prometheus exporter written in Go
  • Multithreaded architecture for improved performance
  • Configurable via YAML configuration file
  • Graceful shutdown support
  • Prometheus metrics exposure
  • Comprehensive logging options
  • Easy to deploy and configure

Requirements

Golang 1.23+

Installation

Install heartbeat:

go get github.com/obstools/go-prometheus-heartbeat-exporter
go install github.com/obstools/go-prometheus-heartbeat-exporter

Import heartbeat dependency into your code:

package main

import heartbeat "github.com/obstools/go-prometheus-heartbeat-exporter"

Usage

Supported connections

Instances in the heartbeat configuration allow you to monitor various types of connections. Each instance can be configured with specific attributes such as name, connection, url, query, interval, and timeout. The connection attribute specifies the type of connection to be monitored, such as postgres for PostgreSQL, etc.

By providing a query, you can define specific operations to be executed on the database or other infrastructure elements, enabling you to check not only the connection status but also the performance of specific queries. This flexibility allows for comprehensive monitoring of your services and ensures that you can quickly identify and respond to issues as they arise.

Note

Please make sure that your query is idempotent, as it can be executed multiple times during the heartbeat check. If query is not provided, heartbeat will check if connection is established only.

Connection Description Query example
postgres Postgres database heartbeat. CREATE TABLE tmp (id SERIAL PRIMARY KEY); DROP TABLE tmp
redis Redis database heartbeat. Implemented only SET, GET, DEL commands. SET key1 value1; GET key1; DEL key1

Configuring

heartbeat configuration is available as YAML file. You can also use environment variable interpolation in your configuration. This allows you to set sensitive information, such as database URLs or API keys, as environment variables and reference them in your YAML configuration. For example, you can set url: '${DB_URL}' and ensure that the DB_URL environment variable is defined in your environment. Available configuration options are described below.

Note

Please keep in mind that instance name should be unique. Otherwise, heartbeat will fail to start.

Configuration Key Type Description Example
log_to_stdout optional Enables logging to standard output. log_to_stdout: true
log_activity optional Enables logging of heartbeat activity. log_activity: true
port required Specifies Heartbeat Prometheus exporter server port number. port: 8080
metrics_route required Defines the route for Prometheus exporter metrics. metrics_route: '/metrics'
instances required List of instances to monitor. instances: [...]
name required Name of the instance. Should be unique. name: 'postgres_1'
connection required Type of connection to the instance. connection: 'postgres'
url required Connection URL for the instance. url: 'postgres://localhost:5432/heartbeat_test'
query optional Query to execute on the instance. query: 'CREATE TABLE tmp (id SERIAL PRIMARY KEY); DROP TABLE tmp'
interval required Check interval for the instance in seconds. interval: 3
timeout required Check timeout for the instance in seconds. timeout: 2

An example of the configuration file:

# config.yml

---

log_to_stdout: true
log_activity: true
port: 8080
metrics_route: '/metrics'
instances:
  - name: 'postgres_1'
    connection: 'postgres'
    url: 'postgres://localhost:5432/heartbeat_test'
    query: 'CREATE TABLE tmp (id SERIAL PRIMARY KEY); DROP TABLE tmp'
    interval: 3
    timeout: 2
  - name: 'redis_1'
    connection: 'redis'
    url: 'redis://localhost:6379'
    query: 'SET key1 value1; GET key1; DEL key1'
    interval: 3
    timeout: 2

Starting server

You can use heartbeat as binary. Just download the pre-compiled binary from the releases page and copy them to the desired location. For start server run command with path to the configuration file. You can use our bash script for automation this process like in the example below:

curl -sL https://raw.githubusercontent.com/obstools/go-prometheus-heartbeat-exporter/master/script/download.sh | bash
./heartbeat -config=config.yml

Passing environment variables to the `heartbeat:

SOME_ENV_VAR=123 ./heartbeat -config=config.yml

Available command line arguments

Flag description Example of usage
-config - path to the configuration file -config=config.yml
-v - Prints current heartbeat binary build data. Doesn't run the server. -v

Stopping server

heartbeat accepts 3 shutdown signals: SIGINT, SIGQUIT, SIGTERM.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/obstools/go-prometheus-heartbeat-exporter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. Please check the open tickets. Be sure to follow Contributor Code of Conduct below and our Contributing Guidelines.

License

This golang package is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the heartbeat project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Credits

Versioning

heartbeat uses Semantic Versioning 2.0.0