Documentation
¶
Overview ¶
Package transcript reads back what a Project's own container wrote while an Exchange was live. proximo collects nothing of its own and stores nothing: a Transcript is quoted from the container's existing output, cut to the window of the Exchange, at the moment the CLI prints it. See docs/adr/0006-the-transcript-is-quoted-never-stored.md.
Index ¶
- Constants
- type Docker
- type Reader
- func (r *Reader) Access(ctx context.Context, since time.Time) ([]inspect.Exchange, error)
- func (r *Reader) Join(ctx context.Context, quote, window []inspect.Exchange, limit int) map[string]Transcript
- func (r *Reader) JoinOne(ctx context.Context, e inspect.Exchange, window []inspect.Exchange, limit int) Transcript
- func (r *Reader) Merge(logged, inspected []inspect.Exchange) []inspect.Exchange
- func (r *Reader) QuoteIncident(ctx context.Context, inc docker.Incident, all []docker.Incident, limit int) Transcript
- func (r *Reader) QuoteService(ctx context.Context, service docker.Service, from, to time.Time, limit int) Transcript
- func (r *Reader) ReadingsOf(ctx context.Context, service docker.Service) []docker.Reading
- func (r *Reader) ServiceOfBackend(backend string) docker.Service
- func (r *Reader) Services() []docker.Service
- type Transcript
Constants ¶
const DefaultLimit = 4 << 10
DefaultLimit is how many bytes of a container's output one Transcript quotes when it is rendered inline beside an Exchange. `proximo errors transcript` asks for far more: it is the command for reading the whole thing.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Docker ¶
type Docker interface {
ContainerList(context.Context, client.ContainerListOptions) (client.ContainerListResult, error)
ContainerInspect(context.Context, string, client.ContainerInspectOptions) (client.ContainerInspectResult, error)
ContainerLogs(context.Context, string, client.ContainerLogsOptions) (client.ContainerLogsResult, error)
}
Docker is the narrow slice of the Docker client this package depends on — exactly the three calls a join makes. *client.Client satisfies it unchanged, so production passes the real client and tests pass a fake. It mirrors the watcher's dockerAPI seam.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader quotes Transcripts. It holds one container listing for the life of a CLI invocation: a backend address is resolved against the containers alive now, which is the only listing that can be checked against a request's instant.
func NewReader ¶
NewReader lists the containers a join resolves against.
Stopped containers are listed too (All). A container that exited is exactly what an Incident is usually about — a worker that dies and is restarted, or a job that ran once — and Docker still answers `docker logs` for it, so leaving it out would report the output as gone while it is sitting right there. What a stopped container is *not* is a replica: the count below stays running-only, because "1 of 3 replicas" is a statement about what is serving now.
func (*Reader) Access ¶
Access reads the Access records Traefik logged since t. Traefik's operational log shares the stream, so lines that are not JSON describing a request are skipped: that is the whole of the filter, and DecodeAccessLine owns it.
func (*Reader) Join ¶
func (r *Reader) Join(ctx context.Context, quote, window []inspect.Exchange, limit int) map[string]Transcript
Join returns the Transcript of each Exchange in quote, keyed by Exchange id.
The two lists are separate because they answer different questions: an Exchange is quoted only if the caller will show it — reading a container's log back is a round trip to Docker, and doing it for a clean request nobody will look at is pure waste — while the overlaps can only be seen across every Exchange in the window, shown or not. Two Exchanges of one container whose windows meet interleave their lines, and nothing after the fact can tell them apart.
func (*Reader) JoinOne ¶
func (r *Reader) JoinOne(ctx context.Context, e inspect.Exchange, window []inspect.Exchange, limit int) Transcript
JoinOne is Join for a single Exchange, with the same window to count overlaps against.
func (*Reader) Merge ¶
Merge folds the Exchanges the hop recorded into the ones Traefik logged. Ordering is the caller's: it follows the most recent activity rather than the request instant, which is a rule about how a listing is read, not about how two sources are joined.
A request to an inspected route appears in both sources, and the hop's copy is the one to keep: it names the container behind the hop rather than the hop itself, and it carries the Client reports. Traefik's copy is recognised by what it is — its backend is a stack service — rather than by matching two records on host and instant, which is a guess and would fail exactly when two requests arrive together.
func (*Reader) QuoteIncident ¶
func (r *Reader) QuoteIncident(ctx context.Context, inc docker.Incident, all []docker.Incident, limit int) Transcript
QuoteIncident quotes what a container wrote in the window one Incident closes. The window's right edge is the Incident; its left edge is the previous Incident of the same service, or the container's birth when there is none — for a restart loop that is exactly one container lifetime, which no fixed duration can be: a fixed one truncates the worker that wrote the useful line five minutes before dying and drowns the one that restarts every three seconds.
Nothing here reads the text. An Incident is a statement the runtime made, and the window it fixes is the same kind of frame an Exchange fixes — which is what lets a Transcript stand on its own without proximo ever deciding which lines of a routeless container look like errors.
func (*Reader) QuoteService ¶
func (r *Reader) QuoteService(ctx context.Context, service docker.Service, from, to time.Time, limit int) Transcript
QuoteService quotes what a service's container wrote in a plain window. It is the fallback for a service with no Incident to anchor to: the runtime declared nothing, so the only window left is the one the developer asked for — which is still a window fixed outside the text, never a reading of it.
func (*Reader) ReadingsOf ¶
ReadingsOf takes the readings for one Service: one per running container of it, in name order so two invocations list the same replicas in the same places. A container that is not running produces none — it has already declared an Incident, and dated history and the present tense are kept apart rather than said twice.
Each is two bounded questions, one inspect and one one-line log read. The type is docker.Reading because a reading is what the runtime declares, the same as an Incident; taking it lives here because this is where the container listing and the log stream already are.
func (*Reader) ServiceOfBackend ¶
ServiceOfBackend names the service of the container a backend address names, or "" when nothing running answers to it. It is what lets one selector narrow both halves of the listing: the Exchanges a service served, and the Incidents the runtime declared about it.
type Transcript ¶
type Transcript struct {
// Container is the name of the container quoted, and Replicas how many the
// service has. Without the count an agent reads "happens only sometimes" as a
// race condition when the cause is one replica running stale config.
Container string `json:"container"`
Replicas int `json:"replicas,omitempty"`
// Head is the start of the window, Tail its most recent lines, and Dropped
// how many lines were elided in between. A panic's message is at the head and
// its most recent output at the tail, so neither end may be the one cut.
// Dropped zero means Head is the whole thing and Tail is empty.
Head []string `json:"head,omitempty"`
Tail []string `json:"tail,omitempty"`
Dropped int `json:"dropped,omitempty"`
// Silence says why there is nothing to quote, and is set only when there is
// nothing. A silence without a named cause is what makes a working tool look
// broken.
Silence string `json:"silence,omitempty"`
// Overlap says another Exchange of this container was live in the same
// window. The cut is temporal, so their lines interleave and nothing here can
// tell them apart. proximo reports the overlap rather than attributing a
// line — quoting the wrong container's stack trace to something about to edit
// code is the failure this refuses.
Overlap int `json:"overlap,omitempty"`
}
Transcript is what one container wrote in the window of one Exchange, quoted verbatim and never interpreted. It is bounded, and the bound is declared: a truncation nobody is told about is the one after which a reader stops looking.
func (Transcript) Empty ¶
func (t Transcript) Empty() bool
Empty reports whether there is nothing to quote.