Skip to content

Commit

Permalink
Merge pull request #181 from sasaki77/docs
Browse files Browse the repository at this point in the history 
DOC: update docs
  • Loading branch information
@sasaki77
sasaki77 authored Nov 25, 2024
2 parents 358ef6a + ed04fa7 commit f7dce52
Show file tree
Hide file tree
Showing 11 changed files with 103 additions and 158 deletions.
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,16 @@
# Change Log
## 2.0.0 (2024-12-xx)

### Enhancements
- **Backend**: Migrate retrieval format from qw JSON to PB raw
- **Backend**: Add the `fieldName` function to handle the severity of PV
- **Backend**: Add the `hideInvalid` feature to hide data with invalid level severity
- **Frontend**:Remove gf-form appearances in QueryEditor

### Bug fixes
- **Frontend**: Fix extrapolation for stream with raw operation


## 1.6.1 (2024-01-22)

### Enhancements
Expand Down
87 changes: 15 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ Visualize EPICS Archiver Appliance on Grafana.
![Screenshot](https://sasaki77.github.io/archiverappliance-datasource/_images/aa-query-overview.png)


See [Archiver Appliance site](https://slacmshankar.github.io/epicsarchiver_docs/index.html) for more information about Archiver Appliance.
See [Archiver Appliance site](https://epicsarchiver.readthedocs.io) for more information about Archiver Appliance.

## Features
- Select multiple PVs by using Regex (Only supports wildcard pattern like `PV.*` and alternation pattern like `PV(1|2)`)
- Legend alias with regular expression pattern
- Data retrieval with data processing (See [Archiver Appliance User Guide](https://slacmshankar.github.io/epicsarchiver_docs/userguide.html) for processing of data)
- Data retrieval with data processing (See [Archiver Appliance User Guide](https://epicsarchiver.readthedocs.io/en/latest/user/userguide.html#processing-of-data) for processing of data)
- Using PV names for Grafana variables
- Transform your data with processing functions
- Live update with stream feature
Expand Down Expand Up @@ -40,7 +40,7 @@ Clone this plugin into grafana plugins directory; the default is /var/lib/grafan

### Configuring the plugin

Please consult [https://sasaki77.github.io/archiverappliance-datasource/configuration.html] for instructions to configure the plugin following installation.
Please consult [Configuration manual](https://sasaki77.github.io/archiverappliance-datasource/configuration.html) for instructions to configure the plugin following installation.

## Documentaion
Documentation is available at [https://sasaki77.github.io/archiverappliance-datasource](https://sasaki77.github.io/archiverappliance-datasource).
Expand All @@ -51,17 +51,17 @@ This section lists the available configuration options for the Archiver Applianc

### Query editor

| Configuration | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PV** | Set PV name to be visualized. It is allowed to set multiple PVs by using Regular Expressoins alternation pattern (e.g. `(PV:1\|PV:2)`). |
| **Regex** | Enable/disable Regex mode. Refer [Select Multiple PVs by Regex](https://sasaki77.github.io/archiverappliance-datasource/query.html#select-multiple-pvs-by-regex). |
| **Operator** | Controls processing of data during data retrieval (Default: `mean`). Refer [Archiver Appliance User Guide](https://slacmshankar.github.io/epicsarchiver_docs/userguide.html) about processing of data. Special operator `raw` and `last` are also available. `raw` allows to retrieve the data without processing. `last` allows to retrieve the last data in the specified time range. |
| **Stream** | Enable/Disable Stream mode. Stream allows to periodically update the data without refreshing the dashboard. The difference data from the last updated values is only retrieved. |
| **Interval** | Streaming interval in milliseconds. You can also use a number with unit. e.g. `1s`, `1m`, `1h`. The default is determined by a width of panel and time range. |
| **Capacity** | The stream data is stored in a circular buffer. Capacity determines the buffer size. The default is detemined by a initial data size. |
| **Alias** | Set alias for legend. |
| **Alias pattern** | Set regular expressoin pattern to use PV name for legend alias. Refer [Legend Alias with Regex Pattern](https://sasaki77.github.io/archiverappliance-datasource/query.html#legend-alias-with-regex-pattern) |
| **Function** | Apply processing function for retrieved data. Refer [Apply Processing Functions](https://sasaki77.github.io/archiverappliance-datasource/query.html#apply-processing-functions) |
| Configuration | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **PV** | Set PV name to be visualized. It is allowed to set multiple PVs by using Regular Expressoins alternation pattern (e.g. `(PV:1\|PV:2)`). |
| **Regex** | Enable/disable Regex mode. Refer [Select Multiple PVs by Regex](https://sasaki77.github.io/archiverappliance-datasource/query.html#select-multiple-pvs-by-regex). |
| **Operator** | Controls processing of data during data retrieval (Default: `mean`). Refer [Archiver Appliance User Guide](https://epicsarchiver.readthedocs.io/en/latest/user/userguide.html#processing-of-data) about processing of data. Special operator `raw` and `last` are also available. `raw` allows to retrieve the data without processing. `last` allows to retrieve the last data in the specified time range. |
| **Stream** | Enable/Disable Stream mode. Stream allows to periodically update the data without refreshing the dashboard. The difference data from the last updated values is only retrieved. |
| **Interval** | Streaming interval in milliseconds. You can also use a number with unit. e.g. `1s`, `1m`, `1h`. The default is determined by a width of panel and time range. |
| **Capacity** | The stream data is stored in a circular buffer. Capacity determines the buffer size. The default is detemined by a initial data size. |
| **Alias** | Set alias for legend. |
| **Alias pattern** | Set regular expressoin pattern to use PV name for legend alias. Refer [Legend Alias with Regex Pattern](https://sasaki77.github.io/archiverappliance-datasource/query.html#legend-alias-with-regex-pattern) |
| **Function** | Apply processing function for retrieved data. Refer [Apply Processing Functions](https://sasaki77.github.io/archiverappliance-datasource/query.html#apply-processing-functions) |

### Variables

Expand Down Expand Up @@ -94,7 +94,7 @@ This data source plugin consists of both frontend and backend components.

### Front-end Development

Node version v12.x is recommended. If you're new to the Node.js ecosystem, [Node Version Manager](https://github.com/nvm-sh/nvm) is a good place to start for managing different Node.js installations and environments.
Node version v12.x is recommended. If you're new to the Node.js ecosystem, [Node Version Manager](https://github.com/nvm-sh/nvm) is a good place to start for managing different Node.js installations and environments.

[grafana-toolkit](https://github.com/grafana/grafana/tree/master/packages/grafana-toolkit) is used to develop the plugin. Please refer grafana-toolkit documentation for more information.

Expand Down Expand Up @@ -141,63 +141,6 @@ mage -v
mage -l
```

### Test environment with Docker Compose
Thanks to [pklaus / docker-archiver-appliance](https://github.com/pklaus/docker-archiver-appliance) and [pklaus / archiver-appliance-with-example-ioc](https://github.com/pklaus/archiver-appliance-with-example-ioc), the test environment is available with Docker Compose.

```bash
docker-compose up
```

The following containers are runinng after `docker-compse up`.

| Name | Description |
| ------------ | -------------------------------------------------------------------- |
| **grafana** | Runs a Grafana server. |
| **archappl** | Runs a EPICS Archiver Appliance. |
| **redis** | Runs a datastore for the persistance of the appliance configuration. |
| **example** | Runs a example EPICS IOC to be archived. |

To set up the Archiver Appliance, open http://localhost:17665/mgmt/ui/index.html. You can add the PVs served by the example IOC on this page.
Enter the following lines in the input field and then clicking the `Archive` button.
the Archive will be start a few minuites later.

```
root:circle:tick
root:circle:step
root:circle:period
root:line:b
root:aiExample
root:aiExample1
root:ai1
root:aiExample2
root:ai2
root:aiExample3
root:ai3
root:EXAMPLE:version
root:compressExample
root:circle:angle
root:line:a
root:circle:x
root:circle:y
root:calcExample
root:calcExample1
root:calc1
root:calcExample2
root:calc2
root:calcExample3
root:calc3
```

![Archiver-Appliance-mgmt-page](https://sasaki77.github.io/archiverappliance-datasource/_images/aa-test-mgmt-page.png)

To add a data source, open Grafana (http://localhost:3000). On the data sources page, add a data source and set URL as http://archappl:17665/retrieval.

![test-configuration](https://sasaki77.github.io/archiverappliance-datasource/_images/aa-test-configuration.png)

The following is a example query with this test environment.

![test-query](https://sasaki77.github.io/archiverappliance-datasource/_images/aa-test-query.png)

## Build documentation

```
Expand Down
4 changes: 2 additions & 2 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
# -- Project information -----------------------------------------------------

project = "Archiver Appliance Datasource"
copyright = "2019-2022, Shinya Sasaki"
copyright = "2019-2024, Shinya Sasaki"
author = "Shinya Sasaki"

# The full version, including alpha/beta/rc tags
release = "1.0.0"
release = "2.0.0"


# -- General configuration ---------------------------------------------------
Expand Down
14 changes: 8 additions & 6 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,16 @@ more information.
![Datasrouce settings](./img/aa-configuration-datasource-settings.png)

### HTTP
- **URL:** set `retrieval url` end with retrieval.
- **Access:** controls how requests to the data source will be handled. Only `Server` mode is tested in this plugin.
- **Server:** Grafana backend/server forwards the requests to the Archiver Appliance server.
- **Browser:** directly access to the Archiver Appliance server from the browser.
- **Whitelisted Cookies:** no need to configure.
- **URL:** sets `retrieval url` end with retrieval.
- **Allowed Cookies:** no need to configure.
- **Timeout:** sets HTTP request timeout in seconds if you need.

### Auth
Basically, no need to configure.

### Misc
- **Use Backend:** enable GO backend to retrieve the archive data for visualization. The archived data is retrieved and processed on Grafana server, then the data is sent to Grafana client.
- **Use Backend:** enables GO backend to retrieve the archive data for visualization. The archived data is retrieved and processed on Grafana server, then the data is sent to Grafana client.
- **Default Operator:** controls the default operator for processing of data during data retrieval.
- **Hide Invalid:** hides the sample data whose severity is invalid with a null value. This feature is only effective if you are using the backend data retrieval.
- **Use live feature:** enables live updating with PVWS WebSocket server.
- **PVWS URI:** sets the URI for the PVWS WebSocket server.
63 changes: 3 additions & 60 deletions docs/development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ This data source plugin consists of both frontend and backend components.

### Front-end Development

Node version v12.x is recommended. If you're new to the Node.js ecosystem, [Node Version Manager](https://github.com/nvm-sh/nvm) is a good place to start for managing different Node.js installations and environments.
Node version v12.x is recommended. If you're new to the Node.js ecosystem, [Node Version Manager](https://github.com/nvm-sh/nvm) is a good place to start for managing different Node.js installations and environments.

[grafana-toolkit](https://github.com/grafana/grafana/tree/master/packages/grafana-toolkit) is used to develop the plugin. Please refer grafana-toolkit documentation for more information.
[grafana-toolkit](https://grafana.com/developers/plugin-tools/) is used to develop the plugin. Please refer grafana-toolkit documentation for more information.

1. Begin by installing Yarn ([https://yarnpkg.com/](https://yarnpkg.com/))
```bash
Expand Down Expand Up @@ -37,7 +37,7 @@ Node version v12.x is recommended. If you're new to the Node.js ecosystem, [Node

If the Mage build tool is not already installed, you may install it using the installation instructions on the [Mage homepage](https://magefile.org/)

1. Update [Grafana plugin SDK for Go](https://grafana.com/docs/grafana/latest/developers/plugins/backend/grafana-plugin-sdk-for-go/) dependency to the latest minor version:
1. Update [Grafana plugin SDK for Go](https://grafana.com/developers/plugin-tools/key-concepts/backend-plugins/grafana-plugin-sdk-for-go) dependency to the latest minor version:

```bash
go get -u github.com/grafana/grafana-plugin-sdk-go
Expand All @@ -53,63 +53,6 @@ If the Mage build tool is not already installed, you may install it using the in
mage -l
```

### Test environment with Docker Compose
Thanks to [pklaus / docker-archiver-appliance](https://github.com/pklaus/docker-archiver-appliance) and [pklaus / archiver-appliance-with-example-ioc](https://github.com/pklaus/archiver-appliance-with-example-ioc), the test environment is available with Docker Compose.

```bash
docker-compose up
```

The following containers are runinng after `docker-compse up`.

| Name | Description |
| ------------ | -------------------------------------------------------------------- |
| **grafana** | Runs a Grafana server. |
| **archappl** | Runs a EPICS Archiver Appliance. |
| **redis** | Runs a datastore for the persistance of the appliance configuration. |
| **example** | Runs a example EPICS IOC to be archived. |

To set up the Archiver Appliance, open [http://localhost:17665/mgmt/ui/index.html](http://localhost:17665/mgmt/ui/index.html). You can add the PVs served by the example IOC on this page.
Enter the following lines in the input field and then clicking the `Archive` button.
the Archive will be start a few minuites later.

```
root:circle:tick
root:circle:step
root:circle:period
root:line:b
root:aiExample
root:aiExample1
root:ai1
root:aiExample2
root:ai2
root:aiExample3
root:ai3
root:EXAMPLE:version
root:compressExample
root:circle:angle
root:line:a
root:circle:x
root:circle:y
root:calcExample
root:calcExample1
root:calc1
root:calcExample2
root:calc2
root:calcExample3
root:calc3
```
![Archiver-Appliance-mgmt-page](./img/aa-test-mgmt-page.png)
To add a data source, open Grafana ([http://localhost:3000](http://localhost:3000)). On the data sources page, add a data source and set URL as `http://archappl:17665/retrieval`.
![test-configuration](./img/aa-test-configuration.png)
The following is a example query with this test environment.
![test-query](./img/aa-test-query.png)
## Build documentation
This documentation is build by Sphinx. Follow below steps to build documentation.

Expand Down
Loading

0 comments on commit f7dce52

Please sign in to comment.