[ADP-612] Event Recording Time

Overview

This ADP defines a standard method for implementing event recording time using the CloudEvents Recorded Time Extension.

Guidelines

1. MUST use the CloudEvents Recorded Time Extension to implement event recording time.

2. Event producers MUST set the recordedtime attribute when creating CloudEvents.

3. The recordedtime attribute MUST be a timestamp adhering to the format specified in RFC 3339.

4. The recordedtime SHOULD be equal to or later than the event occurrence time (represented by the time attribute).

5. Intermediaries MUST NOT modify the recordedtime attribute.

6. Event consumers SHOULD be able to process events based on both their occurrence time (time) and recording time (recordedtime).

CloudEvents Recorded Time Extension

The Recorded Time Extension adds one attribute to CloudEvents:

• recordedtime: Timestamp of when the occurrence was recorded in this CloudEvent, i.e., when the CloudEvent was created by a producer.

Example CloudEvent with recordedtime:

{
    "specversion" : "1.0",
    "type" : "com.example.someevent",
    "source" : "/mycontext",
    "id" : "C234-1234-1234",
    "time" : "2023-06-01T10:30:00Z",
    "recordedtime": "2023-06-01T10:30:05Z",
    "data" : {
        "message" : "This event was recorded 5 seconds after it occurred"
    }
}

Implementation Recommendations

• Implement mechanisms to accurately capture and set the recordedtime when creating events.
• Use both time and recordedtime for event ordering and processing when appropriate.
• Consider implementing data versioning or event sourcing patterns to handle cases where events need to be re-recorded or amended.
• Provide clear documentation on the semantics and usage of recordedtime in your system.
• Implement monitoring and alerting based on the difference between time and recordedtime to detect system latencies.

Use Cases

• Bitemporal Data Representation: Enable representation of both when an event occurred and when it was recorded, crucial for certain regulatory and analytical scenarios.
• Latency Monitoring: Measure the time difference between event occurrence and recording to monitor system performance.
• Data Versioning: Use recordedtime to differentiate between multiple records of the same event, useful in event sourcing patterns.
• Reproducible Analytics: Create reproducible datasets by constraining both time and recordedtime in queries.
• Time-based Event Capture: Implement time-intervalled event capture based on the recording time.

Related ADPs

• ADP-602 CloudEvents
• ADP-610 Event Ordering

References

• CloudEvents Recorded Time Extension