apple / apple/container

Support Docker Compose-compatible container log semantics

Open
#1,752 6 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.