Elaborate on timestamps within ingestion (#8538)

Co-authored-by: Ian Vanagas <[email protected]>

contents/docs/data/timestamps.md

@@ -10,8 +10,33 @@ PostHog automatically computes timestamps for captured events, but you can also
 
 - If the payload includes a `timestamp` but no `sent_at` field, then `timestamp` is directly used as the event timestamp.
 
+- If the payload contains `timestamp`, `sent_at`, and `$ignore_sent_at` fields, then `timestamp` is used directly as the event timestamp. Using `$ignore_sent_at` could be useful during historical data imports.
+
 - If `offset` is included in the payload, then this value is interpreted as milliseconds and is subtracted from the capture time recorded by the server to obtain the event timestamp. The first two alternatives have higher priority so `offset` is ignored if `timestamp` is present.
 
 - Finally, as a fallback when no `timestamp` or `offset` are included in the payload, the capture time recorded by the server is used as the event timestamp.
 
-To ensure maximum compatibility with PostHog, `timestamp` and `sent_at` fields should be in `ISO-8601` format like `2023-12-13T15:45:30.123Z` or `YYYY-MM-DDTHH:MM:SSZ`.
+To ensure maximum compatibility with PostHog, `timestamp` and `sent_at` fields should be in `ISO-8601` format like `2023-12-13T15:45:30.123Z` or `YYYY-MM-DDTHH:MM:SSZ`.
+
+> **Note:** `posthog-js` also sends `$time` property, but this isn't used anywhere in the ingestion pipeline.
+
+Here's a flowchart for how event timestamp is computed during ingestion:
+
+```mermaid
+graph TD
+    A[timestamp?] -->|Yes| B[sent_at?]
+    A -->|No| E[offset?]
+    B -->|Yes| F[$ignore_sent_at?]
+    F -->|No| X[timestamp = now + timestamp - sent_at]
+    F -->|Yes| J
+    B -->|No| J
+    E -->|Yes| H[timestamp = now - offset]
+    E -->|No| I[timestamp = now]
+    X --> J[timestamp > now + 23h?]
+    H --> J
+    J -->|No| K[timestamp valid?]
+    J -->|Yes| I
+    K -->|yes| M[return]
+    K -->|No| I
+    I --> M      
+```