Comprehensive Prometheus Installation Guide

Introduction

Prometheus is an open-source monitoring and alerting toolkit designed for reliability and scalability. This guide will walk you through installing the latest version of Prometheus on various platforms.

Official Documentation: Prometheus Overview

---

Prerequisites

Before installing Prometheus, ensure you have:

• A Linux, macOS, or Windows system
• Root or sudo access (for Linux/macOS)
• At least 2GB of RAM
• 20GB of free disk space
• Basic knowledge of command-line operations

---

Installation Methods

There are several ways to install Prometheus:

1. Binary Installation – Direct download and execution
2. Docker Installation – Containerized deployment
3. Package Manager – Using apt, yum, or brew
4. From Source – Building from the GitHub repository

---

Binary Installation

Step 1: Download the Latest Version

Visit the official Prometheus downloads page to get the latest version.

For Linux (amd64):

# Check the latest version at the download page
VERSION="2.49.1"  # Update this to the latest version
cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v${VERSION}/prometheus-${VERSION}.linux-amd64.tar.gz

For macOS (amd64):

VERSION="2.49.1"  # Update this to the latest version
cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v${VERSION}/prometheus-${VERSION}.darwin-amd64.tar.gz

For macOS (arm64/M1/M2):

VERSION="2.49.1"  # Update this to the latest version
cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v${VERSION}/prometheus-${VERSION}.darwin-arm64.tar.gz

Step 2: Extract the Archive

# For Linux
tar xvfz prometheus-${VERSION}.linux-amd64.tar.gz
cd prometheus-${VERSION}.linux-amd64

# For macOS (amd64)
tar xvfz prometheus-${VERSION}.darwin-amd64.tar.gz
cd prometheus-${VERSION}.darwin-amd64

# For macOS (arm64)
tar xvfz prometheus-${VERSION}.darwin-arm64.tar.gz
cd prometheus-${VERSION}.darwin-arm64

Step 3: Create Prometheus User and Directories (Linux)

# Create prometheus user
sudo useradd --no-create-home --shell /bin/false prometheus

# Create directories
sudo mkdir -p /etc/prometheus
sudo mkdir -p /var/lib/prometheus

# Set ownership
sudo chown prometheus:prometheus /etc/prometheus
sudo chown prometheus:prometheus /var/lib/prometheus

Step 4: Copy Binaries and Configuration Files

# Copy binaries
sudo cp prometheus /usr/local/bin/
sudo cp promtool /usr/local/bin/

# Set ownership for binaries
sudo chown prometheus:prometheus /usr/local/bin/prometheus
sudo chown prometheus:prometheus /usr/local/bin/promtool

# Copy configuration files
sudo cp -r consoles /etc/prometheus
sudo cp -r console_libraries /etc/prometheus
sudo cp prometheus.yml /etc/prometheus/prometheus.yml

# Set ownership for configuration
sudo chown -R prometheus:prometheus /etc/prometheus

Step 5: Create Systemd Service (Linux)

Create a systemd service file for Prometheus:

sudo nano /etc/systemd/system/prometheus.service

Add the following content:

[Unit]
Description=Prometheus
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
    --config.file=/etc/prometheus/prometheus.yml \
    --storage.tsdb.path=/var/lib/prometheus/ \
    --web.console.templates=/etc/prometheus/consoles \
    --web.console.libraries=/etc/prometheus/console_libraries

[Install]
WantedBy=multi-user.target

Save and exit (Ctrl+X, then Y, then Enter).

Step 6: Start Prometheus Service

# Reload systemd
sudo systemctl daemon-reload

# Start Prometheus
sudo systemctl start prometheus

# Enable Prometheus to start on boot
sudo systemctl enable prometheus

# Check status
sudo systemctl status prometheus

---

Docker Installation

Step 1: Install Docker

If you don’t have Docker installed, follow the official Docker installation guide.

Step 2: Create Configuration File

Create a directory for Prometheus configuration:

mkdir -p ~/prometheus
cd ~/prometheus

Create a prometheus.yml file:

nano prometheus.yml

Add the following basic configuration:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

Step 3: Run Prometheus Container

docker run -d \
  --name prometheus \
  -p 9090:9090 \
  -v ~/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
  -v prometheus-data:/prometheus \
  prom/prometheus:latest \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/prometheus

Step 4: Verify Container is Running

docker ps | grep prometheus
docker logs prometheus

---

Configuration

Basic Configuration File Structure

The main configuration file is prometheus.yml. Here’s a detailed example:

# Global configuration
global:
  scrape_interval: 15s        # How often to scrape targets
  evaluation_interval: 15s    # How often to evaluate rules
  external_labels:
    monitor: 'prometheus-monitor'

# Alertmanager configuration (optional)
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - 'localhost:9093'

# Load rules once and periodically evaluate them
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

# Scrape configurations
scrape_configs:
  # Prometheus itself
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
  
  # Node exporter (for system metrics)
  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']

Configuration Best Practices

1. Use descriptive job names – Make it clear what each job monitors
2. Set appropriate scrape intervals – Balance between freshness and load
3. Use labels effectively – Add metadata for easier querying
4. Validate configuration before reloading

Validate Configuration

Before applying changes, validate your configuration:

