Skip to content

Commit 9172316

Browse files
author
Mario Mann
committed
Update readme file
1 parent 3b5ddb6 commit 9172316

File tree

1 file changed

+164
-32
lines changed

1 file changed

+164
-32
lines changed

‎README.md‎

100644100755
Lines changed: 164 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,173 @@
1-
# Grafana Panel Plugin Template
1+
## Novatec Service Dependency Graph Panel
22

3-
<!--
4-
[![CircleCI](https://circleci.com/gh/grafana/simple-react-panel.svg?style=svg)](https://circleci.com/gh/grafana/simple-react-panel)
5-
[![David Dependency Status](https://david-dm.org/grafana/simple-react-panel.svg)](https://david-dm.org/grafana/simple-react-panel)
6-
[![David Dev Dependency Status](https://david-dm.org/grafana/simple-react-panel/dev-status.svg)](https://david-dm.org/grafana/simple-react-panel/?type=dev)
7-
[![Known Vulnerabilities](https://snyk.io/test/github/grafana/simple-react-panel/badge.svg)](https://snyk.io/test/github/grafana/simple-react-panel)
8-
[![Maintainability](https://api.codeclimate.com/v1/badges/1dee2585eb412f913cbb/maintainability)](https://codeclimate.com/github/grafana/simple-react-panel/maintainability)
9-
[![Test Coverage](https://api.codeclimate.com/v1/badges/1dee2585eb412f913cbb/test_coverage)](https://codeclimate.com/github/grafana/simple-react-panel/test_coverage) -->
3+
[![Downloads](https://img.shields.io/badge/dynamic/json?color=orange&label=downloads&query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22novatec-sdg-panel%22%29%5D.downloads&url=https%3A%2F%2Fgrafana.com%2Fapi%2Fplugins)](https://grafana.com/grafana/plugins/novatec-sdg-panel)
4+
[![License](https://img.shields.io/github/license/NovatecConsulting/novatec-service-dependency-graph-panel)](LICENSE)
105

11-
This template is a starting point for building Grafana Panel Plugins in Grafana 7.0+
126

7+
![Service Dependency Graph In Action](https://novatecconsulting.github.io/novatec-service-dependency-graph-panel/images/service-dependency-graph-panel.gif)
138

14-
## What is Grafana Panel Plugin?
15-
Panels are the building blocks of Grafana. They allow you to visualize data in different ways. While Grafana has several types of panels already built-in, you can also build your own panel, to add support for other visualizations.
9+
The Service Dependency Graph Panel by [Novatec](https://www.novatec-gmbh.de/en/) provides you with many features such as monitoring
10+
your latencies, errors and requests of your desired service. This interactive panel for [Grafana](https://grafana.com/) will help you
11+
visualize the processes of your application much better.
1612

17-
For more information about panels, refer to the documentation on [Panels](https://grafana.com/docs/grafana/latest/features/panels/panels/)
13+
___
14+
### How to build
15+
16+
Due to dependency issues please install, if needed with `yarn install`
17+
18+
To build a production build with minification: `yarn build`
19+
20+
Run the following for hot-reloading during development: `yarn watch`
21+
22+
___
23+
24+
## Configuration of the Data Source
25+
26+
### Using Static Dummy Data
27+
28+
If you want to get a first impression of this panel without having your own data source yet, the panels provides you some dummy data to play around with.
29+
30+
The dummy data is basically a snapshot of multiple query results in the table format. You'll find its source [here](https://github.com/NovatecConsulting/novatec-service-dependency-graph-panel/blob/master/src/dummy_data_frame.ts), in the panel's GitHub repository.
31+
32+
Depending on the query result, the data provides the following tags:
33+
* **service**: The service (application) the data is realted to.
34+
* **protocol**: The communication type (e.g. HTTP, JMS, ...).
35+
* **origin_service**: In case of an incoming communication, this is the origin service.
36+
* **target_service**: In case of an outgoing communication, this is the target service.
37+
* **origin_external**: The origin of an incoming communication, which cannot be correlated to a known serive (e.g. HTTP request of a third party application).
38+
* **target_external**: The target of an outgoing communication, which cannot be correlated to a known serive (e.g. third party HTTP endpoint).
39+
40+
Depending on the query result, the data provides the following fields:
41+
* **in_timesum**: The total sum of all incoming request response times. (Prometheus style)
42+
* **in_count**: The total amount of incoming requests.
43+
* **error_in**: The amount of incoming requests which produced an error.
44+
* **out_timesum**: The total sum of all outgoing request response times. (Prometheus style)
45+
* **out_count**: The total amount of outgoing requests.
46+
* **error_out**: The amount of outgoing requests which produced an error.
47+
* **threshold**: The critical threshold in miliseconds for the response times of incoming requests.
48+
49+
50+
In order to use this data you simply have to follow the following steps:
51+
52+
1. Add a `template variable` in Grafana called `aggregationType` having the constant value `service`.
53+
2. After selecting the Novatec Service Dependency Graph in your panels' settings check the box called `Show Dummy Data`.
54+
3. Adapt the panel's `Data Mapping` according to the dummy data. You can use the following settings. Note: at least you have to specify the `Request Rate` mapping!
55+
56+
| key | value |
57+
| --- | --- |
58+
| Response Time | in_timesum |
59+
| Request Rate | in_count |
60+
| Error Rate | error_in |
61+
| Response Time (Outgoing) | out_timesum |
62+
| Request Rate (Outgoing) | out_count |
63+
| Error Rate (Outgoing) | error_out |
64+
| Response Time Baseline (Upper) | threshold |
65+
66+
_Note that you may have to refresh the dashboard or reload the page in order for it to work._
67+
68+
##### Live example dummy data
69+
70+
Downloading and launching the [inspectIT Ocelot demo #1](https://inspectit.github.io/inspectit-ocelot/docs/getting-started/docker-examples) will provide you with live dummy data rather than static one.
71+
Just open the docker images' Grafana and choose the dashboard `Service Graph` to see the fully functional Service Dependency Graph.
72+
___
73+
74+
### Use your own Data Source
75+
76+
If you now want to use your own data source you have make sure, that the data received is in the `TABLE` format and is structured as follows:
77+
78+
* The table requires a column which is named equal to the value of the `aggregationType` template variable. This column defines the component to which the data refers.
79+
**Example**: Assuming the `aggregationType` template variable is set to `app`, the data table has to provide a column named `app`.
80+
* The table requires at least one column which specifies the connection's origin or target. This column has the following requirements for its naming:
81+
* It requires a suffix which has to be equal to the `aggregationType` template variable.
82+
* In case an incoming connection should be represented, a prefix is required which is equal to the `Source Component Column Prefix` panel option. By default it is `origin_`.
83+
* In case an outcoming connection should be represented, a prefix is required which is equal to the `Target Component Column Prefix` panel option. By default it is `target_`.
84+
85+
**Example**: Assuming the `aggregationType` template variable is set to `app`, the previously mentioned column prefix options are in its default state (`origin_` or `target_`) and we want to represent an outgoing connection. In this case, the data table has to provide a column named: `target_app`
86+
* The data table can contain multiple value columns. These columns have to be mapped on specifc attributes using the panel's `Data Mappings` options.
87+
**Example**: Assuming the data table contains a column named `req_rate` which values represents a request rate for the related connection in the current time window. In order to correctly visualize these values as a request rate, the `Request Rate Column` option has to be set to `req_rate` - the column's name.
88+
89+
#### Examples
90+
91+
##### Example 1
92+
93+
If the previously described requirements are respected, a minimal table can be as follows:
94+
95+
| app | target_app | req_rate |
96+
| --- | --- | --- |
97+
| service a | service b | 50 |
98+
| service a | service c | 75 |
99+
| service c | service d | 25 |
100+
101+
Assuming a `aggregationType` template variable is provided and set to `app` and the panel's settings are specified as seen in the screenshot, the panel will visualize the data as following:
102+
103+
![Visualization of the minimal data table.](https://raw.githubusercontent.com/NovatecConsulting/novatec-service-dependency-graph-panel/master/src/img/data-example-1.png)
104+
105+
> Note: It is important to know that connections can only be generated if at least one request-rate column (incoming or outgoing) is defined.
106+
107+
The data mapping represents always the data from the point of view of the component which is specified by the column which name is equal to the `aggregationType` template variable. This means that if we want to represent an outgoing connection in this example, the `app` and `target_app` columns must be present. In case an incoming connection should be represented, the `app` and `origin_app` columns must be present.
108+
109+
##### Example 2
110+
111+
In this example, we extend the data table of example 1 by another column, representing the total sum of all request response times of a specific connection (e.g. sum of all HTTP request response times).
112+
113+
| app | target_app | req_rate | resp_time |
114+
| --- | --- | --- | --- |
115+
| service a | service b | 50 | 4000 |
116+
| service a | service c | 75 | 13650 |
117+
| service c | service d | 25 | 750 |
118+
119+
Now, the panel's `Data Mappings` option `Response Time Column` is set to `resp_time`. This specifies that the value in the `resp_time` column should be handled as the response time for a connection. By default, the values in this column will be handled as a sum of all response times - kind of a Prometheus style metric. This behavior can be changed by using the `Handle Timings as Sums` option. This table will result in the following visualization.
120+
121+
![Visualization of a data table including request rate and response times.](https://raw.githubusercontent.com/NovatecConsulting/novatec-service-dependency-graph-panel/master/src/img/data-example-2.png)
122+
123+
___
124+
125+
### Service Icons
126+
127+
The service dependency graph plugin allows you to display your own symbols in the drawn nodes.
128+
For this purpose the option 'Service Icon Mapping' can be used.
129+
Here you can specify an assignment of icons to certain name patterns.
130+
All nodes that match the specified pattern (regular expression) will get the icon.
131+
132+
![Custom service icons in the graph.](https://raw.githubusercontent.com/NovatecConsulting/novatec-service-dependency-graph-panel/master/src/img/service-icons.png)
133+
134+
##### Example
135+
136+
A sample assignment is included by default: `Pattern: java // Icon: java`.
137+
This means that all nodes which have `java` in their name get the `java` icon.
138+
139+
#### Custom Service Icons
140+
141+
You can add custom icons, by putting them into the plugin's `/assets/service_icons/` directory.
142+
The file type **has to be `PNG`** and the icon itself and **has to be square**.
143+
In order to be able to use the icon, its name (without its ending) has to be put into the array contained in the `icon_index.json` file located in the `/assets/service_icons/` directory.
144+
145+
##### Example
146+
147+
If the `icon_index.json` has the following content:
18148

19-
## Getting started
20-
1. Install dependencies
21-
```BASH
22-
yarn install
23-
```
24-
2. Build plugin in development mode or run in watch mode
25-
```BASH
26-
yarn dev
27-
```
28-
or
29-
```BASH
30-
yarn watch
31149
```
32-
3. Build plugin in production mode
33-
```BASH
34-
yarn build
150+
["java", "star_trek"]
35151
```
36152

37-
## Learn more
38-
- [Build a panel plugin tutorial](https://grafana.com/tutorials/build-a-panel-plugin)
39-
- [Grafana documentation](https://grafana.com/docs/)
40-
- [Grafana Tutorials](https://grafana.com/tutorials/) - Grafana Tutorials are step-by-step guides that help you make the most of Grafana
41-
- [Grafana UI Library](https://developers.grafana.com/ui) - UI components to help you build interfaces using Grafana Design System
153+
it is assumed that the files `java.png` and `star_trek.png` is existing in the `/assets/service_icons/` directory.
154+
___
155+
156+
### Tracing Drilldown
157+
158+
The service dependency graph plugin allows you to specify a backend URL for each drawn node.
159+
For this purpose the option 'Tracing Drilldown' can be used.
160+
Here you can specify a backend URL. An open and closed curly bracket `{}` is the placeholder for the selected node.
161+
Each node will get an arrow icon in the details view. This icon is a link to your backend, specified in the options.
162+
The curly brackets `{}` will be replaced with the selected node.
163+
164+
#### Example
165+
166+
`http://{}/my/awesome/path` will end up to `http://customers-service/my/awesome/path` when you select the `customers-service`.
167+
168+
___
169+
170+
### Found a bug? Have a question? Wanting to contribute?
171+
172+
Feel free to open up an issue. We will take care of you and provide as much help as needed. Any suggestions/contributions are being very much appreciated.
173+

0 commit comments

Comments
 (0)