# OpenShift Monitoring Plugin
This plugin enables frontend UI based on feature flags passed to the backend. These features are generally grouped under two sets, those deployed by the [Cluster Monitoring Operator](https://github.com/openshift/cluster-monitoring-operator) (alerting, dashboards, metrics and targets) and those deployed by the [Cluster Observability Operator](https://github.com/rhobs/observability-operator) (ACM Alerting, Perses Dashboards, Incidents). CMO is included and enabled by default on most installations of OpenShift so observability signals needed for these features are expected to be present in any cluster, while the COO features utilize optional observability signals which are installed through COO. Information on running the plugin as it if were deployed through CMO can be found under the [monitoring-plugin](#monitoring-plugin) heading and the other set can be found under the [monitoring-console-plugin](#monitoring-console-plugin) heading.
## Feature Flags
Feature flags should be added to the Feature enum [here](pkg/server/server.go) and to the useFeatures hook [here](web/src/shared/hooks/useFeatures.ts). Whenever a feature is enabled, a set of related feature extension points is included in the plugin-manifest.json served by the backend. These feature extension points are created through the use of [json-patches](https://datatracker.ietf.org/doc/html/rfc6902), such as the `acm-alerting` patch [here](config/acm-alerting.patch.json). The server looks for a patch in the format of `{feature-flag-name}.patch.json` to apply. UI-only flags, such as `alert-management-api`, do not need a manifest patch and can be checked directly by frontend components. Some feature flags, such as `acm-alerting` require other flags to be set such as `alertmanager` and `thanos-querier` to instruct the backend how to communicate with the observability signals they utilize
| Feature | OCP Version |
| -------------------- | ----------- |
| acm-alerting | 4.14+ |
| perses-dashboards | 4.14+ |
| incidents | 4.17+ |
| alerting | 5.0+ |
| legacy-dashboards | 5.0+ |
| metrics | 5.0+ |
| targets | 5.0+ |
| overview | 5.1+ |
| alert-management-api | 5.1+ |
## monitoring-plugin
This section describes knowledge helpful to development of the default monitoring-plugin.
### Docker image
Before you can deploy the plugin on a cluster, you must build an image and push it to an image registry.
1. Build the image:
```sh
docker build -t quay.io/my-repositroy/my-plugin:latest .
```
2. Run the image:
```sh
docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest
```
3. Push the image:
```sh
docker push quay.io/my-repository/my-plugin:latest
```
NOTE: If you have a Mac with Apple silicon, you will need to add the flag `--platform=linux/amd64` when building the image to target the correct platform to run in-cluster. We recommend utilizing the `make build-image` action to build and push the image.
### Deployment on cluster
### Running using Devspace
Install the [devspace](https://www.devspace.sh/docs/getting-started/installation) cli.
Devspace works by "taking over" a pod. It does this by scaling down the original, forwarding the traffic to its own pod, copying any mounted files and directories (like certs) and then syncing changes you make locally into that pod. Our configuration syncs `web/dist` to `/opt/app-root/web/dist`, where the Go backend serves the frontend files from, and syncs the `cmd`, `pkg`, and `config` directories into the pod. Air watches the Go source files and JSON config patches, rebuilding and restarting the backend when they change.
By running the webpack dev server locally any changes to your frontend files they will be rebuilt and then copied into the pod. You will need to disable your network cache in your dev tools to allow for overriding the previous webpack chunks and then perform a page refresh to see your changes.
#### Monitoring Features
When running the `devspace dev` command, the pipeline will run `scale-down-cmo.sh` function to scale down the CMO deployment, which keeps it from fighting over control of the monitoring-plugin pod.
```sh
make start-frontend
devspace dev # select mp
```
Running `devspace purge` and selecting `mp` will scale the CMO deployment back up
#### COO Features: ACM Alerting, Perses Dashboards, Health analyzer.
When running the `devspace dev` command, the pipeline will run `install-coo.sh` which will attempt to install COO if it isn't already installed. It will then create a `Monitoring` type `UIPlugin` with all features enabled. Once the `monitoring-console-plugin` deployment is ready it will scale down COO to prevent it from fighting over the deployment.
```sh
make start-mcp-frontend
devspace dev # select mcp
```
Running `devspace purge` and selecting `mcp` will scale the COO deployment back up.
### Local Development
#### Editor configuration
Some of the lint rules for typescript which we have enabled in our codebase are not supported by prettier and need to be solved by running `eslint --fix` You can configure your code editor to perform this on save/format although some setup is needed:
- zed: https://zed.dev/docs/languages/javascript#eslint
- vscode: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint
We recommend running the following eslint rules when formatting:
- `import/order`
- `sort-imports`
#### Dependencies
1. [Node.js 22+](https://nodejs.org/en/) and [npm](https://www.npmjs.com/) are required
2. [oc](https://mirror.openshift.com/pub/openshift-v4/clients/oc/4.4/)
3. [podman 3.2.0+](https://podman.io) or [Docker](https://www.docker.com)
4. An OpenShift cluster
#### Running Locally
```
# Login to an OpenShift cluster
$ oc login <clusterAddress> -u <username> -p <password>
# Start podman (or Docker)
$ podman machine init
$ podman machine start
# Install dependencies
$ make install
# Run the frontend
$ make start-frontend
# In a separate terminal
# Run the backend
$ make start-backend
# In a separate terminal
$ make start-console
```
The application will be running at [localhost:9000](http://localhost:9000/).
#### Local Development Troubleshooting
1. Disable cache. Select 'disable cache' in your browser's DevTools > Network > 'disable cache'. Or use private/incognito mode in your browser.
2. Enable higher log verbosity by setting `-log-level=trace` when starting the plugin backend. For more options to set log level see [logrus documentation](https://github.com/sirupsen/logrus?tab=readme-ov-file#level-logging).
## monitoring-console-plugin (mcp)
### Dependencies
1. [Local Development Dependencies](README#Dependencies)
2. [yq](https://github.com/mikefarah/yq) for acm deployment
3. sed ([gnu-sed](https://formulae.brew.sh/formula/gnu-sed) for mac, with sed being aliased to that gnu-sed)
### Building an image
Images for the mcp can be built by running the following command. Due to the limitation of linux/amd64 image builds on Apple Silicon Macs's, some of the changes are run locally and not just in the Dockerfiles. If you are on a Mac, it is not suggested to cancel the exection of this scipt part way through
```bash
make build-dev-mcp-image
```
### Redux Store
Since the store for the `monitoring-plugin` is stored in the `openshift/console` codebase and updates to the store that are aren't tied directly to the OCP are needed, when the default extension points are removed due to the presence of a feature flag a duplicate store is created at the `.state.plugins.mcp` path. A combination of the `useFeatures` hook and the `getLegacyObserveState` (which is dependent on the perspective) can be used to retrieve the state from the redux store based on the mode the plugin was deployed in.
### Local Development
```
# Login to an OpenShift cluster
$ oc login <clusterAddress> -u <username> -p <password>
# Start podman (or Docker) - Linux machines can skip this part
$ podman machine init
$ podman machine start
# Install dependencies
$ make install
# Run the application
$ make start-frontend
# In a separate terminal
$ make start-console
# In a separate terminal
$ make start-coo-backend
```
`make start-coo-backend` will inject the `alerting,targets,overview,legacy-dashboards,metrics,incidents,perses-dashboards` features.
#### Local Development with Perses Proxy
The bridge script `start-console.sh` is configured to proxy to a local Perses instance running at port `:8080`. To run the local Perses instance you will need to clone the [perses/perses](https://github.com/perses/perses) repository and follow the start up instructions in [ui/README.md](https://github.com/perses/perses/blob/63601751674403f626d1dea3dec168bdad0ef1c7/ui/README.md) :
```
# Clone the perses/perses repo
$ git clone https://github.com/perses/perses.git
$ cd perses
# Follow the instructions in ui/README.md
$ cd ui
$ npm install
$ npm run build
$ ./scripts/api_backend_dev.sh
# Lastly navigate to http://localhost:8080/ to see Perses app running
```
##### Install COO && Perses Datasource && Perses Sample Dashboard
1. Install COO through the OpenShift UI > OperatorHub > Cluster Observability Operator
2. Install UIPlugin > monitoring
3. oc apply -f <PERSES_DATASOURCE_YAML>
- See sample yaml [here](https://github.com/observability-ui/development-tools/blob/main/monitoring-plugin/monitoring-console-plugin/perses/thanos-querier-datasource.yaml)
4. oc apply -f <PERSES_DASHBOARD_YAML>
- See sample yaml [here](https://github.com/observability-ui/development-tools/blob/main/monitoring-plugin/monitoring-console-plugin/perses/perses-dashboard.yaml)
##### Port forward Perses Datasource
To use the PERSES_DATASOURCE you deployed above, you'll need to forward it to your local machine then proxy it using the local Perses Instance.
```
# Forward cluster Prometheus Instance to localhost:9090
oc port-forward -n openshift-monitoring service/prometheus-operated 9090:9090
# Test is port-forward returns Prometheus data from query 'up'
curl "http://localhost:9090/api/v1/query?query=up"
```
Adjust Perses local instance http://localhost:8080/ to use the a proxy to http://localhost:9090/ instead of http://demo.prometheus.io.
#### Local Development with the Logging View (LokiStack)
The logging view runs under the `monitoring-console-plugin` identity and is
not part of any default feature set. To test it locally against a cluster that
runs a LokiStack (for example one set up with
[development-tools](https://github.com/observability-ui/development-tools/blob/main/logging/setup-logging-stack.sh)):
```
# In a separate terminal: forward the LokiStack gateway; start-console.sh
# proxies https://logging-loki-gateway-http.openshift-logging.svc:8080 to it
oc -n openshift-logging port-forward svc/logging-loki-gateway-http 8080:8080
# Frontend under the console-plugin identity (manifest name + i18n namespace)
make start-mcp-frontend
# Backend with logging enabled (not in MONITORING_FEATURES by default)
make start-coo-backend
# Console bridge
make start-coo-console
```
`start-console.sh` fetches the cluster's service CA so the bridge can verify
the gateway's TLS certificate and registers
`/api/proxy/plugin/monitoring-console-plugin/loki/` for it. Override
`LOKI_HOST`, `LOKI_NAME` or `LOKI_NAMESPACE` for non-default LokiStacks, e.g.
`LOKI_HOST=http://localhost:3100` for a plain-HTTP local Loki.