skip to content

Why should an automated run print the configuration it actually resolved before the first case runs?

level: juniorimportance: should knowfreq 44%

answer

  1. The output outlives every input
  2. Print before the first case, always
  3. Values plus the layer that supplied them
  4. Two echoes diff faster than two machines

basics

~20 s

So anyone reading the output later sees the values the run truly used, not the ones a file suggests. Without that echo, explaining a surprising result means reconstructing every input layer by hand, on a machine that is gone.

solid answer

~50 s

Emit the resolved configuration as the run's first output: every key, the value in force, and which layer supplied it. That turns three later arguments into a lookup — whether the run pointed where you assumed, whether an override actually took effect, and whether yesterday's green run and today's red one differed in inputs at all. It costs a few lines and it is the only durable record, because a file changes with the next commit, process variables belong to a machine that may be discarded, and the arguments someone typed are written down nowhere. Print it on every run rather than only on failure: the run you will need to explain is always one nobody thought worth recording. Sort by key so two runs diff cleanly, and include keys that took a declared default.

code

text · 6 lines
text
effective configuration (resolved once at startup)
  artefact_dir    = ./out/run-8841        <- invocation override
  batch_size      = 50                    <- built-in default
  target_tenant   = acme-staging          <- process environment
  worker_count    = 8                     <- checked-in file
  wait_budget_ms  = 30000                 <- checked-in file

go deeper

for a junior

Be ready to say that a run should print the settings it actually used, at the start, every time. Recall that files and machines change but the run's output is what people still have next week.

for a middle

Explain what the echo must contain to be useful: every key including defaulted ones, sorted for clean comparison, each with the layer that supplied it, and derived from the same resolved object the cases read.

for a senior

Show how the echo shortens a real diagnosis: green yesterday, red today becomes a two-block comparison instead of an argument about machines. Be ready to explain why an ignored override is invisible when only values are printed.

for a principal

Own it as an estate-wide expectation rather than a per-suite nicety: every run explains itself in a comparable format, so that inputs can be diffed across suites and teams without anyone reverse-engineering a harness.

## What the echo is The echo is a few lines the run emits before it does any work: every configuration key it resolved, the value in force, and ideally which layer supplied that value. It is not a debugging aid you switch on when something looks wrong. It is the run's own statement of what it was, written at the only moment when that statement is free to produce and guaranteed to be accurate. The reason it matters is that every input to the resolved configuration is more perishable than the record of a run. A file changes with the next commit. Process variables belong to a machine or a job that may be discarded minutes later. The arguments someone typed on an invocation are written down nowhere at all. A week later the only durable artefact is the output, so whatever the output does not say, nobody can reconstruct. ## The three questions it answers later 1. **Did this run point where I think it pointed, and behave how I think it behaved?** Without the echo this is answered by inference — reading the file as it exists *today* and assuming it was the same then, which is exactly the assumption that fails. 2. **Did my override actually take effect?** Someone passes a value, the run behaves as before, and there is no way to tell whether the value was ignored, overridden by a higher layer, or applied and irrelevant. The echo settles it in one line. 3. **Did these two runs differ in their inputs at all?** A green run yesterday and a red run today are either a product change or an input change, and every minute spent on the wrong branch is wasted. Two echoed blocks diff in seconds. ## Values alone are not enough: record the source Printing values gets most of the benefit. Printing values *with the layer each came from* gets the rest, and the difference shows up in the cases people actually argue about. | Echoed | Answers "what was in force?" | Answers "why was it that?" | Catches an ignored override | |---|---|---|---| | Nothing | no | no | no | | Values only | yes | no | no | | Values with source layer | yes | yes | yes | The middle row is the common trap. A reader sees the value they expected and concludes their override worked, when in fact a higher layer set the same value for an unrelated reason and their override was discarded. That misdiagnosis is durable: the person now believes a mechanism works that does not. ## Where it goes, and when - **First, not last.** Emit it before the first case, so a run that crashes early still explains itself. - **On every run, not only on failure.** The run you will need to explain is always one nobody thought worth recording, and by definition you cannot know in advance which one that is. - **In the run's own output**, where the person diagnosing is already reading, rather than somewhere they must be told about. - **Stable in order**, sorted by key, so two runs can be compared line by line without a reader untangling ordering noise. - **Complete**, including keys that took their declared default. A key that is absent from the echo because "nobody set it" is precisely the key someone will later wonder about. ## Why the checked-in file is not the record The instinct that replaces this practice is: *we do not need an echo, the settings are in the file.* Three things break it. The file is one layer of several, so it does not show what the layers above it did. The file is mutable and shared, so its state today is not evidence about last Tuesday. And the file describes intent, whereas the echo describes what happened — those diverge exactly in the situations where somebody needs the answer. ## Habits that keep it honest - Derive the echo from the same resolved object every case reads, never from a second traversal of the layers, or the two can disagree and the echo becomes a plausible lie. - Keep it short enough that people actually read it: keys sorted, one per line, no decoration. - Treat a key that appears in the echo but is read nowhere as dead configuration, and delete it. - Treat a value read anywhere but absent from the echo as a bug in the chain, because something is bypassing resolution.

  • Why print the layer each value came from, rather than just the values?
    Because values alone cannot tell you whether an override was honoured. A reader sees the value they expected and concludes their argument worked, when a higher layer may have set the same value for an unrelated reason and their argument was discarded. That misdiagnosis is durable: the person now trusts a mechanism that is not working. The source layer makes an ignored override visible in one line.
  • Should the echo be produced by walking the layers again, or from the resolved object?
    From the resolved object every case reads. A second traversal is a second implementation of the chain, and the two can drift, at which point the echo becomes a plausible lie that is worse than no echo at all. Deriving it from the single frozen object also means anything missing from the echo is a real defect, because something bypassed resolution.

saying these in an interview costs you the question

  • Says the checked-in file is already the record
  • Prints the configuration only when a run fails
  • Omits keys that took their declared default
  • Prints values but never their source layer
  • Rebuilds the echo from the layers instead of the resolved object