Skip to content

Commit 420ba77

Browse files
knopers8knopers8
committed
[doc] Plugin documentation
1 parent 4aba01f commit 420ba77

File tree

1 file changed

+158
-0
lines changed

1 file changed

+158
-0
lines changed

‎core/integration/README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Integration plugins
2+
3+
The integration plugins allow AliECS to communicate with other ALICE services.
4+
A plugin can register a set of callback which can be invoked upon defined environment events (state transitions).
5+
6+
## Plugin system overview
7+
8+
All plugins should implement the [`Plugin`](/core/integration/plugin.go) interface.
9+
See the existing plugins for examples.
10+
11+
In order to have the plugin loaded by the AliECS, one has to:
12+
- add `RegisterPlugin` to the `init()` function in [AliECS core main source](https://github.com/AliceO2Group/Control/blob/master/cmd/o2-aliecs-core/main.go)
13+
- add plugin name in the `integrationPlugins` list and set the endpoint in the AliECS configuration file (typically at `/o2/components/aliecs/ANY/any/settings` in the configuration store)
14+
15+
# Integrated service operations
16+
17+
In this chapter we list and describe the integrated service plugins.
18+
19+
## Bookkeeping
20+
21+
The legacy Bookkeeping plugin sends updates to Bookkeeping about the state of data taking runs.
22+
As of May 2025, Bookkeeping has transitioned into consuming input from the Kafka event service and the only call in use is "FillInfo", which allows ECS to retrieve LHC fill information.
23+
24+
## CCDB
25+
26+
CCDB plugin calls PDP-provided executable which creates a General Run Parameters (GRP) object at each run start and stop.
27+
28+
## DCS
29+
30+
DCS plugin communicates with the ALICE Detector Control System (DCS).
31+
32+
### DCS operations
33+
34+
The DCS integration plugin exposes to the workflow template (WFT) context the
35+
following operations. Their associated transitions in this table refer
36+
to the [readout-dataflow](https://github.com/AliceO2Group/ControlWorkflows/blob/master/workflows/readout-dataflow.yaml) workflow template.
37+
38+
| **DCS operation** | **WFT call** | **Call timing** | **Critical** | **Contingent on detector state** |
39+
|-----------------------|---------------------|---------------------------|--------------|----------------------------------|
40+
| Prepare For Run (PFR) | `dcs.PrepareForRun` | during `CONFIGURE` | `false` | yes |
41+
| Start Of Run (SOR) | `dcs.StartOfRun` | early in `START_ACTIVITY` | `true` | yes |
42+
| End Of Run (EOR) | `dcs.EndOfRun` | late in `STOP_ACTIVITY` | `true` | no |
43+
44+
The DCS integration plugin subscribes to the [DCS service](https://github.com/AliceO2Group/Control/blob/master/core/integration/dcs/protos/dcs.proto) and continually
45+
receives information on operation-state compatibility for all
46+
detectors.
47+
When a given environment reaches a DCS call, the relevant DCS operation
48+
will be called only if the DCS service reports that all detectors in that
49+
environment are compatible with this operation, except EOR, which is
50+
always called.
51+
52+
### DCS PrepareForRun behaviour
53+
54+
Unlike SOR and EOR, which are mandatory if `dcs_enabled` is set to `true`,
55+
an impossibility to run PFR or a PFR failure will not prevent the
56+
environment from transitioning forward.
57+
58+
#### DCS PFR incompatibility
59+
60+
When `dcs.PrepareForRun` is called, if at least one detector is in a
61+
state that is incompatible with PFR as reported by the DCS service,
62+
a grace period of 10 seconds is given for the detector(s) to become
63+
compatible with PFR, with 1Hz polling frequency. As soon as all
64+
detectors become compatible with PFR, the PFR operation is requested
65+
to the DCS service.
66+
67+
If the grace period ends and at least one detector
68+
included in the environment is still incompatible with PFR, the PFR
69+
operation will be performed for the PFR-compatible detectors.
70+
71+
Despite some detectors not having performed PFR, the environment
72+
can still transition forward towards the `RUNNING` state, and any DCS
73+
activities that would have taken place in PFR will instead happen
74+
during SOR. Only at that point, if at least one detector is not
75+
compatible with SOR (or if it is but SOR fails), will the environment
76+
declare a failure.
77+
78+
#### DCS PFR failure
79+
80+
When `dcs.PrepareForRun` is called, if all detectors are compatible
81+
with PFR as reported by the DCS service (or become compatible during
82+
the grace period), the PFR operation is immediately requested to the
83+
DCS service.
84+
85+
`dcs.PrepareForRun` call fails if no detectors are PFR-compatible
86+
or PFR fails for all those which were PFR-compatible,
87+
but since it is non-critical the environment may still reach the
88+
`CONFIGURED` state and transition forward towards `RUNNING`.
89+
90+
As in the case of an impossibility to run PFR, any DCS activities that
91+
would have taken place in PFR will instead be done during SOR.
92+
93+
### DCS StartOfRun behaviour
94+
95+
The SOR operation is mandatory if `dcs_enabled` is set to `true`
96+
(AliECS GUI "DCS" switched on).
97+
98+
#### DCS SOR incompatibility
99+
100+
When `dcs.StartOfRun` is called, if at least one detector is in a
101+
state that is incompatible with SOR as reported by the DCS service,
102+
or if after a grace period of 10 seconds at least one detector is
103+
still incompatible with SOR, the SOR operation **will not run for any
104+
detector**.
105+
106+
The environment will then declare a **failure**, the
107+
`START_ACTIVITY` transition will be blocked and the environment
108+
will move to `ERROR`.
109+
110+
#### DCS SOR failure
111+
112+
When `dcs.StartOfRun` is called, if all detectors are compatible
113+
with SOR as reported by the DCS service (or become compatible during
114+
the grace period), the SOR operation is immediately requested to the
115+
DCS service.
116+
117+
If this operation fails for one or more detectors, the
118+
`dcs.StartOfRun` call as a whole is considered to have failed.
119+
120+
The environment will then declare a **failure**, the
121+
`START_ACTIVITY` transition will be blocked and the environment
122+
will move to `ERROR`
123+
124+
### DCS EndOfRun behaviour
125+
126+
The EOR operation is mandatory if `dcs_enabled` is set to `true`
127+
(AliECS GUI "DCS" switched on). However, unlike with PFR and SOR, there
128+
is **no check for compatibility** with the EOR operation. The EOR
129+
request will always be sent to the DCS service during `STOP_ACTIVITY`.
130+
131+
#### DCS EOR failure
132+
133+
If this operation fails for one or more detectors, the
134+
`dcs.EndOfRun` call as a whole is considered to have failed.
135+
136+
The environment will then declare a **failure**, the
137+
`STOP_ACTIVITY` transition will be blocked and the environment
138+
will move to `ERROR`.
139+
140+
## DD Scheduler
141+
142+
DD scheduler plugin informs the Data Distribution software about the pool of FLPs taking part in data taking.
143+
144+
## Kafka (legacy)
145+
146+
See [Legacy events: Kafka plugin](/docs/kafka.md#legacy-events-kafka-plugin)
147+
148+
## ODC
149+
150+
ODC plugin communicates with the [Online Device Control (ODC)](https://github.com/FairRootGroup/ODC) instance of the ALICE experiment, which controls the event processing farm used in data taking and offline processing.
151+
152+
## Test plugin
153+
154+
Test plugin serves as an example of a plugin and is used for testing the plugin system.
155+
156+
## Trigger
157+
158+
Trigger plugin communicates with the ALICE trigger system.

0 commit comments

Comments
 (0)