db-analyser: print hashes for --show-slot-block-no (#1152)

A concrete use case is to find the intersection between two ChainDBs (eg
by diffing the db-analyser output).

Author: amesgen

ouroboros-consensus-cardano/README.md

@@ -106,8 +106,8 @@ Note that these flags do not refer to Ledger validation.
 
 Lastly the user can provide the analysis that should be run on the chain:
 
-* `--show-slot-block-no` prints the slot and block number of each block it
-  process.
+* `--show-slot-block-no` prints the slot and block number and hash of each block
+  it process.
 
 * `--count-tx-outputs` prints the block and slot number, tx out output for given
   block and the cumulative tx out output for all the blocks seen so far.
@@ -245,6 +245,38 @@ gnuplot -e "bench_data='ledger-ops-cost.csv'" \
 The plot will be written to a file named `results.png`. See the script file for
 more usage options.
 
+#### Finding the intersection between two ChainDBs
+
+Suppose that you have two ChainDBs containing different forks, and you want to
+find their intersection. This can be accomplished with db-analyser via the
+`--show-slot-block-no` analysis:
+
+First, run the following command for both of your ChainDBs:
+
+```
+db-analyser --analyse-from 1234 --db /path/to/dbX --show-slot-block-no \
+  cardano --config /path/to/config.json | cut -d ' ' -f 2- > dbX.log
+```
+
+Note that specificying `--analyse-from` is optional; it means that you are
+certain that both ChainDBs still were on the same fork in slot `1234`, in order
+to decrease the run time of the command.
+
+Then, you can `diff` the resulting files to find the last common block, or the
+`comm` tool like this:
+
+ - Get the last few blocks in common (last one is the intersection):
+   ```console
+   comm -1 -2 db0.log db1.log | tail
+   ```
+ - Get the first few blocks after the intersection:
+   ```console
+   comm -3 db0.log db1.log | head
+   ```
+
+> It is possible to do this in logarithmic instead of linear time via a binary
+> search; however, this hasn't been necessary so far.
+
 ## db-immutaliser
 
 Copy a specific chain from a volatile DB to an immutable DB, such that other

ouroboros-consensus-cardano/app/DBAnalyser/Parsers.hs

@@ -70,7 +70,7 @@ parseAnalysis :: Parser AnalysisName
 parseAnalysis = asum [
       flag' ShowSlotBlockNo $ mconcat [
           long "show-slot-block-no"
-        , help "Show slot and block number of all blocks"
+        , help "Show slot and block number and hash of all blocks"
         ]
     , flag' CountTxOutputs $ mconcat [
           long "count-tx-outputs"

ouroboros-consensus-cardano/src/unstable-cardano-tools/Cardano/Tools/DBAnalyser/Analysis.hs

@@ -189,7 +189,7 @@ data TraceEvent blk =
     -- ^ triggered when given analysis has started
   | DoneEvent
     -- ^ triggered when analysis has ended
-  | BlockSlotEvent BlockNo SlotNo
+  | BlockSlotEvent BlockNo SlotNo (HeaderHash blk)
     -- ^ triggered when block has been found, it holds:
     --   * block's number
     --   * slot number when the block was forged
@@ -244,9 +244,10 @@ data TraceEvent blk =
 instance HasAnalysis blk => Show (TraceEvent blk) where
   show (StartedEvent analysisName)        = "Started " <> (show analysisName)
   show DoneEvent                          = "Done"
-  show (BlockSlotEvent bn sn)             = intercalate "\t" $ [
+  show (BlockSlotEvent bn sn h)           = intercalate "\t" $ [
       show bn
     , show sn
+    , show h
     ]
   show (CountTxOutputsEvent bn sn cumulative count) = intercalate "\t" $ [
       show bn
@@ -292,7 +293,7 @@ instance HasAnalysis blk => Show (TraceEvent blk) where
 
 
 {-------------------------------------------------------------------------------
-  Analysis: show block and slot number for all blocks
+  Analysis: show block and slot number and hash for all blocks
 -------------------------------------------------------------------------------}
 
 showSlotBlockNo :: forall blk. HasAnalysis blk => Analysis blk StartFromPoint
@@ -301,7 +302,8 @@ showSlotBlockNo AnalysisEnv { db, registry, startFrom, limit, tracer } =
         >> pure Nothing
   where
     process :: Header blk -> IO ()
-    process hdr = traceWith tracer $ BlockSlotEvent (blockNo hdr) (blockSlot hdr)
+    process hdr = traceWith tracer $
+        BlockSlotEvent (blockNo hdr) (blockSlot hdr) (headerHash hdr)
 
 {-------------------------------------------------------------------------------
   Analysis: show total number of tx outputs per block
@@ -419,7 +421,7 @@ storeLedgerStateAt slotNo (AnalysisEnv { db, registry, startFrom, cfg, limit, le
 
     issueWarning blk   = let event = SnapshotWarningEvent slotNo (blockSlot blk)
                          in traceWith tracer event
-    reportProgress blk = let event = BlockSlotEvent (blockNo blk) (blockSlot blk)
+    reportProgress blk = let event = BlockSlotEvent (blockNo blk) (blockSlot blk) (blockHash blk)
                          in traceWith tracer event
 
     storeLedgerState ::