 |
| Getting started with Perses |
Back in December of 2022 I started a series taking you on a tour of the Perses project. These articles covered this fairly new open dashboard and visualization project targeting cloud native environments. I used a getting started workshop to guide you through this series and to provide a hands-on experience for those new to visualizing observability data.
In the previous article I kicked off with an introduction to and installation of Perses and provided links to the actual online workshop content.
In this article, I'll share a guided tour of the Perses application programming interface (API) and how you can interact with your Perses instance through its API.
Let's dive right in, shall we?
I'm going to preview the Perses API as covered in my workshop lab before diving into the actual hands-on with the project.
You can find the free workshop here online:
Now let's dive into the Perses project API lab. Note this article is only a short summary, so please see the complete lab found online as the lab 3 here to work through the API experience yourself:
The following is a short overview of what is in this specific lab of the Perses workshop.
Perses API
One of the most interesting aspects of any project for developers is the amount and ease of access that a project API provides. Rest assured, everything you ever might want to do with your Perses instance is covered, allowing you to perform operations on your resources. You'll see that a resource is part of the Perses dashboard specification and you can perform all of the following with your resources known as CRUD (create, read, update, delete):
- creating a resource
- retrieving a resource
- updating a resource
- deleting a resource
- retrieving a list of resources
After installing Perses in the previous lab, you have a dashboard open in your browser. There is an application programming interface (API) available for you to gain insights into the configuration applied to your Perses instance. You can find out more about the projects, dashboards, and data sources that have been created. This can be handy to start with existing resources and modify them for your own versions.
The pre-installed project is called WorkshopProject and this is how we get started exploring some of the provided API operations for handling a Perses resource, which can be one of the following:
- project
- dashboard
- datasource
You learn that you can use a standard browser and the RestAPI (URL) to leverage the API operations, such as how you can view the configured projects on your Perses server with a browser, just enter this URL:
http://localhost:8080/api/v1/projects
This shows you un-formatted JSON output of the available projects. You should see the single WorkshopProject listed:
Next you explore an example RestAPI tool and query the same operation:
Seeing the results now embedded and formatted nicely for human consumption:
Finally, you'll start using the provided Perses command line executable known as percli. If you built the project from the source code, you have built this executable, but if you are using the container image installation then you will find an executable percli for your operating system using the pointers provided in the lab. The rest of this lab is dedicated to exploring how to use this command line tool and you explore all of the following commands:
- login - log in to an instance of the Perses API
- get - request a response from the Perses API
- project - select a project to be used as default
- describe - request details for a specific resource
- delete - delete a specific resource
- apply - create or update existing resources using JSON or YAML file
You'll learn by using each one of these commands and exploring the output they provide. For example, if you use the command line tool to get all the projects in your Perses instance it would look like this in your console:
More to come
Next up, I'll continue working with you through the Perses project with a look at the Perses specification. Stay tuned for more insights into real practical experience as my cloud native o11y journey continues.