https://github.com/periskop-dev/periskop
Exception Monitoring Service
https://github.com/periskop-dev/periskop
error-monitoring error-reporting errors exceptions monitoring
Last synced: 8 days ago
JSON representation
Exception Monitoring Service
- Host: GitHub
- URL: https://github.com/periskop-dev/periskop
- Owner: periskop-dev
- License: apache-2.0
- Created: 2019-07-23T09:34:02.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-15T05:21:01.000Z (about 2 years ago)
- Last Synced: 2024-11-19T08:47:21.278Z (6 months ago)
- Topics: error-monitoring, error-reporting, errors, exceptions, monitoring
- Language: Go
- Homepage:
- Size: 3.08 MB
- Stars: 185
- Watchers: 62
- Forks: 15
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Authors: AUTHORS
Awesome Lists containing this project
README
# 
[](https://cirrus-ci.com/github/periskop-dev/periskop)
[](https://gitter.im/soundcloud/periskop)
Pull based, language agnostic exception aggregator for microservice environments.
Periskop scales well with the number of exceptions and application instances:
- Exceptions are pre-aggregated in client libraries and stored efficiently in memory, while keeping a sample of concrete occurrences for inspection.
- Exceptions are scraped and aggregated across instances by the server component.
- More application instances result in longer refresh cycles but the memory usage remains constant.
A UI component is provided for convenience.
## Scraping
Errors are scraped and aggregated using a configured endpoint from each of the instances discovered via service discovery.
Periskop supports all service discovery mechanisms supported by Prometheus. The configuration format for service discovery
mirrors the one from Prometheus. See [Prometheus's official documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/)
for reference.
A full example of service configuration for Periskop can be found in the [sample configuration](config.dev.yaml).
## Format
The format for scraped errors is defined in [a proto3 IDL](representation/errors.proto). Currently the only supported protocol is snake_cased JSON over HTTP ([example](scraper/sample-response1.json)).
## UI
The UI allows navigating and inspecting exceptions as they occur.
## Run project locally
Please see [CONTRIBUTING.md](CONTRIBUTING.md)
## Building & Running
We are looking into distributing Periskop via Docker Hub.
In the meantime, you can build and run Periskop from source:
```
docker build --tag periskop .
docker run -v path/to/config.yaml:/etc/periskop/periskop.yaml -p 8080:8080 periskop
```
## Enable persistance storage
By default Periskop stores all the scrapped errors in memory [repository](repository/memory.go). You can configure your Periskop deployment to use persistent storage.
Currently the supported persistance storages are SQLite, MySQL and PostgreSQL.
For SQLite, add these lines to your `config.yaml` file:
```yaml
repository:
type: sqlite
path: periskop.db
```
For MySQL:
```yaml
repository:
type: mysql
dsn: user:pass@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local
```
For PostgreSQL:
```yaml
repository:
type: postgres
dsn: host=localhost user=gorm password=gorm dbname=gorm port=9920 sslmode=disable
```
## Alert reported exceptions
All reported errors are instrumented with [Prometheus](https://prometheus.io) which provides alerting capabilities using [Alertmanager](https://prometheus.io/docs/alerting/alertmanager/). You can configure an alert when you reach some threshold of errors. Here's an example:
```yaml
groups:
- name: periskop
rules:
- alert: TooManyErrors
expr: periskop_error_occurrences{severity="error"} > 1000
for: 5m
labels:
severity: critical
annotations:
summary: "Too many errors on {{ $labels.service_name }}"
description: "Errors for {{ $labels.service_name }}({{ $labels.aggregation_key }}) is {{ $value }}"
dashboard: "https://periskop.example.com/#/{{ $labels.service_name }}/errors/{{ $labels.aggregation_key }}"
```
## Pushgateway
See [periskop-pushgateway](https://github.com/periskop-dev/periskop-pushgateway) if you want to use Periskop as push based metric system.
## Client Libraries
- [periskop-scala](https://github.com/periskop-dev/periskop-scala)
- [periskop-go](https://github.com/periskop-dev/periskop-go)
- [periskop-python](https://github.com/periskop-dev/periskop-python)
- [periskop-ruby](https://github.com/periskop-dev/periskop-ruby)
## Integrations
- [Backstage plugin](https://github.com/backstage/backstage/blob/master/plugins/periskop)
