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 4 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.
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