Intro

Pulse is similar to cloudprober, but minus the cloud part. It's a standalone service that you can just run everywhere with minimal config and still get those uptime and latency metrics.

Connecting to a database

By default, pulse uses an embedded storage backed up by sqlite3. That's cool for testing/debugging, but for production-ish use you'd want to connect it to a proper database service such as TimescaleDB or PostgreSQL.

Use the DATABASE_URL environment variable to provide the, well, database url to use.

Make sure the database user has the permission to create tables in the schema 'public'.

Adding probes

Adding a probe is as simple as adding a config file entry:

probes:
  cloudlfare-dns:
    http:
      method: GET
      url: https://1.1.1.1/
      interval: 60
      timeout: 10

Deploying

Using a dockerfile:

from ghcr.io/maddsua/pulse:latest
copy ./pulse.config.yml /pulse.config.yml
cmd ["-config=/pulse.config.yml"]

Use http probes through a proxy

In case you want to monitor a service that sits inside a private network, you can use a socks proxy to forward healthcheck requests.

A sample config would look something like this:

probes:
  my-private-service:
    http:
      url: http://10.10.10.2:80/health
      proxy: my-vpc-proxy

proxies:
  my-vpc-proxy:
    url: socks5://user:[email protected]:1080

Querying the metrics

Get metrics for the last 6 hours using just plain SQL:

select
  time,
  latency,
  label
from series
where time >= now() - '6h'::interval

Basic postgres/timescale query with grafana postgres data source:

select
  time,
  latency,
  label
from series
where $__timeFilter(time)

With interval grouping (should sample data, removing points that are too close):

select
  $__timeGroupAlias(time, $__interval),
  avg(latency),
  label
from series
where $__timeFilter(time)
group by
  time,
  latency,
  label
order by time

There's also an exporter api, that can be enabled with the following config lines:

exporters:
  web:
    enabled: true

This will enable a local http server with a path /exporters/web/ that can be used to query metrics in json format.

See the openapi.yml for more details.

Full config reference

pulse.config.yml:

# defines the list of probe tasks
probes:
  # each probe has to have a unique tag/key/name, whatever you want to call it
  # this key is what you will see in the metrics
  cloudlfare-dns:
    # probe config specifically for the http variant
    http:
      # the http method to use (defaults to HEAD if not set)
      method: GET
      # http request url, required and that's non-negotiable
      url: https://10.10.10.10:443/
      # optional request headers to send;
      # this is particularly useful to status check load balancers and proxies
      headers:
        # here we override the '10.10.10.10:443' request host to a site name that the proxy must serve us
        host: example.com
      # probe interval in seconds, so one minute in this case
      interval: 60
      # probe operation timeout in seconds, if the target doesn't respond in that time - it will be considered to be down
      timeout: 10
      # optional name of the proxy to use
      proxy: my-proxy
      # autorun options;
      # 'true' allows this task to autorun by itself;
      # 'false' prevents it from being run on startup when a global autorun is enabled
      autorun: true|false

# data export API options;
# if no exporters are enabled, pulse won't even start the http server, as it's not needed for anything
exporters:
  # 'web' is just a generic http/rest/whatever API exporter;
  # no other options are supported at the moment
  web:
    enabled: true

# http probe client's proxy configs
proxies:
  # proxy name
  my-proxy:
    # it's url in format socks://[username:password]@hostname:port
    # can be set as an env variable name with a dollar sign prefix or as a plain string
    url: $MY_PROXY_URL

taskhost:
  # enables global task autorun;
  # this will run all the task on startup instead of waiting for their scheduled runs
  autorun: false