https://github.com/messagebird/pushprom
Pushprom is a proxy to the Prometheus Go client.
https://github.com/messagebird/pushprom
Last synced: 5 months ago
JSON representation
Pushprom is a proxy to the Prometheus Go client.
- Host: GitHub
- URL: https://github.com/messagebird/pushprom
- Owner: messagebird
- License: bsd-2-clause
- Created: 2016-06-09T15:29:36.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2022-12-06T11:30:28.000Z (over 3 years ago)
- Last Synced: 2024-11-20T06:34:26.573Z (over 1 year ago)
- Language: Go
- Homepage: https://www.messagebird.com
- Size: 1.73 MB
- Stars: 80
- Watchers: 10
- Forks: 13
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Pushprom
[](https://travis-ci.org/messagebird/pushprom)
Pushprom is a proxy (HTTP/UDP) to the [Prometheus](https://prometheus.io/) Go client.
Prometheus doesn't offer a PHP client and PHP clients are hard to implement because they would need to keep track of state and PHP setups generally don't encourage that. That's why we built Pushprom.
## Dependencies
- [make](https://www.gnu.org/software/make/)
- [golang](https://go.dev/)
- [docker](https://www.docker.com/)
- [github-release](https://cli.github.com/manual/gh_release_create)
## Installing
Execute the following command:
```bash
go get -u github.com/messagebird/pushprom
```
To build amd64/linux binary:
```bash
make release_linux
```
To build os & platform dependent native binary:
```bash
make native
```
To build using Docker container:
```bash
make container
```
## Release
```bash
VERSION=1.0.9 ./release.sh
```
## Usage
Running Pushprom is as easy as executing `pushprom` on the command line.
```
$ pushprom
2016/08/25 10:43:32 http.go:36: exposing metrics on http://0.0.0.0:9091/metrics
2016/08/25 10:43:32 udp.go:10: listening for stats UDP on port :9090
2016/08/25 10:43:32 http.go:39: listening for stats on http://0.0.0.0:9091
```
Use the `-h` flag to get help information.
```
$ pushprom -h
Usage of bin/pushprom:
-http-listen-address string
The address to listen on for http stat and telemetry requests. (default ":9091")
-udp-listen-address string
The address to listen on for udp stats requests. (default ":9090")
```
Pushprom accepts HTTP and UDP requests. The payloads are in JSON. Here is a full example:
```json
{
"type": "gauge",
"name": "trees",
"help": "the amount of trees in the forest.",
"method": "add",
"value": 3002,
"labels": {
"species": "araucaria angustifolia",
"job": "tree-counter-bot"
}
}
```
When Pushprom receives this payload (from now on called Delta) it tries to register the metric with type **Gauge** named **trees** and then apply the operation **add** with value **3002** on it.
## Protocol support
You can use HTTP requests and UDP packages to push deltas to Pushprom.
### HTTP
When using HTTP you should do a `POST /`.
Example:
```bash
curl -H "Content-type: application/json" -X POST -d '{"type": "counter", "name": "gophers", "help": "little burrowing rodents", "method": "inc"}' http://127.0.0.1:9091/
```
### UDP
*You move fast and break things.*
Example:
```bash
echo "{\"type\": \"counter\", \"name\": \"gophers\", \"help\": \"little burrowing rodents\", \"method\": \"inc\"}" | nc -u -w1 127.0.0.1 9090
```
## Caveats
In the Prometheus Go client you can not register a metric with the same **name** and different **help** or **labels**. For example: you register a metric with name `gophers` and with help `little rodents` and a little later you think "but they are also burrowing animals!". When you change the help string and push the same metric it won't work: you need to reboot Pushprom.
## Clients
We currently offer two flavors of PHP clients for Pushprom:
* [PHP](https://github.com/messagebird/pushprom-php-client)
* [Yii 2](https://github.com/messagebird/pushprom-yii2-client)
## Alternatives
### Pushgateway
[Pushgateway](https://github.com/prometheus/pushgateway) is a metrics cache for Prometheus. It's explicitly not an aggregator, which is the most distinct difference with Pushprom.
# Tests
```bash
go test ./...
```
## License
Pushprom is licensed under [The BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause). Copyright (c) 2022, MessageBird