Skip to content

D
docs
Commit 34e6a4a2 authored by Tobias Schmidt's avatar Tobias Schmidt
Browse files
Options

Start extracting Prometheus server specific documentation 

This commit is a first in a series to extract all Prometheus server
specific documentation pages and load them from the prometheus
repository instead.
parent bd570947
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 14 additions and 1545 deletions
content/docs/introduction/getting_started.md deleted 100644 → 0
View file @ bd570947
---
title: Getting started
sort_rank: 3
---
# Getting started
This guide is a "Hello World"-style tutorial which shows how to install,
configure, and use Prometheus in a simple example setup. You will download and run
Prometheus locally, configure it to scrape itself and an example application,
and then work with queries, rules, and graphs to make use of the collected time
series data.
## Downloading and running Prometheus
[Download the latest release](/download) of Prometheus for your platform, then
extract and run it:
```language-bash
tar xvfz prometheus-*.tar.gz
cd prometheus-*
```
Before starting Prometheus, let's configure it.
## Configuring Prometheus to monitor itself
Prometheus collects metrics from monitored targets by scraping metrics HTTP
endpoints on these targets. Since Prometheus also exposes data in the same
manner about itself, it can also scrape and monitor its own health.
While a Prometheus server that collects only data about itself is not very
useful in practice, it is a good starting example. Save the following basic
Prometheus configuration as a file named `prometheus.yml`:
```language-yaml
global:
scrape_interval: 15s # By default, scrape targets every 15 seconds.
# Attach these labels to any time series or alerts when communicating with
# external systems (federation, remote storage, Alertmanager).
external_labels:
monitor: 'codelab-monitor'
# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
# The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
- job_name: 'prometheus'
# Override the global default and scrape targets from this job every 5 seconds.
scrape_interval: 5s
static_configs:
- targets: ['localhost:9090']
```
For a complete specification of configuration options, see the
[configuration documentation](/docs/operating/configuration).
## Starting Prometheus
To start Prometheus with your newly created configuration file, change to the directory containing the Prometheus binary and run:
```language-bash
# Start Prometheus.
# By default, Prometheus stores its database in ./data (flag -storage.local.path).
./prometheus -config.file=prometheus.yml
```
Prometheus should start up. You should also be able to browse to a status page about itself at http://localhost:9090. Give it a couple of seconds to collect data about itself from its own HTTP metrics endpoint.
You can also verify that Prometheus is serving metrics about itself by
navigating to its metrics endpoint: http://localhost:9090/metrics
The number of OS threads executed by Prometheus is controlled by the
`GOMAXPROCS` environment variable. As of Go 1.5 the default value is
the number of cores available.
Blindly setting `GOMAXPROCS` to a high value can be counterproductive. See the relevant [Go FAQs](http://golang.org/doc/faq#Why_no_multi_CPU).
Prometheus by default uses around 3GB in memory. If you have a
smaller machine, you can tune Prometheus to use less memory. For details,
see the [memory usage documentation](/docs/operating/storage/#memory-usage).
## Using the expression browser
Let us try looking at some data that Prometheus has collected about itself. To
use Prometheus's built-in expression browser, navigate to
http://localhost:9090/graph and choose the "Console" view within the "Graph"
tab.
As you can gather from http://localhost:9090/metrics, one metric that
Prometheus exports about itself is called
`prometheus_target_interval_length_seconds` (the actual amount of time between
target scrapes). Go ahead and enter this into the expression console:
```
prometheus_target_interval_length_seconds
```
This should return a number of different time series (along with the latest value
recorded for each), all with the metric name
`prometheus_target_interval_length_seconds`, but with different labels. These
labels designate different latency percentiles and target group intervals.
If we were only interested in the 99th percentile latencies, we could use this
query to retrieve that information:
```
prometheus_target_interval_length_seconds{quantile="0.99"}
```
To count the number of returned time series, you could write:
```
count(prometheus_target_interval_length_seconds)
```
For more about the expression language, see the
[expression language documentation](/docs/querying/basics/).
## Using the graphing interface
To graph expressions, navigate to http://localhost:9090/graph and use the "Graph"
tab.
For example, enter the following expression to graph the per-second rate of all
storage chunk operations happening in the self-scraped Prometheus:
```
rate(prometheus_local_storage_chunk_ops_total[1m])
```
Experiment with the graph range parameters and other settings.
## Starting up some sample targets
Let us make this more interesting and start some example targets for Prometheus
to scrape.
The Go client library includes an example which exports fictional RPC latencies
for three services with different latency distributions.
Ensure you have the [Go compiler installed](https://golang.org/doc/install) and
have a [working Go build environment](https://golang.org/doc/code.html) (with
correct `GOPATH`) set up.
Download the Go client library for Prometheus and run three of these example
processes:
```language-bash
# Fetch the client library code and compile example.
git clone https://github.com/prometheus/client_golang.git
cd client_golang/examples/random
go get -d
go build
# Start 3 example targets in separate terminals:
./random -listen-address=:8080
./random -listen-address=:8081
./random -listen-address=:8082
```
You should now have example targets listening on http://localhost:8080/metrics,
http://localhost:8081/metrics, and http://localhost:8082/metrics.
## Configuring Prometheus to monitor the sample targets
Now we will configure Prometheus to scrape these new targets. Let's group all
three endpoints into one job called `example-random`. However, imagine that the
first two endpoints are production targets, while the third one represents a
canary instance. To model this in Prometheus, we can add several groups of
endpoints to a single job, adding extra labels to each group of targets. In
this example, we will add the `group="production"` label to the first group of
targets, while adding `group="canary"` to the second.
To achieve this, add the following job definition to the `scrape_configs`
section in your `prometheus.yml` and restart your Prometheus instance:
```
scrape_configs:
- job_name: 'example-random'
# Override the global default and scrape targets from this job every 5 seconds.
scrape_interval: 5s
static_configs:
- targets: ['localhost:8080', 'localhost:8081']
labels:
group: 'production'
- targets: ['localhost:8082']
labels:
group: 'canary'
```
Go to the expression browser and verify that Prometheus now has information
about time series that these example endpoints expose, such as the
`rpc_durations_seconds` metric.
## Configure rules for aggregating scraped data into new time series
Though not a problem in our example, queries that aggregate over thousands of
time series can get slow when computed ad-hoc. To make this more efficient,
Prometheus allows you to prerecord expressions into completely new persisted
time series via configured recording rules. Let's say we are interested in
recording the per-second rate of example RPCs
(`rpc_durations_seconds_count`) averaged over all instances (but
preserving the `job` and `service` dimensions) as measured over a window of 5
minutes. We could write this as:
```
avg(rate(rpc_durations_seconds_count[5m])) by (job, service)
```
Try graphing this expression.
To record the time series resulting from this expression into a new metric
called `job_service:rpc_durations_seconds_count:avg_rate5m`, create a file
with the following recording rule and save it as `prometheus.rules`:
```
job_service:rpc_durations_seconds_count:avg_rate5m = avg(rate(rpc_durations_seconds_count[5m])) by (job, service)
```
To make Prometheus pick up this new rule, add a `rule_files` statement to the
`global` configuration section in your `prometheus.yml`. The config should now
look like this:
```language-yaml
global:
scrape_interval: 15s # By default, scrape targets every 15 seconds.
evaluation_interval: 15s # Evaluate rules every 15 seconds.
# Attach these extra labels to all timeseries collected by this Prometheus instance.
external_labels:
monitor: 'codelab-monitor'
rule_files:
- 'prometheus.rules'
scrape_configs:
- job_name: 'prometheus'
# Override the global default and scrape targets from this job every 5 seconds.
scrape_interval: 5s
static_configs:
- targets: ['localhost:9090']
- job_name: 'example-random'
# Override the global default and scrape targets from this job every 5 seconds.
scrape_interval: 5s
static_configs:
- targets: ['localhost:8080', 'localhost:8081']
labels:
group: 'production'
- targets: ['localhost:8082']
labels:
group: 'canary'
```
Restart Prometheus with the new configuration and verify that a new time series
with the metric name `job_service:rpc_durations_seconds_count:avg_rate5m`
is now available by querying it through the expression browser or graphing it.
content/docs/introduction/install.md deleted 100644 → 0
View file @ bd570947
---
title: Installing
sort_rank: 2
---
# Installing
## Using pre-compiled binaries
We provide precompiled binaries for most official Prometheus components.
Check out the [download section](/download) for a list of all available
versions.
## From source
For building Prometheus components from source, see the `Makefile` targets in
the respective repository.
NOTE: **Note:** The documentation on this website refers to the latest stable
release (excluding pre-releases). The branch
[next-release](https://github.com/prometheus/docs/compare/next-release) refers
to unreleased changes that are in master branches of source repos.
## Using Docker
All Prometheus services are available as Docker images under the
[prom](https://hub.docker.com/u/prom/) organization.
Running Prometheus on Docker is as simple as `docker run -p 9090:9090
prom/prometheus`. This starts Prometheus with a sample configuration and
exposes it on port 9090.
The Prometheus image uses a volume to store the actual metrics. For
production deployments it is highly recommended to use the
[Data Volume Container](https://docs.docker.com/engine/admin/volumes/volumes/)
pattern to ease managing the data on Prometheus upgrades.
To provide your own configuration, there are several options. Here are
two examples.
### Volumes & bind-mount
Bind-mount your `prometheus.yml` from the host by running:
```
docker run -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml \
prom/prometheus
```
Or use an additional volume for the config:
```
docker run -p 9090:9090 -v /prometheus-data \
prom/prometheus -config.file=/prometheus-data/prometheus.yml
```
### Custom image
To avoid managing a file on the host and bind-mount it, the
configuration can be baked into the image. This works well if the
configuration itself is rather static and the same across all
environments.
For this, create a new directory with a Prometheus configuration and a
`Dockerfile` like this:
```
FROM prom/prometheus
ADD prometheus.yml /etc/prometheus/
```
Now build and run it:
```
docker build -t my-prometheus .
docker run -p 9090:9090 my-prometheus
```
A more advanced option is to render the configuration dynamically on start
with some tooling or even have a daemon update it periodically.
## Using configuration management systems
If you prefer using configuration management systems you might be interested in
the following third-party contributions:
### Ansible
* [griggheo/ansible-prometheus](https://github.com/griggheo/ansible-prometheus)
* [William-Yeh/ansible-prometheus](https://github.com/William-Yeh/ansible-prometheus)
### Chef
* [rayrod2030/chef-prometheus](https://github.com/rayrod2030/chef-prometheus)
### Puppet
* [puppet/prometheus](https://forge.puppet.com/puppet/prometheus)
### SaltStack
* [bechtoldt/saltstack-prometheus-formula](https://github.com/bechtoldt/saltstack-prometheus-formula)
content/docs/operating/configuration.md deleted 100644 → 0
View file @ bd570947
This diff is collapsed.
content/docs/prometheus/index.md 0 → 100644
View file @ 34e6a4a2
---
title: Prometheus
sort_rank: 3
nav_icon: server
---
content/download.html
View file @ 34e6a4a2
......@@ -24,10 +24,6 @@ title: Download
exporters listed at <a href="/docs/instrumenting/exporters/">Exporters
and integrations</a>.
</p>
<p>
After downloading a binary release suitable for your system, please follow
the <a href="/docs/introduction/getting_started/">installation instructions</a>.
</p>
<div class="panel panel-default download-selection">
<div class="panel-body">
......
content/index.html
View file @ 34e6a4a2
......@@ -6,7 +6,7 @@ layout: jumbotron
<h1>From metrics to insight</h1>
<p class="subtitle">Power your metrics and alerting with a leading<br>open-source monitoring solution.</p>
<p>
<a class="btn btn-default btn-lg" href="/docs/introduction/getting_started/" role="button">Get Started</a>
<a class="btn btn-default btn-lg" href="/docs/prometheus/1.8/getting_started/" role="button">Get Started</a>
<a class="btn btn-default btn-lg" href="/download" role="button">Download</a>
</p>
</div>
......@@ -46,7 +46,7 @@ layout: jumbotron
<div class="row">
<div class="col-md-3 col-sm-6 col-xs-12 feature-item">
<a href="/docs/operating/configuration/">
<a href="/docs/prometheus/1.8/configuration/">
<h2><i class="fa fa-cog"></i> Simple operation</h2>
<p>Each server is independent for reliability, relying only on local storage. Written in Go, all binaries are statically linked and easy to deploy.</p>
</a>
......
nanoc.yaml
View file @ 34e6a4a2
......@@ -61,6 +61,13 @@ data_sources:
# The encoding to use for input files. If your input files are not in
# UTF-8 (which they should be!), change this.
encoding: utf-8
-
type: repo_docs
items_root: /docs/prometheus/latest/
config:
name: '1.8'
repository: https://github.com/prometheus/prometheus.git
refspec: docs
-
type: static
items_root: /assets/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Technounit-GROUP 2023