TelopiDocs

Linux, EC2 or bare metal

Any Linux machine or VM, an EC2 instance included. One script installs Alloy as a service and sends the machine's CPU, memory, disks and network.

These are the steps the Connect page shows in the portal, at telopi.com/app, where your values are filled in. Here they are placeholders:

  • <INGEST_URL>: your ingest address, on the portal's home page and on its Connect page.
  • <USERNAME>: the username of an ingest key, on the portal's Ingest keys page, or, if your Grafana takes one ingest login rather than keys, the login's username on Connect. Use one key for each place that sends, so you can replace one without touching the others.
  • <ENVIRONMENT>: a name you choose for this environment, such as production: lower-case letters, digits, ., _ and -. Your dashboards group by it.

Your ingest key's password is never in the code: a step that needs it asks for it when it runs.

1. Install and start Alloy

Run this on the machine, as a user that may use sudo, and paste your ingest key's password when it asks: it is not shown, and it goes in no command, so not in your shell's history. It adds Grafana's package repository (apt on Debian and Ubuntu, dnf or yum on Red Hat, Amazon Linux and Fedora), installs Alloy as the alloy service, writes its configuration to /etc/alloy/config.alloy and the password to /etc/default/alloy, which only root reads, and starts it. Run it again to change the configuration or the password; a newer Alloy's default files never replace yours.

sudo bash -s <<'TELOPI'
set -euo pipefail

# The password, from the terminal: it goes in no command.
read -rsp "Ingest key password: " TELOPI_PASSWORD </dev/tty
echo

# Grafana's package repository, and Alloy from it. bash reads this script
# from stdin, so nothing may read stdin or prompt: an upgrade keeps your
# changed files and puts the package's new defaults beside them.
if command -v apt-get >/dev/null; then
  export DEBIAN_FRONTEND=noninteractive
  apt-get update -q </dev/null
  apt-get install -yq curl gpg </dev/null
  mkdir -p /etc/apt/keyrings
  curl -fsSL https://apt.grafana.com/gpg.key | gpg --dearmor --yes -o /etc/apt/keyrings/grafana.gpg
  echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" > /etc/apt/sources.list.d/grafana.list
  apt-get update -q </dev/null
  apt-get install -yq -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold alloy </dev/null
elif command -v dnf >/dev/null || command -v yum >/dev/null; then
  cat > /etc/yum.repos.d/grafana.repo <<'REPO'
[grafana]
name=grafana
baseurl=https://rpm.grafana.com
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://rpm.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
REPO
  "$(command -v dnf || command -v yum)" install -y alloy </dev/null
else
  echo "This script knows apt, dnf and yum; the guide shows other systems." >&2
  exit 1
fi

# The configuration has no secret; only Alloy reads it.
cat > /etc/alloy/config.alloy <<'ALLOY'
// Machines: CPU, load, memory, disks and network of the machine Alloy runs
// on, through Alloy's unix exporter, sent to your Telopi stack every minute.
// Run one Alloy per machine. The password is your ingest key's, read from
// the environment variable TELOPI_PASSWORD.

prometheus.exporter.unix "machines" {
  // In a container, TELOPI_ROOTFS is where the host's / is mounted, so the
  // disks are the host's; unset, as on a machine itself, it is /.
  rootfs_path = coalesce(sys.env("TELOPI_ROOTFS"), "/")
}

prometheus.scrape "machines" {
  targets         = prometheus.exporter.unix.machines.targets
  scrape_interval = "60s"
  forward_to      = [prometheus.remote_write.machines.receiver]
}

prometheus.remote_write "machines" {
  // The environment's name: the Machines dashboard and its alerts group by it.
  external_labels = {
    cluster = "<ENVIRONMENT>",
  }

  endpoint {
    url = "<INGEST_URL>/mimir/api/v1/push"

    basic_auth {
      username = "<USERNAME>"
      password = sys.env("TELOPI_PASSWORD")
    }
  }
}
ALLOY
chown alloy:alloy /etc/alloy/config.alloy
chmod 600 /etc/alloy/config.alloy

# The password: only root reads the file, and systemd hands it to Alloy.
touch /etc/default/alloy
chmod 600 /etc/default/alloy
cat > /etc/default/alloy <<ENV
CONFIG_FILE="/etc/alloy/config.alloy"
CUSTOM_ARGS=""
RESTART_ON_UPGRADE=true
TELOPI_PASSWORD='$TELOPI_PASSWORD'
ENV
# The rpm package reads /etc/sysconfig/alloy; this has both read this file too.
mkdir -p /etc/systemd/system/alloy.service.d
printf '[Service]\nEnvironmentFile=/etc/default/alloy\n' > /etc/systemd/system/alloy.service.d/telopi.conf

systemctl daemon-reload
systemctl enable alloy
systemctl restart alloy
TELOPI

2. Check that it arrived

Alloy should be active and log no error. Within two minutes Connect in the portal says Receiving data, and the Machines dashboard in your Grafana fills. A 401 in the log is a wrong username or password.

systemctl is-active alloy
sudo journalctl -u alloy --since "5 minutes ago" --no-pager | grep -E "level=error|HTTP status 40[13]" || echo "No errors in the last five minutes."

More

On this page