[PR] feat(tools): add TimelineInspector standalone Java tool for timeline forensics [hudi]

["nsivabalan (via GitHub)" <gi...@apache.org>]

nsivabalan opened a new pull request, #19238:
URL: https://github.com/apache/hudi/pull/19238

   ### Change Logs
   
   Adds `org.apache.hudi.tools.TimelineInspector`, a pure-Java CLI for inspecting a Hudi table's active + archived timeline without needing Spark. Lives in `hudi-hadoop-common` since it uses Hadoop `FileSystem` APIs for raw archive log scanning and per-instant mtime lookups.
   
   #### Modes
   
   - `--show-instant` — dump one instant's content (all states + timeline location)
   - `--find-file-id` — find which instants touched a file id / partition / file group
   - `--commit-stats` — per-instant stats (numWrites/numInserts/numUpdateWrites/numDeletes, bytes, partitions touched) with optional filters
   - `--parse-filename` — decode a base or log file name into {fileId, commitTime, writeToken, ...}
   - `--raw-archive` — dump raw archive log entries for a specific instant
   - `--phase-timings` — per-instant phase durations (requested→inflight→completed for data table + MDT sub-table) for latency forensics
   
   Modifiers: `--lifecycle`, `--output table|json`, `--state`, `--actions`, `--start-instant`, `--end-instant`, `--limit`, `--sort asc|desc`, `--quiet`, `--no-archived`.
   
   #### Robustness
   
   Handles archived-timeline storage quirks:
   - Avro-container vs JSON-string sniff
   - Union-tag fixup walker for malformed JSON
   - `instantsRollback` checked alongside legacy `commitsRollback`
   - JSON-tree aggregator fallback for `--commit-stats` when the POJO path yields an empty shell
   
   Handles V2 timeline layout:
   - Reads instant files under `<base>/.hoodie/timeline/`
   - Resolves completed-instant filenames with the `_<completionTime>` suffix via the metaclient's `InstantFileNameGenerator`
   - For `--phase-timings`, the MDT completed-file lookup globs the timeline dir by `<requestedTime>` prefix + `.deltacommit` suffix (we don't know the completion time a priori)
   
   ### Impact
   
   - **New**: standalone CLI tool for timeline forensics. Useful for on-call debugging (what did commit X do?) and post-incident analysis (which commits touched file id Y?).
   - **No breaking changes**: purely additive. No `@PublicAPIClass` / `@PublicAPIMethod` touched. No storage format changes. No new `hoodie.*` configs.
   
   ### Risk level
   
   **low** — new tool with no changes to existing code paths.
   
   ### Documentation Update
   
   - New file: `hudi-hadoop-common/src/main/java/org/apache/hudi/tools/TimelineInspector.md` — full runbook (classpath setup, per-mode usage + examples, troubleshooting).
   - Class-level Javadoc on `TimelineInspector`.
   
   ### Contributor's checklist
   
   - [x] Read through [contributor's guide](https://hudi.apache.org/contribute/how-to-contribute)
   - [x] Change Logs and Impact were stated clearly
   - [x] Adequate tests were added if applicable
   - [x] CI passed locally: `mvn -pl hudi-hadoop-common -o test -Dtest=TestTimelineInspector` → **32/32 passing**


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@hudi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] feat(tools): add TimelineInspector standalone Java tool for timeline forensics [hudi]

["hudi-bot (via GitHub)" <gi...@apache.org>]

hudi-bot commented on PR #19238:
URL: https://github.com/apache/hudi/pull/19238#issuecomment-4929406485

   <!--
   Meta data
   {
     "version" : 1,
     "metaDataEntries" : [ {
       "hash" : "5790ba2c49103f493fbc4a40a756c1e40fc8858d",
       "status" : "UNKNOWN",
       "url" : "TBD",
       "triggerID" : "5790ba2c49103f493fbc4a40a756c1e40fc8858d",
       "triggerType" : "PUSH"
     } ]
   }-->
   ## CI report:
   
   * 5790ba2c49103f493fbc4a40a756c1e40fc8858d UNKNOWN
   
   <details>
   <summary>Bot commands</summary>
     @hudi-bot supports the following commands:
   
    - `@hudi-bot run azure` re-run the last Azure build
   </details>


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@hudi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] feat(tools): add TimelineInspector standalone Java tool for timeline forensics [hudi]

["codope (via GitHub)" <gi...@apache.org>]

codope merged PR #19238:
URL: https://github.com/apache/hudi/pull/19238


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@hudi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org