# The CNCF sandbox for observability visualisation. Already supports Prometheus/Tempo - more data sources to come!


![Perses](https://github.com/perses/perses/raw/main/docs/images/perses_logo_cropped.svg align="center")

## Overview

Perses, a [Cloud Native Computing Foundation](https://cncf.io/) sandbox project, is a dashboard tool to visualize observability data from Prometheus/Thanos/Jaeger.

|  |  |
| --- | --- |

Perses aims to tackle multiple goals:

1. Become a **standard** dashboard visualization tool for Prometheus and other datasources. It will focus on being GitOps-compatible and thus enabling a smooth Dashboard-as-Code workflow, via a new and well-defined dashboard definition model.
    
2. Provide different npm packages, so that anyone that would like to embed charts and dashboards in their own UI could benefit from the work achieved here. For example, these packages might be used in the future to improve the display of the data in the Prometheus UI.
    
3. Offer a Kubernetes-native mode in which dashboard definitions can be deployed into and read from individual application namespaces (using CRDs). For more information you can take a look at [the doc](https://github.com/perses/perses/blob/main/docs/design-docs/kubernetes.md) which would give you an idea of how it would work.
    
4. To be friendly to Dashboard-as-Code users, by providing a complete static validation of the dashboard format. That means you will be able to validate your dashboards in a CI/CD using the Perses CLI (named `percli`)
    
5. Support plugins, to allow users to extend the capacities natively provided.
    

## Try it

We are providing an online demo available at [**https://demo.perses.dev**](https://demo.perses.dev/). You can create your own project(s) and dashboard(s) there, no one else will be able to modify them!

## Status

1. Perses as an application can now **be used**.
    
    * The data model reached a stable point, and we are providing multiple panel types that should cover most of the use cases when using Prometheus.
        
    * Authentication and authorization are available.
        
2. On the GitOps aspect:
    
    * We provide a CLI that helps interacting with the API. A short doc is available [here](https://github.com/perses/perses/blob/main/docs/tooling/cli.md)
        
    * Two SDKs (in Golang and in Cuelang) are available to code dashboards. See [Dashboard-as-Code](https://github.com/perses/perses/blob/main/docs/user-guides/dashboard-as-code.md) guide. Probably these SDKs are going to evolve depending on the feedbacks we might receive. Still it's likely to be about adding more util functions rather than breaking things.
        
3. We are eager to change the current plugin architecture to make it potentially simpler and above all to be able to externalize the load and the implementation of a plugin.
    
    * Changes are more on the frontend side. [cue/schemas](https://github.com/perses/perses/blob/main/cue/schemas) are kept in their current shape as there is no point to remove the static validation of plugins on the backend side.
        
    * *Work is in progress*
        

## What's next

Current Roadmap is available [here](https://github.com/perses/perses/blob/main/ROADMAP.md)

## Install

There are various ways of installing Perses.

### Precompiled binaries

Precompiled binaries for released versions are available in the [GitHub release](https://github.com/perses/perses/releases). Using the latest release binary is the recommended way of installing Perses.

### Docker images

Docker images are available on [Docker Hub](https://hub.docker.com/r/persesdev/perses).

You can launch a Perses container for trying it out with:

```less
docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses
```

### Building from source

To build Perses from source code, You need:

* Go [version 1.18 or greater](https://golang.org/doc/install).
    
* NodeJS [version 18 or greater](https://nodejs.org/).
    
* npm [version 8 or greater](https://www.npmjs.com/).
    

Start by cloning the repository:

```less
git clone https://github.com/perses/perses.git
cd perses
```

Then you can use `make build` that would build the web assets and then Perses itself (and also the Perses CLI that can be used to interact directly with the Perses API in case you prefer to browser the API using a terminal).

```less
make build
./bin/perses --config=your_config.yml
```

## Contributing and development

General instructions about how you can contribute to Perses are available in the document [CONTRIBUTING.md](https://github.com/perses/perses/blob/main/CONTRIBUTING.md).

### UI development

If you are primarily interested in contributing to the UI application and libraries, please refer to the [UI Readme](https://github.com/perses/perses/blob/main/ui/README.md). It includes quick start instructions for how to build, run, and test the React UI. It also includes details about the architecture and [guidelines](https://github.com/perses/perses/blob/main/ui/ui-guidelines.md) for development.