# Binary installation
promtool check config /etc/prometheus/prometheus.yml

# Docker installation
docker exec prometheus promtool check config /etc/prometheus/prometheus.yml

---

Running Prometheus

Binary Installation

# Start Prometheus
sudo systemctl start prometheus

# Stop Prometheus
sudo systemctl stop prometheus

# Restart Prometheus
sudo systemctl restart prometheus

# Reload configuration (without restart)
sudo systemctl reload prometheus

# View logs
sudo journalctl -u prometheus -f

Docker Installation

# Start container
docker start prometheus

# Stop container
docker stop prometheus

# Restart container
docker restart prometheus

# Reload configuration
docker exec prometheus kill -HUP 1

# View logs
docker logs -f prometheus

macOS (Manual Start)

# Start Prometheus in the foreground
./prometheus --config.file=prometheus.yml

# Start in the background
nohup ./prometheus --config.file=prometheus.yml > prometheus.log 2>&1 &

---

Verification

Access the Web UI

Open your web browser and navigate to:

http://localhost:9090

You should see the Prometheus web interface.

Check Targets

1. Go to Status > Targets in the web UI
2. Verify that the Prometheus target shows as “UP”
3. Check the “Last Scrape” time to ensure data is being collected

Run a Test Query

In the Prometheus web UI:

1. Go to the Graph tab
2. Enter the query: up
3. Click Execute
4. You should see a result showing up{job="prometheus"} 1

Verify with Command Line

# Check if Prometheus is listening
curl http://localhost:9090/metrics

# Query the API
curl 'http://localhost:9090/api/v1/query?query=up'

---

Basic Monitoring Setup

Install Node Exporter

Node Exporter provides system-level metrics. Download from the official Node Exporter page.

Linux Installation

# Download Node Exporter
VERSION="1.7.0"  # Check for latest version
wget https://github.com/prometheus/node_exporter/releases/download/v${VERSION}/node_exporter-${VERSION}.linux-amd64.tar.gz

# Extract
tar xvfz node_exporter-${VERSION}.linux-amd64.tar.gz
cd node_exporter-${VERSION}.linux-amd64

# Copy binary
sudo cp node_exporter /usr/local/bin/
sudo chown prometheus:prometheus /usr/local/bin/node_exporter

# Create systemd service
sudo nano /etc/systemd/system/node_exporter.service

Add the following content:

[Unit]
Description=Node Exporter
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/node_exporter

[Install]
WantedBy=multi-user.target

Start Node Exporter:

sudo systemctl daemon-reload
sudo systemctl start node_exporter
sudo systemctl enable node_exporter
sudo systemctl status node_exporter

Docker Installation

docker run -d \
  --name node-exporter \
  --net="host" \
  --pid="host" \
  -v "/:/host:ro,rslave" \
  prom/node-exporter:latest \
  --path.rootfs=/host

Update Prometheus Configuration

Edit your prometheus.yml to add Node Exporter:

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
  
  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']

Reload Prometheus:

# Binary installation
sudo systemctl reload prometheus

# Docker installation
docker exec prometheus kill -HUP 1

Verify Node Exporter

1. Check targets in the Prometheus UI: http://localhost:9090/targets
2. Run a query: node_cpu_seconds_total

---

Troubleshooting

Common Issues and Solutions

Issue 1: Prometheus Won’t Start

Check logs:

# Binary installation
sudo journalctl -u prometheus -n 50

# Docker installation
docker logs prometheus

Common causes:

• Configuration syntax errors – Run promtool check config
• Port 9090 already in use – Check with netstat -tulpn | grep 9090
• Permission issues – Verify file ownership

Issue 2: Targets Show as “Down”

Verify target is accessible:

curl http://localhost:9100/metrics

Check firewall rules:

# Linux
sudo ufw status
sudo firewall-cmd --list-all

# Allow port if needed
sudo ufw allow 9100

Issue 3: High Memory Usage

Adjust retention settings in the Prometheus startup command:

--storage.tsdb.retention.time=15d
--storage.tsdb.retention.size=50GB

Issue 4: Configuration Changes Not Applied

Reload configuration:

# Binary installation
sudo systemctl reload prometheus

# Docker installation
docker exec prometheus kill -HUP 1

# Or restart the service
sudo systemctl restart prometheus

Issue 5: Cannot Access Web UI

Check if Prometheus is running:

# Binary installation
sudo systemctl status prometheus

# Docker installation
docker ps | grep prometheus

Verify port binding:

netstat -tulpn | grep 9090

Check firewall:

sudo ufw allow 9090

---

Additional Resources

• Official Documentation
• Best Practices
• Query Examples
• Exporters List
• GitHub Repository
• Community Forum

---

Next Steps

After successfully installing Prometheus, consider:

1. Setting up Grafana for better visualization
2. Configuring Alertmanager for alerts
3. Adding more exporters for comprehensive monitoring
4. Implementing service discovery for dynamic environments
5. Setting up recording rules for performance optimization

---

Conclusion

You now have Prometheus installed and running! This powerful monitoring system will help you track metrics, set up alerts, and maintain visibility into your infrastructure. Remember to regularly check for updates and follow security best practices.

For questions or issues, refer to the official documentation or community forums linked above.

Happy Monitoring! 📊