Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 27 ยท Prometheus Basics

Installing Prometheus and Your First Scrape

Install Prometheus from a binary or Docker, write prometheus.yml with scrape_configs, open the web UI and Targets page, and read the up metric.

Prometheus is one of the easiest big monitoring systems to install: it is a single program with no database server to set up. In this lesson you will download it, write a configuration file that tells it what to scrape, start it, and check in the web UI that it is collecting data. You will use Prometheus to monitor itself, which is a common first step because Prometheus exposes its own metrics.

The commands here are read-only because this page cannot run a server, but they are real and work on Linux, macOS and Windows. Runnable stand-ins at the end show what the configuration file means.

From zero to first scrape

Install Binary or Docker.
Configure Write prometheus.yml.
Start Run it, open port 9090.
Check Targets page and up.
1 / 2

Installing from a release archive

Prometheus publishes ready-built archives for each operating system on its download page. On Linux the steps look like this (use the current version number from the download page in place of X.Y.Z):

Terminal
tar xvfz prometheus-X.Y.Z.linux-amd64.tar.gz
cd prometheus-X.Y.Z.linux-amd64
ls
# prometheus  promtool  prometheus.yml  ...

The archive contains the prometheus server, promtool (a command-line checker used later for validating configs and rules) and an example prometheus.yml. On Windows you unzip the archive and run prometheus.exe instead.

Installing with Docker

If you have Docker, you can skip downloads. The official image is prom/prometheus. This command mounts your own configuration file into the container and publishes port 9090:

Terminal
docker run -d --name prometheus -p 9090:9090 \
  -v "$(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml" \
  prom/prometheus

Data lives inside the container unless you also mount a volume for /prometheus, so for anything beyond a trial, add a volume. A complete Compose setup comes in Project: A Complete Monitoring Stack with Docker Compose.

The configuration file

Prometheus is configured with one YAML file, usually called prometheus.yml. A minimal version that monitors Prometheus itself and one application:

YAML
global:
  scrape_interval: 15s

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

  - job_name: web
    metrics_path: /metrics
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:8080", "localhost:8081"]

The important parts:

  • global holds defaults for all jobs. scrape_interval is how often to scrape. The default is one minute, and 15 seconds is a common choice. evaluation_interval (how often rules run) also lives here.
  • scrape_configs is a list of jobs. A job is a group of targets that share a purpose and settings, such as "all instances of the web service".
  • job_name becomes the job label on every sample from that job.
  • static_configs lists targets by hand as host:port. Each becomes the instance label. (Dynamic lists come with service discovery.)
  • metrics_path defaults to /metrics, so you only set it if your application serves metrics elsewhere. A job can override the global scrape_interval or scrape_timeout.

Indentation matters in YAML, and a typo can stop Prometheus from starting. promtool checks a file before you start it:

Terminal
./promtool check config prometheus.yml

Starting and opening the UI

Terminal
./prometheus --config.file=prometheus.yml

When the log says the server is ready, open http://localhost:9090. The page has an expression box where you can type queries, a Graph tab and a Status menu. Choose Status, then Targets (the page lives at /targets) to see every target, whether it is UP or DOWN, the last scrape time, how long it took and any error text. That page is the first place to look when data is missing.

To reload the configuration without a restart, send the process a SIGHUP signal, or start Prometheus with --web.enable-lifecycle and then POST to /-/reload.

The up metric

Every scrape automatically produces a metric called up: 1 if the scrape succeeded and 0 if it failed. In the expression box, type:

PROMQL
up

You get one series per target, each with job and instance labels, for example up{job="prometheus", instance="localhost:9090"} with value 1. Since localhost:8080 and localhost:8081 are not running yet, their up values would be 0. up is the easiest alert in all of monitoring: "a target has been down for five minutes". Prometheus also records scrape_duration_seconds and scrape_samples_scraped for each scrape, so you can see how heavy a target is.

Try some other queries: prometheus_http_requests_total shows how many HTTP requests the Prometheus server itself has served, and process_resident_memory_bytes shows its memory use. These come from Prometheus's own /metrics endpoint, which you can open in a browser to see the raw text.

What the config means

The stand-in below parses the configuration shown above and "scrapes" every target on a fake network where only two addresses answer. It uses a tiny purpose-built parser that understands only this shape of file (real Prometheus uses a full YAML parser), but the resolution logic is the real idea: per-job settings override the global ones, each target gets a URL and each attempt yields an up value.

Node.js Parse a prometheus.yml and simulate a scrape

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The prometheus job inherited the global 15 s interval, while web overrode it with 5 s. The three targets would produce three up series, and the unreachable localhost:8081 gets up=0, exactly what the Targets page would show as DOWN with a "connection refused" error.

Reading the Targets page

When a target is DOWN, the error text tells you why. The second stand-in turns several typical failures into the status you would see. The messages are paraphrased from the common causes, not Prometheus's exact wording, which varies by version.

Node.js Why is my target DOWN?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Connection refused usually means nothing is listening on that port, or a firewall blocks it. A 404 means the path is wrong, so check metrics_path. A timeout (by default scrapes time out after 10 seconds, adjustable with scrape_timeout, which must not exceed the interval) means the target is too slow or unreachable. If the page is HTML, you are probably pointing at an ordinary web page instead of a metrics endpoint.

What is real and what is the stand-in

The downloads, the Docker command, prometheus.yml, promtool, the Targets page, up and the query box are real. The parsers above are miniature stand-ins that mimic what Prometheus does with the file, not the real configuration loader, and the "network" is a hard-coded set.

Run promtool check config prometheus.yml before every restart or reload. It catches YAML mistakes and unknown fields, and it is easy to add to a deployment pipeline.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of prometheus.yml lists the groups of targets to scrape?

    scrape_configs is a list of jobs, each with its targets and optional settings.
  2. 2. What does up == 0 mean for a target?

    Prometheus records up as 1 for a successful scrape and 0 for a failed one.
  3. 3. Where do you check whether each target is UP and why it may be failing?

    The Targets page lists every target with its health, last scrape time and error message.
  4. 4. What does the job_name setting become in the stored data?

    Prometheus attaches job and instance labels automatically to the samples it scrapes.

Summary

  • Install Prometheus from a release archive or the prom/prometheus Docker image; the UI listens on port 9090.
  • prometheus.yml has a global section and scrape_configs, a list of jobs with static_configs targets.
  • Each job gets a job label and each target an instance label; jobs can override the global interval.
  • The Targets page and the up metric tell you whether scraping works and why it fails.
  • Validate configuration with promtool check config before starting or reloading.

Next: Metrics, Labels and Time Series.