Weather Pipeline Performance Diagnosis

Weather Pipeline Performance Diagnosis locates the stage that actually makes a weather workflow slow before anyone optimizes it, measuring the real runtime path from source discovery through the final artifact, including optional companion data and fallback work. It diagnoses latency and throughput only - it does not prescribe a particular data provider, file format, decoder, or fix.

It starts by insisting on a reproducible workload recorded before any code changes: requested source, time, location, variables, and output; application commit and runtime version; which backend implementation is actually active and why (including fallback reason); cold- versus warm-cache state; machine and worker-count details; and bytes transferred. The same workload must be used for baseline and candidate measurement, because a faster run with fewer inputs or a warm cache is not evidence the original path improved.

The pipeline gets divided into at least eight independently timed boundaries: request validation and source discovery, availability checks and fallback selection, network transfer or cache read, parsing or decoding, supplemental-data retrieval, profile/grid/derived-value construction, visualization or export, and cleanup/publication - adding finer sub-stages only where the first pass shows meaningful time, and never silently disabling expensive work while instrumenting it.

@contextmanager
def timed_stage(name, report):
    started = time.perf_counter()
    outcome = "ok"
    try:
        yield
    except BaseException:
        outcome = "error"
        raise
    finally:
        report.append({
            "stage": name,
            "outcome": outcome,
            "seconds": round(time.perf_counter() - started, 6),
        })

Instrumentation is meant to sit at production boundaries or the same public APIs production actually uses - not a benchmark helper that bypasses the exact path users report as slow. Evidence gets interpreted by pattern: long discovery with little transfer suggests broad listings or repeated availability probes; long transfer with expected parsing time suggests bandwidth or a failed cache reuse; long parsing needs proof the intended backend is actually active; long processing after parsing points to interpolation or repeated computation; long rendering can come from layout, rasterization, or output dimensions; and high variance across identical runs suggests external services, contention, cold starts, or uncontrolled parallelism. A single total duration is explicitly called out as unable to locate a bottleneck by itself - wall time, CPU time, bytes, item counts, cache state, and worker count all matter.

Validating a proposed fix means preserving the baseline report and environment description, changing the smallest shared cause the measurements actually support, rerunning the identical workload several times in the same cache state, comparing the affected stage plus total duration plus output identity plus resource use, running correctness tests for the changed path, and reporting both improvement and measurement variability - a slowdown is never called fixed when only a suspected backend or a microbenchmark changed rather than the end-to-end reported path.

Use it when a fetch, sounding, map, animation, or batch job feels slower than before; when a parser or native backend is blamed without stage-level timing evidence; when local and packaged/hosted runs perform differently; when a cache, provider fallback, or optional enrichment step may be hiding the real cost; or when a proposed performance fix needs a repeatable before-and-after comparison.

Do not use it for a correctness bug unless performance is also part of the observed failure.

Input is a fixed, reproducible weather-workflow workload and its runtime environment (backend, cache state, machine, worker count). Output is a set of per-stage timing records (wall time, CPU time, bytes, outcome) across the pipeline's boundaries, an interpretation of which stage dominates and why, and a before-and-after comparison validating any proposed fix against the identical workload.

Engineers debugging a slow weather data pipeline who need to know which stage actually costs the time - source discovery, transfer, parsing, processing, or rendering - instead of guessing at the decoder or backend and "fixing" something a benchmark doesn't actually exercise.