Status reporting v2#36
Conversation
tuomasjjrasanen
force-pushed
the
35-status-reporting-v2
branch
9 times, most recently
from
d47c42e to
429d0f2
Compare
tuomasjjrasanen
force-pushed
the
35-status-reporting-v2
branch
from
429d0f2 to
411aedb
Compare
Adds aux/generate_status_report_docs.py which reads the StatusReport Pydantic schema and renders docs/status_report.md with field tables, type links, nullable markers, and enum listings.
- Traverse $defs depth-first so tables appear in top-down order - Include field descriptions from Pydantic Field(..., description=...) - Handle dict-with-typed-values (additionalProperties) type rendering - Regenerate docs/status_report.md against updated v2 schema
Sections are now rendered with heading levels that reflect their depth in the schema tree (## root, ### depth-1, #### depth-2, etc.). Enums are placed inline at their natural depth rather than collected at the end.
From a producer's perspective, fields with default values are always present in the serialized output even though they are absent from the JSON Schema required array. The column now reflects this correctly: a field is always present if it is in required OR has a default.
Add Field(examples=[...]) to all scalar fields in the StatusReport schema hierarchy, sourced from status_report_v2_example*.json. The doc generator picks up the examples key from the JSON schema and renders the first value in a new Example column.
…r null' for nullable types
The mapping of exam title → stats is replaced with a flat list of stats objects each carrying their own title field, making the structure more uniform with the rest of the schema.
tuomasjjrasanen
force-pushed
the
35-status-reporting-v2
branch
from
a86bd9e to
01f6f5e
Compare
| is_active: pydantic.StrictBool = Field(examples=[True]) | ||
| is_idle: pydantic.StrictBool = Field(examples=[False]) | ||
| is_connected: pydantic.StrictBool = Field(examples=[True]) | ||
| is_waiting_for_auth: pydantic.StrictBool = Field(examples=[False]) | ||
| is_finished: pydantic.StrictBool = Field(examples=[False]) | ||
| status: pydantic.StrictStr = Field(examples=["waiting-for-auth-browser"]) |
There was a problem hiding this comment.
Saisiko näitä yhdistettyä seuraavasti (ei oikealla syntaksilla, vaan kuvaus sisällöstä):
is_connected: [true,false]
status: ["active","idle","waiting-for-auth","finished"]
Eli ajatuksena, että statusdatassa KTP Controller lähettäisi mahdollisimman yksiselitteisen oman näkemyksensä tilanteesta.
There was a problem hiding this comment.
Tuossa ehkä pieni looginen ero/onglema muodostuu siitä että nuo statukset eivät ole täysin toisiaan poissulkevia: is_idle voinee olla true minkä tahansa muun kanssa samanaikaisesti.
is_idle siis vaan määritelmällisesti yli 30min Abitti2:n raportoimasta opiskelijakohtaisesti updateTime:stä.
En osaa varmaksi sanoa milloin tuo updateTime on mukana datassa ja milloin ei, tai milloin varmuudella Abitti2 sitä alkaa ylläpitämään ja milloin ei.
Esim. mitä jos is_idle on true ja is_waiting_for_auth on true.
Pointti se, että suoraan ei voi muuttaa noita erillisiksi tiloiksi, mutta jos me määritellään noille tässä rajat, niin silloin toki voi.
Esim. joku presedenssi tilatulkinnalle, esim. finished > waiting for auth > idle > active
There was a problem hiding this comment.
Ja status voisi olla sitten myös null, mikäli status-tietoa ei ole pystytty tulkitsemaan syystä tai toisesta
There was a problem hiding this comment.
Ja onhan tuo erillinen is_connected myös varmaan vaikeasti tulkittava. Tai mitä sillä tiedolla pitäisi Koejakajalla tehdä? Mitä jos Abitti2 ilmoittaa is_disconnected, mutta ei ole idle. Onko silloin opiskelijalla kaikki kunnossa koska on active (vaikka onkin disconnected)?
Tässä varmaan pääasiallisesti haetaan tietoa että onko opiskelijalla kaikki kunnossa, eikö?
No, finished on kunnossa, riippumatta connected-tilasta. Ja ainoa toinen kunnossa oleva tila on kun opiskelija on is_connected true, mutta ei ole mitään muuta indikaatiota mistään häiritsevästä. Sitten muuten is_connected false on vähän huolestuttavaa, samaten nuo kaikki muut, waiting for auth ja idle.
Eli pitäisikö kuitenkin yrittää esittää Koejakajalle opiskelijasta:
has_finished: true | false
troubles: ['disconnected', 'idle', 'waiting for auth']
Ja jos troubles on tyhjä, niin kaikki on kunnossa
| supervisor_username: pydantic.StrictStr | ||
| supervisor_passphrase: pydantic.StrictStr | None | ||
| version: pydantic.StrictStr | None | ||
| last_message_received_at: ktp_controller.pydantic.DateTime | None |
There was a problem hiding this comment.
Näihin tietoihin jos saisi mukaan myös KTP Controllerin tulkinnan websocket-yhteyden tilasta.
websocket_active: [true,false]
There was a problem hiding this comment.
KTP Controllerilla on kolme erillista websocket-yhteyttä:
1 Abitti2:een
1 Koejakajaan
1 omaan APIinsa
Voisin oikeastaan kaikista raportoida, koska ongelma minkä tahansa kanssa näistä on indikaatio ongelmista.
Se sanottuna, mitä jos raportoisin ne samantyyppisellä stats-tietueella kuin muitakin tietoja. Eli jokaiselle kolmelle websocket-yhteydelle voisi tulla tällaiset tietueet:
+##### WebsocketStats
+
+All fields are always present.
+
+| Field | Type | Description | Example | Notes |
+| ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- | ------- | ------------ |
+| `connection_duration_current` | `number` or `null` | Current connection duration. Null means there's no connection at the moment. | | minimum: `0` |
+| `connection_duration_mean` | `number` or `null` | Mean connection duration since the program start. Null means there has been no connections yet. | | minimum: `0` |
+| `connection_duration_stdev` | `number` or `null` | Standard deviation of all connection durations since the program start. Null means there has been no connections yet. | | minimum: `0` |
+| `connection_count` | `integer` | Number connections since the program start. | | minimum: `0` |
2 participants
Changes in nutshell
docs/status_report.md(generated from schema)