docs(gateway): define the fault occurrence timestamps in the REST reference - #678
Open
bburda wants to merge 3 commits into
Open
docs(gateway): define the fault occurrence timestamps in the REST reference#678bburda wants to merge 3 commits into
bburda wants to merge 3 commits into
Conversation
…erence The fault detail response showed first_occurrence and last_occurrence as example values without saying what they mean. The REST reference now describes both where the fault object's fields are described, matching the Fault.msg definitions: first_occurrence marks the start of the current occurrence and is reset when a FAILED event reactivates a CLEARED fault, and last_occurrence advances on FAILED events only.
…estamps The REST reference points at Fault.msg for the occurrence timestamps, but the message reference documents first_occurred and last_occurred, not the extended_data_records names. State the mapping so a reader following the link does not have to work it out.
bburda
marked this pull request as ready for review
September 10, 2026 20:09
mfaferek93
reviewed
Sep 11, 2026
| **Extended Data Records:** | ||
|
|
||
| The ``environment_data.extended_data_records`` object carries the fault's | ||
| occurrence timestamps, which are ``Fault.msg``'s ``first_occurred`` and |
Collaborator
There was a problem hiding this comment.
"under their REST names" reads as if first_occurrence/last_occurrence were the names everywhere. The list route serves the same instants as first_occurred/last_occurred epoch-seconds floats (fault_msg_conversions.cpp:36-37, dto/faults.hpp:52-53); only the detail route renames them and formats ISO-8601 UTC with ms. Worth one sentence: "the list route serves them as first_occurred/last_occurred in epoch seconds; the detail route uses these names in ISO-8601 UTC". The reset rules themselves match sqlite_fault_storage.cpp:724-754.
… which names The list route serves first_occurred and last_occurred in epoch seconds. Only the fault detail route renames them to first_occurrence and last_occurrence and formats them as ISO-8601 UTC. The extended data records section names both.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The fault detail in the REST reference showed
first_occurrenceandlast_occurrenceas example values with no definition.The reference now defines both where the fault object's fields are described.
first_occurrenceis the start of the current occurrence. It is reset when a FAILED event reactivates a CLEARED fault, so it moves withoccurrence_count.last_occurrenceadvances on FAILED events only. The second commit states the mapping toFault.msg'sfirst_occurredandlast_occurred.These are the definitions #618 settled at the message layer. The naming question in #672 stays open.
Issue
Type
Testing
Docs only. From
docs/, both clean:pre-commitpasses.Checklist