flinkit / docs / findings

Findings

A finding is flinkit's unit of diagnosis: a ranked, coded statement of something wrong with a job, with the evidence behind it and a suggested fix. Findings appear inline in inspect and as a ranked list in doctor.

Severities

Every finding carries a severity. flinkit uses the same cues everywhere — in scan's status column, the inspect dashboard, and doctor's list.

Anatomy of a finding

Each finding has:

• a severity — High / Medium / Low;
• a code — a stable identifier like DOC-CKPT-001 you can search and reference;
• a one-line summary of what's wrong;
• evidence — the metric or event that triggered it (e.g. N checkpoints have failed);
• a fix — what to change;
• a docs link — more detail on the cause.

Codes are grouped by area: CKPT for checkpointing, STAB for stability, and so on.

Catalog

The findings catalog grows with each release. A couple of the most common ones:

High DOC-CKPT-001 — checkpoints are failing

Checkpoints are failing, so the job cannot recover cleanly from failure — on a restart it falls back to an old checkpoint (or none), replaying or losing progress.

Evidence: one or more checkpoints have failed; often a climbing failure count and a reason such as Asynchronous task checkpoint failed, with a correlated log line.

Typical causes & fixes: checkpoints timing out because the job is under-provisioned for its state — too little TaskManager memory for the state backend, or more state than can be snapshotted within the checkpoint timeout. Give the TaskManager more memory, raise the checkpoint timeout, or reduce state/throughput, then confirm the failure count stops climbing in inspect.

Medium DOC-STAB-001 — repeated restarts

The job has restarted; repeated restarts point to an unstable pipeline. A job that keeps failing over isn't making dependable forward progress even if it looks RUNNING between restarts.

Evidence: a non-zero (and often climbing) restart count, with the last failover exception.

Typical causes & fixes: find the root cause in the last failure exception shown by inspect. Frequently it's the same underlying issue as a checkpoint finding (the job can't checkpoint, so it fails over). Fix the root cause rather than just raising restart limits.