periskop

Periskop is a pull-based, language agnostic exception aggregator for microservice environments.

Periskop aggregated errors

The Periskop Backstage Plugin exposes a component named EntityPeriskopErrorsCard. Each of the entries in the table will direct you to the error details in your deployed Periskop instance location.

Setup

Configure the periskop backend plugin
Install the plugin by running:

# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-periskop

Add to the app EntityPage component:

// In packages/app/src/components/catalog/EntityPage.tsx
import { EntityPeriskopErrorsCard } from '@backstage/plugin-periskop';

const componentPage = (
  <EntityLayout>
    {/* other tabs... */}
    <EntityLayout.Route path="/periskop" title="Periskop">
      <Grid container spacing={3} alignItems="stretch">
        <Grid item xs={12} sm={12} md={12}>
          <EntityPeriskopErrorsCard />
        </Grid>
      </Grid>
    </EntityLayout.Route>

Setup the app-config.yaml periskop block
Annotate entities with the periskop service name

annotations:
  periskop.io/service-name: '<THE NAME OF THE PERISKOP APP>'

Run app with yarn start and navigate to /periskop or a catalog entity 'Periskop' tab

Instances

The periskop plugin can be configured to fetch aggregated errors from multiple deployment instances.
This is especially useful if you have a multi-zone deployment, or a federated setup and would like to drill deeper into a single instance of the federation. Each of the configured instances will be included in the plugin's UI via a dropdown on the errors table.

The plugin requires to configure at least one Periskop API location in the app-config.yaml:

periskop:
  instances:
    - name: <name of the instance>
      url: <HTTP/S url for the Periskop instance's API>