/nodegraph-api-plugin

A data source plugin for nodegraph panel in grafana

Primary LanguageTypeScriptApache License 2.0Apache-2.0

Nodegraph API Plugin for Grafana

License CI Release

This plugin provides a data source to connect a REST API to nodegraph panel of Grafana. It is signed and published by Grafana.

Graph Example

Requirements

  • Grafana 7.5+

Getting started

Installation via grafana-cli tool

Use the grafana-cli tool to install Node Graph API from the commandline:

grafana-cli plugins install hamedkarbasi93-nodegraphapi-datasource

The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.

Installation via zip file

Alternatively, you can manually download the latest release .zip file and unpack it into your grafana plugins directory; the default is /var/lib/grafana/plugins.

Plugin Configuration

You can now add the data source. Just enter the URL of your API app and push "Save & Test." You will get an error in case of connection failure.

Add Datasource

In the Grafana dashboard, pick the Nodegraph panel and visualize the graph.

Note on Application Access:

  • Versions 0.x.x work in direct mode. i.e., The browser must have access to the API application.
  • Versions 1.x.x+ work in proxy mode. i.e., The Grafana server should have access to the API application.

API Configuration

The REST API application should handle three requests: fields, data, and health. They are described below.

Fetch Graph Fields

This route returns the nodes and edges fields defined in the parameter tables. It would help the plugin to create desired parameters for the graph. For nodes, id and for edges, id, source, and target fields are required. Other fields are optional.

endpoint: /api/graph/fields

method: GET

content type: application/json

content format example:

{
  "edges_fields": [
    {
      "field_name": "id",
      "type": "string"
    },
    {
      "field_name": "source",
      "type": "string"
    },
    {
      "field_name": "target",
      "type": "string"
    },
    {
      "field_name": "mainStat",
      "type": "number"
    }
  ],
  "nodes_fields": [
    {
      "field_name": "id",
      "type": "string"
    },
    {
      "field_name": "title",
      "type": "string"
    },
    {
      "field_name": "mainStat",
      "type": "string"
    },
    {
      "field_name": "secondaryStat",
      "type": "number"
    },
    {
      "color": "red",
      "field_name": "arc__failed",
      "type": "number"
    },
    {
      "color": "green",
      "field_name": "arc__passed",
      "type": "number"
    },
    {
      "displayName": "Role",
      "field_name": "detail__role",
      "type": "string"
    }
  ]
}

Fetch Graph Data

This route returns the graph data, which is intended to visualize.

endpoint: /api/graph/data

method: GET

content type: application/json

Data Format example:

{
    "edges": [
        {
            "id": "1",
            "mainStat": "53/s",
            "source": "1",
            "target": "2"
        }
    ],
    "nodes": [
        {
            "arc__failed": 0.7,
            "arc__passed": 0.3,
            "detail__zone": "load",
            "id": "1",
            "subTitle": "instance:#2",
            "title": "Service1"
        },
        {
            "arc__failed": 0.5,
            "arc__passed": 0.5,
            "detail__zone": "transform",
            "id": "2",
            "subTitle": "instance:#3",
            "title": "Service2"
        }
    ]
}

For more detail of the variables, please visit here.

Health

This route is for testing the health of the API, which is used by the Save & Test action while adding the plugin.(Part 2 of the Getting Started Section). Currently, it only needs to return the 200 status code in case of a successful connection.

endpoint: /api/health

method: GET

success status code: 200

API Example

In the example folder, you can find a simple API application in Python Flask.

Requirements:

  • flask

Run

python run.py

The application will be started on http://localhost:5000

Query Configuration

You can pass a query string to apply for the data endpoint of the graph via Query String. Like any other query, you can utilize variables too:

Add Datasource

With variable $service defined as processors, above query will produce this endpoint: /api/graph/data?query=text1&service=processors

Compiling the data source by yourself

  1. Install dependencies

    yarn install

  2. Build plugin in development mode or run in watch mode

    yarn dev

    or

    yarn watch

  3. Build plugin in production mode

    yarn build

Roadmap

  • Utilize BackenSrv in proxy mode. This will prevent the client browser necessity to connect to the API server.
  • Write unit tests.

Learn more

Contributing

Thank you for considering contributing! If you find an issue or have a better way to do something, feel free to open an issue or a PR.

License

This repository is open-sourced software licensed under the Apache License 2.0.