Skip to content

Update logging docs for VictoriaLogs migration and app logs API corrections#2407

Open
lesliebc wants to merge 4 commits into
mainfrom
update-logging-docs
Open

Update logging docs for VictoriaLogs migration and app logs API corrections#2407
lesliebc wants to merge 4 commits into
mainfrom
update-logging-docs

Conversation

@lesliebc
Copy link
Copy Markdown
Contributor

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:

  • Changes API response format from newline-delimited JSON stream to JSON:API document
  • Replaces start_time with next_token in supported query params
  • Documents endpoint's default behaviour

@lesliebc lesliebc requested a review from kcmartin May 25, 2026 14:03
Copy link
Copy Markdown
Contributor

@kcmartin kcmartin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few comments and a suggestion

Comment thread monitoring/logs-api-options.html.md
Comment thread monitoring/search-logs.html.markerb Outdated
Comment thread monitoring/logs-api-options.html.md Outdated
- `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
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:00Z what'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_token of 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread monitoring/search-logs.html.markerb
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants