Skip to content

Commit 0ab76bf

Browse files
gradutagraduta
authored
Merge branch 'dev' into dependabot/npm_and_yarn/QualityControl/form-data-4.0.6
2 parents 0a0a22e + 6ffc7cf commit 0ab76bf

2 files changed

Lines changed: 157 additions & 77 deletions

File tree

‎InfoLogger/README.md‎

Lines changed: 157 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -3,108 +3,188 @@
33
[![Actions Status](https://github.com/AliceO2Group/WebUi/workflows/InfoLogger/badge.svg)](https://github.com/AliceO2Group/WebUi/actions)
44
[![codecov](https://codecov.io/gh/AliceO2Group/WebUi/branch/dev/graph/badge.svg?flag=infologger)](https://codecov.io/gh/AliceO2Group/WebUi)
55

6+
## Contents
7+
68
- [InfoLogger GUI (ILG)](#infologger-gui-ilg)
9+
- [Contents](#contents)
10+
- [Introduction](#introduction)
711
- [Interface User Guide](#interface-user-guide)
812
- [Requirements](#requirements)
9-
- [Installation](#installation)
10-
- [Dummy InfoLogger test server](#dummy-infologger-test-server)
11-
- [InfoLogger insights](#infologger-insights)
12-
- [Continuous Integration Workflows](#continuous-integration-workflows)
13+
- [Project Layout](#project-layout)
14+
- [Backend](#backend)
15+
- [Frontend](#frontend)
16+
- [Local Development](#local-development)
17+
- [First-time setup](#first-time-setup)
18+
- [Query \& Live mode Against a remote backend (e.g. a staging instance)](#query--live-mode-against-a-remote-backend-eg-a-staging-instance)
19+
- [Live mode against synthetic logs (thoroughly test Live mode)](#live-mode-against-synthetic-logs-thoroughly-test-live-mode)
20+
- [Query against a local DB](#query-against-a-local-db)
21+
- [Testing](#testing)
22+
- [Integration tests (now run elsewhere)](#integration-tests-now-run-elsewhere)
23+
- [CI](#ci)
1324
- [infologger.yml](#infologgeryml)
1425
- [release.yml](#releaseyml)
26+
- [system-configuration pipeline](#system-configuration-pipeline)
27+
- [InfoLogger Insights](#infologger-insights)
28+
29+
## Introduction
1530

16-
Web user interface of [InfoLogger](https://github.com/AliceO2Group/InfoLogger) logging system.
31+
The Web User Interface for [**ALICE O2 InfoLogger**](https://github.com/AliceO2Group/InfoLogger). The application operates in two distinct modes:
1732

18-
It interfaces with the system using two modes:
33+
- **Query** - historical logs from a database.
34+
- **Live** - real-time logs from a TCP endpoint over the InfoLogger protocol.
1935

20-
- **Query**: Querying historical logs from a database
21-
- **Live**: Receiving Real-Time logs from a TCP endpoint over InfoLogger protocol (v1.3, v1.4)
36+
Screenshot of the current interface, running locally against a fake InfoLoggerServer emitting synthetic logs:
2237

2338
![Screenshot of ILG](docs/screenshot.png)
2439

2540
## Interface User Guide
41+
2642
- Use upper panel to:
27-
- match and/or exclude filters (Supports SQL Wildcard `%`)
43+
- match and/or exclude filters (Supports SQL Wildcard `%`, empty value toggling)
44+
- control the zoom level of the log table
2845
- limit the number of logs displayed
2946
- match severity and level
3047
- reset the filters
3148
- Show/hide columns by clicking on labels on top of page
3249
- Click "Query" or "Live" button to start the respective mode
3350
- Double click on a log or toggle the inspector view from the bottom right corner to see all fields of the log
34-
- Use arrows keys to navigate quickly between logs
51+
- Right-click a log to open a context menu with copy / use-as-filter / open inspector actions
52+
- Use arrow keys to navigate quickly between logs
3553
- Download the logs in a file via the top left download icon
3654

3755
## Requirements
38-
- `nodejs` >= `16.x`
56+
57+
- `nodejs` >= `22.x`
3958
- InfoLogger MariaDB database for Query mode
4059
- InfoLoggerServer endpoint for Live mode
4160

42-
## Installation
43-
1. `git clone https://github.com/AliceO2Group/WebUi.git; cd WebUi/InfoLogger`
44-
2. `npm install --prod`
45-
3. `cp config-default.js config.js`
46-
4. Modify `config.js` file to set InfoLogger database and endpoint details
47-
5. Start web app: `npm start`
48-
6. Open browser and navigate to http://localhost:8080
49-
50-
## Development database installation
51-
In order to run queries in the InfoLogger a MariaDB server is required. To run a local MariaDB server that can easily be updated/wiped/configured you will need Docker installed.
52-
1. Follow the instructions specific for you platform: [docker desktop install](https://www.docker.com/products/docker-desktop/)
53-
2. Create a `compose.yaml` file somewhere on your pc with the following content:
54-
```
55-
services:
56-
mariadb:
57-
image: mariadb
58-
restart: unless-stopped
59-
ports:
60-
- 3306:3306
61-
environment:
62-
MARIADB_ROOT_PASSWORD: root
63-
# (this is just an example, not intended to be a production configuration)
64-
phpmyadmin:
65-
image: phpmyadmin
66-
restart: unless-stopped
67-
ports:
68-
- 9090:80
69-
environment:
70-
- PMA_HOST=mariadb
71-
```
72-
This will get you a MariaDB server with phpmyadmin.
73-
Should you ever feel the need to test a specific version of MariaDB then change the image to `mariadb:11.5` where 11.5 is the version. By default the compose.yaml will get you the latest MariaDB image.
74-
75-
3. Execute the following command in the same directory as the compose.yaml file: `docker compose up -d` this will start the containers and the `-d` parameter makes sure you can close your commandline window by running in daemon mode.
76-
4. You should now be able to visit `http://localhost:9090/` in your browser of choice, enter user and password root to login.
77-
5. Create the `INFOLOGGER` database by clicking `New` in the phpMyAdmin UI on the left side.
78-
6. In the phpMyAdmin UI select `SQL` on the top of the page. Then enter the contents of the `InfoLogger/docs/database-specs.sql` file in the field and pressing the `Go` button.
79-
7. Edit `config.js` to point to your local database:
80-
```
81-
mysql: {
82-
host: '127.0.0.1',
83-
user: 'root',
84-
password: 'root',
85-
database: 'INFOLOGGER',
86-
port: 3306,
87-
timeout: 60000,
88-
retryMs: 5000,
89-
},
61+
## Project Layout
62+
63+
ILG is a Node.js API Gateway and Single-Page Application built on top of the `@aliceo2/web-ui` framework. It serves as a unified interface to two separate operational backends: a **MariaDB database** for historical queries and an **InfoLoggerServer TCP endpoint** for live log streaming.
64+
65+
## Backend
66+
67+
- **Entry point** - [index.js](index.js) starts the `HttpServer` from `@aliceo2/web-ui` and attaches a `WebSocket`. [lib/api.js](lib/api.js) instantiates the services, wires them to the DB and InfoLoggerServer, and registers HTTP routes. Config is loaded by [configProvider.js](lib/configProvider.js).
68+
- **Query** - `POST /query` and `GET /query/stats` → [QueryController](lib/controller/QueryController.js) → [QueryService](lib/services/QueryService.js). Both routes are gated by [serviceAvailabilityCheck](lib/middleware/serviceAvailabilityCheck.middleware.js).
69+
- **Live** - [LiveService](lib/services/LiveService.js) wraps `InfoLoggerReceiver`, parses each TCP line per the [InfoLogger protocol](docs/il-protocol.md), and broadcasts to connected clients over WebSocket.
70+
- **Status / Config** - [StatusController](lib/controller/StatusController.js) reports DB / Server / GUI health; [ConfigController](lib/controller/ConfigController.js) exposes the runtime config to the frontend.
71+
- **Profiles** - [ProfileService](lib/ProfileService.js) persists per-user column visibility/width to a JSON file ([JSONFileConnector](lib/JSONFileConnector.js)) via `getUserProfile` / `saveUserProfile`. The named-profile endpoint (`getProfile`) is a stub - it returns the hard-coded defaults regardless of the profile requested.
72+
- **Utilities** - [utils/](lib/utils/) contains the InfoLogger message-command parser, SQL to native error mapping, prepared-statement parsing, and query cancellation.
73+
74+
## Frontend
75+
76+
Static files served from [public/](public/); no build step. A lightweight MVC app on top of `@aliceo2/web-ui`.
77+
78+
- **App shell** - [index.html](public/index.html) bootstraps [index.js](public/index.js), which mounts the top-level [Model](public/Model.js) and renders [view.js](public/view.js).
79+
- **Sub-models** - [log/Log.js](public/log/Log.js) drives the log table (rendering in `tableLogs*.js`, inspector, status bar, context menu, zoom, etc.). [logFilter/LogFilter.js](public/logFilter/LogFilter.js) owns the filter inputs. [table/Table.js](public/table/Table.js) holds shared table state.
80+
- **Supporting code** - [services/](public/services/), [constants/](public/constants/), [common/](public/common/), [about/](public/about/) (about component).
81+
- **Styles** - [app.css](public/app.css), layered on the framework's [bootstrap.css](../Framework/Frontend/css/src/bootstrap.css).
82+
83+
## Local Development
84+
85+
### First-time setup
86+
87+
```bash
88+
git clone https://github.com/AliceO2Group/WebUi.git
89+
cd WebUi/InfoLogger
90+
npm ci
91+
cp config-default.js config.js
9092
```
91-
8. Run the InfoLogger and check for the following message in the console: `info: Connection to DB successfully established: 127.0.0.1:3306`
92-
93-
## Dummy InfoLogger test server
94-
InfoLoggerServer can be simulated by running `npm run simul`. The dummy server binds `localhost:6102` endpoint.
95-
## InfoLogger insights
96-
- [Message protocol](docs/il-protocol.md)
97-
- [Database structure](docs/database-specs.sql)
98-
99-
## Continuous Integration Workflows
100-
InfoLogger project makes use of two workflows.
101-
### [infologger.yml](./../.github/workflows/infologger.yml)
102-
* Checks that tests of the project are running successfully on two virtual machines:
103-
* `ubuntu`
104-
* `macOS`
105-
* Make sure that the proposed changes are not reducing the current code-coverage percent
106-
* Sends a code coverage report to [CodeCov](https://codecov.io/gh/AliceO2Group/WebUi)
93+
94+
Edit `config.js` for the setup you're using below.
95+
96+
`npm run dev` runs the backend under nodemon. The frontend has no hot reload - refresh the browser to pick up changes.
97+
98+
### Query & Live mode Against a remote backend (e.g. a staging instance)
99+
100+
1. Point `mysql` and `infoLoggerServer` in `config.js` at the remote host and port.
101+
2. `npm start`, then open [http://localhost:8080](http://localhost:8080).
102+
103+
### Live mode against synthetic logs (thoroughly test Live mode)
104+
105+
The bundled [fake InfoLoggerServer](test/live-simulator/) emits a log every 0-100 ms, shuffling through [test/live-simulator/fakeData.json](test/live-simulator/fakeData.json).
106+
107+
1. Set `infoLoggerServer` in `config.js` to `localhost:6102`.
108+
2. Terminal 1: `npm run simul`.
109+
3. Terminal 2: `npm run dev`.
110+
4. Open [http://localhost:8080](http://localhost:8080) and click **Live**.
111+
112+
### Query against a local DB
113+
114+
Requires [Docker Desktop](https://www.docker.com/products/docker-desktop/).
115+
116+
1. In a working dir, create `compose.yaml`:
117+
118+
```yaml
119+
services:
120+
mariadb:
121+
image: mariadb
122+
restart: unless-stopped
123+
ports: ['3306:3306']
124+
environment:
125+
MARIADB_ROOT_PASSWORD: root # this is just an example, not intended to be a production configuration
126+
phpmyadmin:
127+
image: phpmyadmin
128+
restart: unless-stopped
129+
ports: ['9090:80']
130+
environment:
131+
- PMA_HOST=mariadb
132+
```
133+
134+
Gives you a MariaDB server with phpMyAdmin on the latest image. Pin a specific version (e.g. `mariadb:11.5`) by changing the `image:` tag.
135+
136+
2. `docker compose up -d`.
137+
3. Open [http://localhost:9090/](http://localhost:9090/) → log in `root` / `root` → **New** → create database `INFOLOGGER`.
138+
4. Open the **SQL** tab, paste [docs/database-specs.sql](docs/database-specs.sql), click **Go**.
139+
5. In `config.js`:
140+
141+
```js
142+
mysql: {
143+
host: '127.0.0.1',
144+
user: 'root',
145+
password: 'root',
146+
database: 'INFOLOGGER',
147+
port: 3306,
148+
timeout: 60000,
149+
retryMs: 5000,
150+
},
151+
```
152+
153+
6. `npm run dev` - startup should log `Connection to DB successfully established: 127.0.0.1:3306`.
154+
155+
## Testing
156+
157+
- `npm test` - eslint + mocha. `npm run mocha` runs the suite alone.
158+
- Backend tests: [test/lib/](test/lib).
159+
- Frontend tests: [test/public/](test/public).
160+
- Add or update the matching test when fixing a bug.
161+
- `npm run eslint` - config in [eslint.config.js](eslint.config.js). Lint failures block CI.
162+
163+
### Integration tests (now run elsewhere)
164+
165+
ILG integration tests live in the **system-configuration** repo and run in its pipeline against a pipeline ILG. They are **not** executed by this repo's CI. To run them locally, clone system-configuration and run `npx mocha ilg-main.js`.
166+
167+
> ⚠️ Files under [test/integration/](test/integration) here are a historical FLP-Suite copy, unmaintained for years. If you change behaviour covered by integration tests, update the system-configuration suite during the next ILG release.
168+
169+
## CI
170+
171+
### [infologger.yml](../.github/workflows/infologger.yml)
172+
173+
Runs on every PR touching `InfoLogger/**`. Must pass to merge:
174+
175+
- `npm test` (eslint + mocha) on `ubuntu-latest`.
176+
- `npm run coverage` with a CodeCov report; **coverage cannot decrease**.
107177

108178
### [release.yml](../.github/workflows/release.yml)
109-
* Releases a new version of the project to the [NPM Registry](npmjs.com/) under the tag [@aliceo2/infologger](https://www.npmjs.com/package/@aliceo2/infologger)
110-
* Builds a `tgz` file which contains an archive of the project. This can be used for local repositories installations.
179+
180+
- Publishes a new version to the [NPM Registry](https://www.npmjs.com/) under [@aliceo2/infologger](https://www.npmjs.com/package/@aliceo2/infologger).
181+
- Builds a `tgz` archive of the project for local-repository installations.
182+
183+
### [system-configuration pipeline](https://gitlab.cern.ch/AliceO2Group/system-configuration)
184+
185+
Runs the integration suite against a pipeline instance. Runs separately from this repo's CI, so run the suite locally before merging and flag any required changes to the team at release time.
186+
187+
## InfoLogger Insights
188+
189+
- [InfoLogger message protocol](docs/il-protocol.md)
190+
- [Database schema](docs/database-specs.sql)

‎InfoLogger/docs/screenshot.png‎

761 KB
Loading

0 commit comments

Comments
 (0)