Support Docker Compose-compatible container log semantics
- Dominant language
- Swift
- Stars
- 49.9k
- Forks
- 1.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 22
Description
## Summary
I am working on a Docker Compose v2 compatibility plugin for apple/container:
https://github.com/stephenlclarke/container-compose
While implementing `container compose logs`, I found that some Compose-level behavior can live cleanly in the plugin, but several lower-level log capabilities need support from apple/container itself. This issue tracks the remaining runtime/API behavior needed for Compose-compatible log commands.
This is related to:
- #1591
- #1592
#1591/#1592 cover an important first step by adding log retrieval options such as `since` and `timestamps`. Compose-compatible logging also needs a few additional capabilities so external orchestrators can avoid replaying/filtering complete log files in user space.
## Why this matters
Docker Compose-style orchestrators need to support commands such as:
```sh
container compose logs
container compose logs --follow
container compose logs --tail 100
container compose logs --since 10m
container compose logs --until 2026-06-18T10:00:00Z
container compose logs --timestamps
```
The plugin can own Compose presentation behavior such as:
- project/service/container selection
- service prefixes
- colorized output
- interleaving logs from multiple services
- replica labels and Compose metadata
- command-line compatibility mapping
However, the plugin needs apple/container to provide efficient and stable access to the underlying log records.
## Requested apple/container capabilities
Building on #1591/#1592, it would be useful for `ContainerClient.logs` or an equivalent direct API to support:
- `tail`: return only the last N log lines/records without requiring the caller to replay the full log
- `since`: return records after a timestamp
- `until`: return records before a timestamp
- `timestamps`: stable timestamp behavior, either by preserving stored timestamps or decorating emitted records consistently
- stream identity where available, for example stdout vs stderr
- follow/stream behavior that works reliably for orchestrators reading multiple containers concurrently
- enough returned metadata for callers to associate log records with a container and preserve ordering where possible
An illustrative API shape might be:
```swift
public struct ContainerLogOptions: Sendable {
public var since: Date?
public var until: Date?
public var tail: Int?
public var timestamps: Bool
public var follow: Bool
}
```
If apple/container already intends #1592 to become the extension point for this, these could potentially be added there incrementally.
## Compose compatibility impact
Without runtime/API support, `container-compose` can still approximate some behavior, but it has to do inefficient or incomplete work in the plugin:
- `--tail` requires reading and buffering full logs
- `--since` / `--until` require parsing and filtering full logs
- `--timestamps` depends on whether timestamps are present, parseable, or need decoration
- stdout/stderr fidelity cannot be preserved if the log API exposes only merged raw text
- multi-service `--follow` becomes harder to implement predictably without stable streaming semantics
These gaps affect compatibility with Docker Compose v2 local-development workflows.
## Non-goals
This issue is not asking apple/container to implement Compose formatting itself.
The following should remain in the Compose plugin:
- service name prefixes
- ANSI color selection
- service filtering
- project filtering
- replica naming
- Compose CLI flag translation
- user-facing `container compose logs` behavior
This issue is specifically about the lower-level log retrieval primitives needed by external orchestrators.
## Acceptance criteria
A downstream orchestrator should be able to implement the following without replaying and filtering whole logs itself:
```sh
container compose logs --tail 100
container compose logs --since 10m
container compose logs --until 2026-06-18T10:00:00Z
container compose logs --timestamps
container compose logs --follow
```
Ideally the API should also expose enough metadata to allow a caller to preserve or reconstruct:
- timestamp
- stdout/stderr stream, where available
- container identity
- stable follow ordering as far as the runtime can provide it
Contributor guide
Research direction
Start by reviewing the existing ContainerClient.logs API and the related work in #1591 and #1592. Define the runtime log retrieval behavior for tail, since, until, timestamps, stream identity, and follow without implementing Compose presentation features. Done means a downstream orchestrator can satisfy the listed Compose log commands without replaying and filtering complete logs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker-compose, swift
- Domain
- backend-api-design, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100