Update logging docs for VictoriaLogs migration and app logs API corrections#2407
Update logging docs for VictoriaLogs migration and app logs API corrections#2407lesliebc wants to merge 5 commits into
Conversation
kcmartin
left a comment
There was a problem hiding this comment.
Left a few comments and a suggestion
| - `start_time=2023-08-01T00:00:00Z` (to backfill) | ||
| - `region`: three-letter region code. Returns only logs from this region | ||
| - `instance`: a Machine ID. Returns only logs from this instance | ||
| - `next_token`: a nanosecond Unix timestamp. Returns logs after this time. Each response includes a `meta.next_token` — pass it in your next request to page forward |
There was a problem hiding this comment.
next_token is described as both "a starting timestamp" (user-suppliable) and "pass it in your next request to page forward" (opaque cursor). Can you confirm which is the intended use, and update as needed?
- If users can construct one themselves to backfill from an arbitrary moment: add an example value to the bullet (the old doc had
start_time=2023-08-01T00:00:00Zwhat's the nanosecond equivalent look like?). - If it's only an opaque cursor returned by the previous response: drop "or set a starting timestamp" from the intro sentence on line 40, and rewrite the bullet as something like "an opaque paging cursor returned in
meta.next_tokenof the previous response."
Either way, the rename from start_time (ISO-8601) to next_token (nanosecond Unix) is a breaking change for anyone using the old param. A one-line note calling that out would save existing users some debugging.
There was a problem hiding this comment.
next_token can be used both ways that you described. I think it's primarily a cursor, but you can also approximate backfilling by passing in your own timestamp as next_token. Could the usage be clearer? I also added an example for that param like you suggested. Thanks!
About the previously documented start_time, I don't know that this was working before. I don't see that param in the bubblegum or web code, but I could've missed it. next_token has been in the logging code for a long time - I think this was always the supported way to backfill and page through logs, before and since migrating to VictoriaLogs.
Edit: I added a bullet after next_token stating that it replaces start_time to avoid confusion. Let me know if anything should be tweaked. Happy to update.
kcmartin
left a comment
There was a problem hiding this comment.
Thanks for the updates. There is one minor suggestion for clarity + fixing a typo, otherwise LGTM!
| - `start_time=2023-08-01T00:00:00Z` (to backfill) | ||
| - `region`: three-letter region code. Returns only logs from this region | ||
| - `instance`: a Machine ID. Returns only logs from this instance | ||
| - `next_token`: a nanosecond Unix timestamp (e.g `1779235200000000000`). Returns logs after this time. Each response includes a `meta.next_token` — pass it in your next request to page forward |
There was a problem hiding this comment.
Could we make the dual purpose of next_token (cursor + timestamp backfill) explicit in the bullet? Something like:
| - `next_token`: a nanosecond Unix timestamp (e.g `1779235200000000000`). Returns logs after this time. Each response includes a `meta.next_token` — pass it in your next request to page forward | |
| - `next_token`: a nanosecond Unix timestamp (e.g. `1779235200000000000`) used either as a paging cursor or to backfill from a specific moment. Returns logs after this time. Each response includes a `meta.next_token` that you can pass in your next request to page forward. |
Summary of changes
Updates logging docs to reflect migration from Quickwit to VictoriaLogs. References to Quickwit are replaced with VictoriaLogs, and our log retention period is updated to 7 days.
Also makes a few changes to the app logs endpoint doc:
start_timewithnext_tokenin supported query params