README.md 3.89 KB
Newer Older
1
# Prometheus [![Build Status](https://travis-ci.org/prometheus/prometheus.svg)](https://travis-ci.org/prometheus/prometheus)
Matt T. Proud's avatar
Matt T. Proud committed
2

3
4
5
6
7
8
Prometheus is a systems and service monitoring system. It collects metrics
from configured targets at given intervals, evaluates rule expressions,
displays the results, and can trigger alerts if some condition is observed
to be true.

Prometheus' main distinguishing features as compared to other monitoring systems are:
9
10
11
12
13
14
15
16
17
18

- a **multi-dimensional** data model (timeseries defined by metric name and set of key/value dimensions)
- a **flexible query language** to leverage this dimensionality
- no dependency on distributed storage; **single server nodes are autonomous**
- timeseries collection happens via a **pull model** over HTTP
- **pushing timeseries** is supported via an intermediary gateway
- targets are discovered via **service discovery** or **static configuration**
- multiple modes of **graphing and dashboarding support**
- **federation support** coming soon

19
## Architecture overview
20

21
![](https://cdn.rawgit.com/prometheus/prometheus/62b69b0/documentation/images/architecture.svg)
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
22

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
23
## Install
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
24

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
25
There are various ways of installing Prometheus.
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
26

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
27
### Precompiled packages
28

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
29
We plan to provide precompiled binaries for various platforms and even
juliusv's avatar
juliusv committed
30
packages for common Linux distributions soon. Once those are offered,
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
31
it will be the recommended way of installing Prometheus.
32

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
33
### Use `make`
34

beorn7's avatar
beorn7 committed
35
36
37
38
39
Clone the repository in the usual way with `git clone`. _Do not
download and unpack the source archives provided by GitHub._ (The
makefile depends on running in a git repository. This will be fixed
eventually.)

Joseph Wilk's avatar
typo    
Joseph Wilk committed
40
In most circumstances, the following should work:
41

juliusv's avatar
juliusv committed
42
43
    $ make build
    $ ./prometheus -config.file=documentation/examples/prometheus.conf
44

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
45
46
47
48
The above requires a number of common tools to be installed, namely
`curl`, `git`, `gzip`, `hg` (Mercurial CLI), `sed`, `xxd`. Should you
need to change any of the protocol buffer definition files
(`*.proto`), you also need the protocol buffer compiler
juliusv's avatar
juliusv committed
49
50
[`protoc`](http://code.google.com/p/protobuf/), v2.5.0 or higher,
in your `$PATH`.
51

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
52
53
54
Everything else will be downloaded and installed into a staging
environment in the `.build` sub-directory. That includes a Go
development environment of the appropriate version.
55

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
56
The `Makefile` offers a number of useful targets. Some examples:
57

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
58
* `make test` runs tests.
juliusv's avatar
juliusv committed
59
* `make tarball` creates a tarball with the binary for distribution.
60
* `make race_condition_run` compiles and runs a binary with the race detector enabled. To pass arguments when running Prometheus this way, set the `ARGUMENTS` environment variable (e.g. `ARGUMENTS="-config.file=./prometheus.conf" make race_condition_run`).
61

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
62
### Use your own Go development environment
Matt T. Proud's avatar
Matt T. Proud committed
63

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
64
65
66
Using your own Go development environment with the usual tooling is
possible, too, but you have to take care of various generated files
(usually by running `make` in the respective sub-directory):
67

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
68
69
70
* Compiling the protocol buffer definitions in `config` (only if you have changed them).
* Generating the parser and lexer code in `rules` (only if you have changed `parser.y` or `lexer.l`).
* The `files.go` blob in `web/blob`, which embeds the static web content into the binary.
71

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
72
73
74
75
Furthermore, the build info (see `build_info.go`) will not be
populated if you simply run `go build`. You have to pass in command
line flags as defined in `Makefile.INCLUDE` (see `${BUILDFLAGS}`) to
do that.
76

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
77
## More information
78

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
79
80
  * The source code is periodically indexed: [Prometheus Core](http://godoc.org/github.com/prometheus/prometheus).
  * You will find a Travis CI configuration in `.travis.yml`.
juliusv's avatar
juliusv committed
81
  * All of the core developers are accessible via the [Prometheus Developers Mailinglist](https://groups.google.com/forum/?fromgroups#!forum/prometheus-developers) and the `#prometheus` channel on `irc.freenode.net`.
Matt T. Proud's avatar
Matt T. Proud committed
82

83
84
## Contributing

85
Refer to [CONTRIBUTING.md](CONTRIBUTING.md)
86

87
## License
88

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
89
Apache License 2.0, see [LICENSE](LICENSE).