Reworking LVAlert types and contents
There is a need to add more finely divided categories for LVAlerts and possibly change the type of serialized objects which are included with them. Should more/different information be added as well?
Current status
Contents of alert JSON packet
Currently, LVAlert JSON packets include the following keys:
- object: dict representation of a database row; typically an event, superevent, or log object. Note that these should be identical to the representation of these object available from the API.
- description: text description of the action which triggered the alert
- uid: event graceid or superevent id
- alert_type: either "new", "label", "update", or "signoff"
- labels: list of label names attached to the event or superevent
- file: filename string (optional and relative)
Actions for which GraceDB issues alerts
GraceDB issues LVAlerts when the following actions are taken:
Events
Constants:
- uid: always the related event's graceid
- labels: always a list of the related event's labels
| Action | alert_type | object | file | description |
|---|---|---|---|---|
| Event creation | "new" | event | Link to initial event file | "" |
| Event log creation (no file) | "update" | log | "" | "LOG: comment" |
| Event log creation (with file) | "update" | log | filename | "UPLOAD: 'filename' comment" |
| Label added to event | "label" | Not included in dict | "" | H1OK |
| Label removed from event | "update" | Not included in dict | "" | "Label H1OK removed" |
| VOEvent created for event | "update" | voevent | G0001-3-Update.xml | "VOEVENT: G0001-3-Update.xml" |
| EM observation created for event | "update" | emobservation | "" | "New EMBB observation record." |
| EMBB event log created for event | "update" | embb event log | "" | "New EMBB event log entry." |
| Event added to superevent | "update" | log | "" | "LOG: Added to superevent S180614b" |
| Event removed from superevent | "update" | log | "" | "LOG: Removed from superevent S180614b" |
| Event selected as preferred event for superevent | "update" | log | "" | "LOG: Set as preferred event for superevent: S180614b" |
| Event removed as preferred event for superevent | "update" | log | "" | "LOG: Removed a preferred event for superevent: S180614b" |
| Operator or advocate signoff (initial or update) on event | "signoff" | signoff | "" | "OK" or "NO" |
Superevents
Constants:
- uid: always the related superevent's superevent_id
- labels: always a list of the related superevent's labels
| Action | alert_type | object | file | description |
|---|---|---|---|---|
| Superevent creation | "new" | superevent | "" | "NEW: superevent S180614a" |
| Superevent update (preferred event, t_start, t_0, t_end) | "update" | log | "" | "LOG: Updated superevent parameters: t_0: 1 -> 2, preferred_event: G0001 -> G0002" |
| Log creation (no file) | "update" | log | "" | "LOG: comment" |
| Log creation (with file) | "update" | log | filename | "UPLOAD: 'filename' comment" |
| Event added to superevent | "update" | log | "" | "LOG: Added event: G0001" |
| Event removed from superevent | "update" | log | "" | "LOG: Removed event: G0001" |
| Label added to superevent | "label" | Not included in dict | "" | "LABEL: H1OK" |
| Label removed from superevent | "update" | Not included in dict | "" | "UPDATE: H1OK removed" |
| Confirm superevent as GW | "update" | log | "" | LOG: Confirmed as a gravitational wave." |
| Create VOEvent for superevent | "update" | voevent | S180614b-3-Update.xml | "VOEVENT: S180614b-3-Update.xml" |
| Create EMObservation for superevent | "update" | emobservation | "" | "New EMBB observation record for DESGW." |
| Operator or advocate signoff (initial or update) on superevent | "signoff" | signoff | "" | "OK" or "NO" |
| Operator or advocate signoff deleted | "update" | log | "" | "LOG: operator signoff for H1 deleted: H1OK removed and H1OPS reapplied" |
Note that there are no EMBB event logs for superevents since they seem to have fallen out of use (there were only ever 31 of them created and the last one was applied for events in ~2015).
Actions for which GraceDB does not issue alerts
LVAlerts are not issued when the following actions occur:
- Event created with labels attached ("new" alert goes out but no "label" alert; this probably should happen)
- Note that superevents created with labels first issue "new" alerts and then "label" alerts
- Event "replaced" with new event file (should probably send an "update" alert)
- An event signoff is deleted.
- An event log or superevent log has a tag applied or removed (I don't think anyone wants to get this alert)
- A log message is generated to document the above action (I don't think anyone wants to get this alert)
Development action items
We want to do the following:
- Define some new alert_type categories and what actions they should be used for.
- Add alerts for some of the actions listed above.
- Change what type of serialized object is included with certain alerts
- Add documentation of alert contents and actions which trigger them
We might want to:
- Add entirely new information to alerts (i.e., new dict key(s) and value(s))
To upload designs, you'll need to enable LFS. More information