README.md 6.06 KB
Newer Older
Krasimir Georgiev's avatar
Krasimir Georgiev committed
1
# Prometheus
2

Julien Pivotto's avatar
Julien Pivotto committed
3
[![CircleCI](https://circleci.com/gh/prometheus/prometheus/tree/main.svg?style=shield)][circleci]
Steve Durrheimer's avatar
Steve Durrheimer committed
4
5
[![Docker Repository on Quay](https://quay.io/repository/prometheus/prometheus/status)][quay]
[![Docker Pulls](https://img.shields.io/docker/pulls/prom/prometheus.svg?maxAge=604800)][hub]
Tobias Schmidt's avatar
Tobias Schmidt committed
6
[![Go Report Card](https://goreportcard.com/badge/github.com/prometheus/prometheus)](https://goreportcard.com/report/github.com/prometheus/prometheus)
Dmytro Slupytskyi's avatar
Dmytro Slupytskyi committed
7
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/486/badge)](https://bestpractices.coreinfrastructure.org/projects/486)
Sven Efftinge's avatar
Sven Efftinge committed
8
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/prometheus/prometheus)
Julien Pivotto's avatar
Julien Pivotto committed
9
[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/prometheus.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:prometheus)
Matt T. Proud's avatar
Matt T. Proud committed
10

11
12
13
Visit [prometheus.io](https://prometheus.io) for the full documentation,
examples and guides.

14
Prometheus, a [Cloud Native Computing Foundation](https://cncf.io/) project, is a systems and service monitoring system. It collects metrics
15
from configured targets at given intervals, evaluates rule expressions,
Anthony D'Atri's avatar
Anthony D'Atri committed
16
displays the results, and can trigger alerts when specified conditions are observed.
17

Anthony D'Atri's avatar
Anthony D'Atri committed
18
The features that distinguish Prometheus from other metrics and monitoring systems are:
19

Anthony D'Atri's avatar
Anthony D'Atri committed
20
- A **multi-dimensional** data model (time series defined by metric name and set of key/value dimensions)
Julius Volz's avatar
Julius Volz committed
21
- PromQL, a **powerful and flexible query language** to leverage this dimensionality
Anthony D'Atri's avatar
Anthony D'Atri committed
22
23
24
25
26
27
- No dependency on distributed storage; **single server nodes are autonomous**
- An HTTP **pull model** for time series collection
- **Pushing time series** is supported via an intermediary gateway for batch jobs
- Targets are discovered via **service discovery** or **static configuration**
- Multiple modes of **graphing and dashboarding support**
- Support for hierarchical and horizontal **federation**
28

29
## Architecture overview
30

31
![](https://cdn.jsdelivr.net/gh/prometheus/prometheus@c34257d069c630685da35bcef084632ffd5d6209/documentation/images/architecture.svg)
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
32

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
33
## Install
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
34

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
35
There are various ways of installing Prometheus.
Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
36

beorn7's avatar
beorn7 committed
37
### Precompiled binaries
38

beorn7's avatar
beorn7 committed
39
Precompiled binaries for released versions are available in the
40
41
[*download* section](https://prometheus.io/download/)
on [prometheus.io](https://prometheus.io). Using the latest production release binary
Tobias Schmidt's avatar
Tobias Schmidt committed
42
43
is the recommended way of installing Prometheus.
See the [Installing](https://prometheus.io/docs/introduction/install/)
44
chapter in the documentation for all the details.
beorn7's avatar
beorn7 committed
45

46
### Docker images
47

48
Docker images are available on [Quay.io](https://quay.io/repository/prometheus/prometheus) or [Docker Hub](https://hub.docker.com/r/prom/prometheus/).
49

50
51
You can launch a Prometheus container for trying it out with

52
    $ docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus
53
54
55

Prometheus will now be reachable at http://localhost:9090/.

56
### Building from source
57

Anthony D'Atri's avatar
Anthony D'Atri committed
58
To build Prometheus from source code, first ensure that have a working
59
Go environment with [version 1.14 or greater installed](https://golang.org/doc/install).
Anthony D'Atri's avatar
Anthony D'Atri committed
60
You also need [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/)
61
installed in order to build the frontend assets.
beorn7's avatar
beorn7 committed
62

63
You can directly use the `go` tool to download and install the `prometheus`
64
and `promtool` binaries into your `GOPATH`:
65

66
    $ GO111MODULE=on go get github.com/prometheus/prometheus/cmd/...
67
    $ prometheus --config.file=your_config.yml
68

69
70
71
72
73
74
*However*, when using `go get` to build Prometheus, Prometheus will expect to be able to
read its web assets from local filesystem directories under `web/ui/static` and
`web/ui/templates`. In order for these assets to be found, you will have to run Prometheus
from the root of the cloned repository. Note also that these directories do not include the
new experimental React UI unless it has been built explicitly using `make assets` or `make build`.

Julien Pivotto's avatar
Julien Pivotto committed
75
An example of the above configuration file can be found [here.](https://github.com/prometheus/prometheus/blob/main/documentation/examples/prometheus.yml)
76

77
78
You can also clone the repository yourself and build using `make build`, which will compile in
the web assets so that Prometheus can be run from anywhere:
79

80
81
82
83
    $ mkdir -p $GOPATH/src/github.com/prometheus
    $ cd $GOPATH/src/github.com/prometheus
    $ git clone https://github.com/prometheus/prometheus.git
    $ cd prometheus
84
    $ make build
85
    $ ./prometheus --config.file=your_config.yml
86

87
The Makefile provides several targets:
88

89
  * *build*: build the `prometheus` and `promtool` binaries (includes building and compiling in web assets)
90
  * *test*: run the tests
91
  * *test-short*: run the short tests
92
93
  * *format*: format the source code
  * *vet*: check the source code for common errors
94
  * *assets*: build the new experimental React UI
95

96
97
98
99
100
101
102
103
104
105
106
### Building the Docker image

The `make docker` target is designed for use in our CI system.
You can build a docker image locally with the following commands:

    $ make promu
    $ promu crossbuild -p linux/amd64
    $ make common-docker-amd64

*NB* if you are on a Mac, you will need [gnu-tar](https://formulae.brew.sh/formula/gnu-tar).

107
108
## React UI Development

Julien Pivotto's avatar
Julien Pivotto committed
109
For more information on building, running, and developing on the new React-based UI, see the React app's [README.md](web/ui/react-app/README.md).
110

Bjoern Rabenstein's avatar
Bjoern Rabenstein committed
111
## More information
112

113
  * The source code is periodically indexed: [Prometheus Core](https://godoc.org/github.com/prometheus/prometheus).
114
  * You will find a CircleCI configuration in [`.circleci/config.yml`](.circleci/config.yml).
115
  * See the [Community page](https://prometheus.io/community) for how to reach the Prometheus developers and users on various communication channels.
Matt T. Proud's avatar
Matt T. Proud committed
116

117
118
## Contributing

Julien Pivotto's avatar
Julien Pivotto committed
119
Refer to [CONTRIBUTING.md](https://github.com/prometheus/prometheus/blob/main/CONTRIBUTING.md)
120

121
## License
122

Julien Pivotto's avatar
Julien Pivotto committed
123
Apache License 2.0, see [LICENSE](https://github.com/prometheus/prometheus/blob/main/LICENSE).
124
125
126
127


[hub]: https://hub.docker.com/r/prom/prometheus/
[circleci]: https://circleci.com/gh/prometheus/prometheus
Steve Durrheimer's avatar
Steve Durrheimer committed
128
[quay]: https://quay.io/repository/prometheus/prometheus