Add container log retrieval options#1592
Open
chrisgeo wants to merge 1 commit into
Open
Conversation
968134b to
77a21ed
Compare
…ient.logs
Adds an additive overload to ContainerClient.logs that accepts a
ContainerLogOptions { since: Date?, timestamps: Bool } and plumbs the
two parameters through XPC into the daemon's existing log-handle path.
Motivation
----------
External orchestrators that drive the API server (the canonical use
case is a Compose-spec orchestrator implementing 'compose logs --since
<timestamp>' and '--timestamps') need to retrieve only recent log
output and optionally annotate lines with timestamps. Today
ContainerClient.logs(id:) returns raw containerLog + bootlog file
handles unconditionally; consumers either replay the entire log buffer
or implement their own line-by-line filter on the client. Surfacing
the parameters at the API boundary keeps the line scanning where the
file lives — server-side — and matches the docker-compose UX users
expect.
What this PR changes
--------------------
- Sources/ContainerResource/Container/ContainerLogOptions.swift (new):
the ContainerLogOptions struct, Sendable + Codable, with a static
'.default' equivalent to the original logs(id:) zero-config call.
- Sources/Services/ContainerAPIService/Client/XPC+.swift: two new
XPCKeys cases ('logSince', 'logTimestamps') for the optional
parameters.
- Sources/Services/ContainerAPIService/Client/ContainerClient.swift:
new logs(id:options:) overload. The existing logs(id:) is retained
as a thin wrapper over .default for source compatibility.
- Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift:
matching logs(id:options:) overload; when options.since is provided,
applies a private 'filterFileHandleSince' that parses ISO-8601
timestamps from line starts and drops older lines (lines without a
parseable timestamp pass through unchanged).
- Sources/Services/ContainerAPIService/Server/Containers/ContainersHarness.swift:
parses the two optional XPC keys, builds ContainerLogOptions, and
forwards to the new service overload.
Wire compatibility
------------------
XPC calls without the new keys decode as 'sinceRaw.timeIntervalSince1970
== 0' (the harness treats this as 'no since filter') and 'timestamps =
false', so older clients hitting a newer server see unchanged behavior.
Newer clients hitting an older server send the keys; an old harness
will silently drop them and run the original codepath.
Known limitations (intentional, follow-up work)
-----------------------------------------------
- The 'options.timestamps' parameter is plumbed end-to-end but the
daemon does not currently decorate raw log lines that lack a
timestamp prefix. Line decoration is a deliberate follow-up; keeping
the parameter on the API surface today avoids a second wire-format
break later.
- 'filterFileHandleSince' currently slurps the file into memory then
returns a Pipe-backed FileHandle. For the typical container log
size this is fine; for very large logs a streaming line iterator
would be a worthwhile optimization. Filed as a known-issue for the
follow-up timestamp-decoration PR.
Verification
------------
Full 'swift build' clean on macOS 26 / Apple silicon (release config,
all targets including downstream consumers of ContainerClient.logs).
77a21ed to
3dac6d5
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Type of Change
Motivation and Context
Add a source-compatible log options API for
ContainerClient.logsso API clients can request recent log output and forward timestamp preferences through the existing XPC log route.External orchestrators that implement compose-style log commands need
--sinceand--timestampsbehavior without replaying and filtering the full log stream downstream. This change introducesContainerLogOptions, preserves the existinglogs(id:)default behavior, and plumbs the options through the client, XPC harness, and container service.The
sinceoption filters ISO-8601-prefixed lines before file handles are returned. Lines without a parseable timestamp are preserved. Thetimestampsoption is forwarded through the API boundary as a hint; decorating raw log lines that lack timestamps remains future work.Resolves #1591.
Testing
Local verification:
swift buildswift test --filter ContainerLogsTestsswift test --filter ContainerLogOptionsTestsContainerResource, encoded/decodedContainerLogOptions, and verified.defaultvalues