Installing and Configuring Prometheus
1. Downloading Prometheus
| Version | Download URL | Notes |
|---|---|---|
| v2.37.0 | prometheus-2.37.0.linux-amd64.tar.gz | Latest stable release for Linux AMD64 |
| v2.37.0 | prometheus-2.37.0.darwin-amd64.tar.gz | Latest stable release for macOS AMD64 |
| v2.37.0 | prometheus-2.37.0.windows-amd64.zip | Latest stable release for Windows AMD64 |
Example: Extracting Prometheus
# For Linux/macOS
tar xvfz prometheus-2.37.0.linux-amd64.tar.gz
cd prometheus-2.37.0.linux-amd64
# For Windows
unzip prometheus-2.37.0.windows-amd64.zip
cd prometheus-2.37.0.windows-amd64Note: Ensure you have sufficient permissions to extract and execute the binaries.
2. Setting Up Configuration File
Example: Basic Prometheus Configuration
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'prometheus'
static_configs:
- targets: ['localhost:9090']
- job_name: 'node'
static_configs:
- targets: ['localhost:9100']
| Field | Description | Default |
|---|---|---|
| global.scrape_interval | How often to scrape targets | 15s |
| global.evaluation_interval | How often to evaluate rules | 15s |
| scrape_configs | List of scrape job configurations | Required |
Note: The configuration file is typically named
prometheus.yml.3. Running Prometheus Server
| Option | Values | Notes |
|---|---|---|
| --config.file | prometheus.yml |
Path to the configuration file |
| --storage.tsdb.path | data/ |
Directory to store the TSDB data |
| --web.listen-address | 127.0.0.1:9090 |
Address to listen on for web interface |
| --web.external-url | |
External URL for web UI links (optional) |
| --storage.tsdb.retention.time | 15d |
How long to retain samples in storage |
Note: Prometheus stores time-series data in a local database called TSDB (Time Series Database). By default, it retains data for 15 days.
Warning: Ensure that the
prometheus.yml file is correctly configured before starting the server, or it will fail to initialize.Example: Running Prometheus with custom retention and storage path
prometheus --config.file=prometheus.yml \
--storage.tsdb.path=/var/lib/prometheus/data \
--storage.tsdb.retention.time=30d
4. Configuring Storage Path
| Configuration Option | Description | Default Value | Notes |
|---|---|---|---|
| storage.tsdb.path | Directory to store the TSDB (Time Series Database) data | data/ |
Must be writable by the Prometheus process |
| storage.tsdb.retention.time | How long to retain samples in the database | 15d |
Can be specified in days (d), hours (h), minutes (m), or seconds (s) |
| storage.tsdb.retention.size | Maximum size of the data directory (in bytes or with unit suffixes like GB, TB) | 0 |
If set to 0, size-based retention is disabled. If both retention.time and retention.size are set, Prometheus uses the one that triggers first |
Example: Configuring Storage Path
global:
scrape_interval: 15s
storage:
tsdb:
path: /prometheus/data
retention:
time: 30d
size: 50GB
Note: Ensure that the configured storage path has sufficient disk space and appropriate permissions for Prometheus to read/write data.
5. Setting Web Listen Address
| Configuration Option | Values | Description |
|---|---|---|
| web.listen-address | "0.0.0.0:9090" |
Address to listen on for web interface and telemetry |
| web.external-url | "" |
External URL to access the Prometheus web UI (used for redirects) |
6. Configuring External URL
| Option | Values | Description |
|---|---|---|
| external_url | http://prometheus.example.com |
External URL to use for all HTTP links generated in web UI and alerts |
Note: The
external_url is used for generating absolute URLs in the web UI and alerts. It should point to the public address where Prometheus is accessible.7. Setting Log Level and Format
| Option | Values | Description |
|---|---|---|
| log.level | debug, info, warn, error |
Sets the minimum level of logs to output. Default is info. |
| log.format | logfmt, json |
Defines the output format of logs. Default is logfmt. |
Example: Configuring Log Level and Format
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'prometheus'
static_configs:
- targets: ['localhost:9090']
# Log configuration
log:
level: debug
format: json
8. Validating Configuration
| Flag | Description | Default |
|---|---|---|
| --config.file | Path to the configuration file | prometheus.yml |
| --dry-run | Run configuration validation without starting Prometheus | false |
Note: The
--dry-run flag ensures that the configuration file is syntactically correct and all required fields are present before starting the Prometheus server.
9. Running as Service
Example: Systemd Service Configuration
# /etc/systemd/system/prometheus.service
[Unit]
Description=Prometheus
After=network.target
[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/usr/local/bin/prometheus \
--config.file /etc/prometheus/prometheus.yml \
--storage.tsdb.path /var/lib/prometheus/ \
--web.listen-address 0.0.0.0:9090
Restart=always
[Install]
WantedBy=multi-user.target
| Option | Values | Notes |
|---|---|---|
| --config.file | prometheus.yml |
Path to the configuration file |
| --storage.tsdb.path | /var/lib/prometheus/ |
Directory to store the TSDB data |
| --web.listen-address | 0.0.0.0:9090 |
Address to listen on for web interface |
Note: Ensure the
prometheus user exists and has appropriate permissions to access the data directory.
Service Setup Steps
- Create the
prometheususer and group - Download and install Prometheus binary
- Create the configuration file
/etc/prometheus/prometheus.yml - Copy the systemd service file to
/etc/systemd/system/prometheus.service - Reload systemd:
systemctl daemon-reload - Enable and start the service:
systemctl enable prometheus && systemctl start prometheus
10. Using Command-Line Help
Prometheus provides comprehensive command-line help to assist users in understanding its various options and flags. The help can be accessed through the --help flag.
| Command | Description | Example |
|---|---|---|
| prometheus --help | Displays all available command-line options and flags for Prometheus. | prometheus --help |
| prometheus --version | Shows the current version of Prometheus installed. | prometheus --version |
Note: The help output includes descriptions for flags such as
--config.file, --storage.tsdb.path, and --web.listen-address, which are essential for configuring Prometheus.
11. Enabling Feature Flags
Note: Feature flags in Prometheus are used to enable experimental or unstable features that are not yet part of the stable release.
| Flag Name | Description | Status | Default Value |
|---|---|---|---|
| enable-feature-flags | Enables the feature flags functionality. | NEW | false |
| enable-query-stats | Enables query statistics collection. | EXPERIMENTAL | false |
| enable-remote-read | Enables remote read functionality. | DEPRECATED | true |
12. Upgrading Prometheus Versions
Note: Ensure you have a backup of your Prometheus data and configuration before upgrading.
| Version | Upgrade Path | Notes |
|---|---|---|
| v2.37.0 | prometheus --config.file=... |
Major version upgrade; requires configuration file review |
| v2.40.0 | prometheus --config.file=... --storage.tsdb.path=... |
New storage path option introduced |
Example: Upgrading Prometheus
# Stop Prometheus service
sudo systemctl stop prometheus
# Backup configuration and data
cp -r /etc/prometheus /etc/prometheus.backup
cp -r /var/lib/prometheus /var/lib/prometheus.backup
# Download new version
wget https://github.com/prometheus/prometheus/releases/download/v2.40.0/prometheus-2.40.0.linux-amd64.tar.gz
# Extract and install
tar xvfz prometheus-2.40.0.linux-amd64.tar.gz
sudo cp prometheus-2.40.0.linux-amd64/prometheus /usr/local/bin/
# Start Prometheus
sudo systemctl start prometheus