Skip to content

docs: clarify audit log filtering behavior.#9871

Open
jmcarp wants to merge 1 commit intomainfrom
jmcarp/audit-log-docs
Open

docs: clarify audit log filtering behavior.#9871
jmcarp wants to merge 1 commit intomainfrom
jmcarp/audit-log-docs

Conversation

@jmcarp
Copy link
Contributor

@jmcarp jmcarp commented Feb 17, 2026

Clarify that the start_time query parameter applies to time_completed, not time_started. This is a bit confusing otherwise, because an inattentive user might assume that start_time filters on time_started, since they sound alike.

Feel free to close if too nit-picky. I was reading the docs and wanted to check the code to be sure of the behavior, even though this is really the only behavior that would make sense.

@jmcarp jmcarp requested a review from david-crespo February 17, 2026 20:06
Copy link
Contributor

@sudomateo sudomateo left a comment

Choose a reason for hiding this comment

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

You'll need to regenerate the OpenAPI specification since that's what's used to generate the documentation.

#[derive(Deserialize, JsonSchema, Serialize, PartialEq, Debug, Clone)]
pub struct AuditLog {
/// Required, inclusive
/// Start of time range (inclusive). Filters on `time_completed`.
Copy link
Contributor

Choose a reason for hiding this comment

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

This query parameter is indeed required but not marked as required in the OpenAPI specification so it doesn't have the required badge on the rendered site. I think this is a dropshot bug?

Image
> curl https://oxide.sys.r3.oxide-preview.com/v1/system/audit-log
{
  "request_id": "7fb4332d-c9f4-4400-a863-d78749965d79",
  "message": "unable to parse query string: missing field `start_time`"
}

Clarify that the `start_time` query parameter applies to `time_completed`, not
`time_started`. This is a bit confusing otherwise, because an inattentive user
might assume that `start_time` filters on `time_started`, since they sound
alike.
@jmcarp jmcarp force-pushed the jmcarp/audit-log-docs branch from 5e9c09a to 0b38300 Compare February 19, 2026 00:24
@jmcarp
Copy link
Contributor Author

jmcarp commented Feb 19, 2026

Bumped the version to get a new openapi doc:

joshcarp@j0sh ~/c/omicron (jmcarp/audit-log-docs)> diff openapi/nexus/nexus-2026021800.0.0-0ebeea.json openapi/nexus/nexus-2026021301.0.0-6e51ab.json
10c10
<     "version": "2026021800.0.0"
---
>     "version": "2026021301.0.0"
7623c7623
<         "description": "A single item in the audit log represents both the beginning and end of the logged operation (represented by `time_started` and `time_completed`) so that clients do not have to find multiple entries and match them up by request ID to get the full picture of an operation. Because timestamps may not be unique, entries have also have a unique `id` that can be used to deduplicate items fetched from overlapping time intervals.\n\nAudit log entries are designed to be immutable: once you see an entry, fetching it again will never get you a different result. The list is ordered and filtered by `time_completed`, not `time_started`. If you fetch the audit log for a time range that is fully in the past, the resulting list is guaranteed to be complete, i.e., fetching the same timespan again later will always produce the same set of entries.",
---
>         "description": "A single item in the audit log represents both the beginning and end of the logged operation (represented by `time_started` and `time_completed`) so that clients do not have to find multiple entries and match them up by request ID to get the full picture of an operation. Because timestamps may not be unique, entries have also have a unique `id` that can be used to deduplicate items fetched from overlapping time intervals.\n\nAudit log entries are designed to be immutable: once you see an entry, fetching it again will never get you a different result. The list is ordered by `time_completed`, not `time_started`. If you fetch the audit log for a time range that is fully in the past, the resulting list is guaranteed to be complete, i.e., fetching the same timespan again later will always produce the same set of entries.",
7629c7629
<             "description": "End of time range (exclusive). Filters on `time_completed`.",
---
>             "description": "Exclusive",
7666c7666
<             "description": "Start of time range (inclusive). Filters on `time_completed`.",
---
>             "description": "Required, inclusive",

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