Merge "Change reference to RSA based ssh to use ed25519"
diff --git a/aos/events/logging/log_reader.cc b/aos/events/logging/log_reader.cc
index 1e7644f..cbe37d5 100644
--- a/aos/events/logging/log_reader.cc
+++ b/aos/events/logging/log_reader.cc
@@ -2335,7 +2335,12 @@
 }
 
 void LogReader::State::NotifyLogfileStart() {
+  // If the start_event_notifier_ is set, that means that a realtime start time
+  // was set manually; when the override is set, we want to delay any startup
+  // handlers that would've happened before requested start time until that
+  // start time.
   if (start_event_notifier_) {
+    // Only call OnStart() if the start time for this node (realtime_start_time())
     if (start_event_notifier_->realtime_event_time() >
         realtime_start_time(boot_count())) {
       VLOG(1) << "Skipping, " << start_event_notifier_->realtime_event_time()
@@ -2351,6 +2356,9 @@
 }
 
 void LogReader::State::NotifyFlagStart() {
+  // Should only be called if start_event_notifier_ has been set (which happens
+  // as part of setting an explicit start time); only call the startup functions
+  // that occurred *before* the start flag value.
   if (start_event_notifier_->realtime_event_time() >=
       realtime_start_time(boot_count())) {
     RunOnStart();
@@ -2358,16 +2366,22 @@
 }
 
 void LogReader::State::NotifyLogfileEnd() {
+  // Don't execute the OnEnd handlers if the logfile was ended artifically
+  // early.
   if (found_last_message_) {
     return;
   }
 
+  // Ensure that we only call OnEnd() if OnStart() was already called for this
+  // boot (and don't call OnEnd() twice).
   if (!stopped_ && started_) {
     RunOnEnd();
   }
 }
 
 void LogReader::State::NotifyFlagEnd() {
+  // Ensure that we only call OnEnd() if OnStart() was already called for this
+  // boot (and don't call OnEnd() twice).
   if (!stopped_ && started_) {
     RunOnEnd();
     SetFoundLastMessage(true);
diff --git a/aos/events/logging/log_reader.h b/aos/events/logging/log_reader.h
index ddf9116..49babe5 100644
--- a/aos/events/logging/log_reader.h
+++ b/aos/events/logging/log_reader.h
@@ -140,9 +140,29 @@
   }
 
   // Called whenever a log file starts for a node.
+  // More precisely, this will be called on each boot at max of
+  // (realtime_start_time in the logfiles, SetStartTime()). If a given boot
+  // occurs entirely before the realtime_start_time, the OnStart handler will
+  // never get called for that boot.
+  //
+  // realtime_start_time is defined below, but/ essentially is the time at which
+  // message channels will start being internall consistent on a given node
+  // (i.e., when the logger started). Note: If you wish to see a watcher
+  // triggered for *every* message in a log, OnStart() will not be
+  // sufficient--messages (possibly multiple messages) may be present on
+  // channels prior to the start time. If attempting to do this, prefer to use
+  // NodeEventLoopFactory::OnStart.
   void OnStart(std::function<void()> fn);
   void OnStart(const Node *node, std::function<void()> fn);
-  // Called whenever a log file ends for a node.
+  // Called whenever a log file ends for a node on a given boot, or at the
+  // realtime_end_time specified by a flag or SetEndTime().
+  //
+  // A log file "ends" when there are no more messages to be replayed for that
+  // boot.
+  //
+  // If OnStart() is not called for a given boot, the OnEnd() handlers will not
+  // be called either. OnEnd() handlers will not be called if the logfile for a
+  // given boot has missing data that causes us to terminate replay early.
   void OnEnd(std::function<void()> fn);
   void OnEnd(const Node *node, std::function<void()> fn);
 
diff --git a/aos/events/simulated_event_loop.h b/aos/events/simulated_event_loop.h
index c4704ff..8242d6c 100644
--- a/aos/events/simulated_event_loop.h
+++ b/aos/events/simulated_event_loop.h
@@ -220,8 +220,10 @@
   // Starts the node up by calling the OnStartup handlers.  These get called
   // every time a node is started.
 
-  // Called when a node has started.  This is typically when a log file starts
-  // for a node.
+  // Called when a node has started. This will most commonly be at the monotonic
+  // clock epoch. In log replay, this will occur prior to any messages
+  // (including "fetched" messages) being replayed for that node.
+  // Called on every boot.
   void OnStartup(std::function<void()> &&fn);
 
   // Called when a node shuts down.  These get called every time a node is shut
diff --git a/aos/util/log_to_mcap.cc b/aos/util/log_to_mcap.cc
index d4e240f..0d51e52 100644
--- a/aos/util/log_to_mcap.cc
+++ b/aos/util/log_to_mcap.cc
@@ -17,6 +17,12 @@
 DEFINE_bool(include_clocks, true,
             "Whether to add a /clocks channel that publishes all nodes' clock "
             "offsets.");
+DEFINE_bool(include_pre_start_messages, false,
+            "If set, *all* messages in the logfile will be included, including "
+            "any that may have occurred prior to the start of the log. This "
+            "can be used to see additional data, but given that data may be "
+            "incomplete prior to the start of the log, you should be careful "
+            "about interpretting data flow when using this flag.");
 
 // Converts an AOS log to an MCAP log that can be fed into Foxglove. To try this
 // out, run:
@@ -73,21 +79,15 @@
 
   std::unique_ptr<aos::EventLoop> clock_event_loop;
   std::unique_ptr<aos::ClockPublisher> clock_publisher;
-  if (FLAGS_include_clocks) {
-    reader.OnStart(
-        node, [&clock_event_loop, &reader, &clock_publisher, &factory, node]() {
-          clock_event_loop =
-              reader.event_loop_factory()->MakeEventLoop("clock", node);
-          clock_publisher = std::make_unique<aos::ClockPublisher>(
-              &factory, clock_event_loop.get());
-        });
-  }
 
   std::unique_ptr<aos::EventLoop> mcap_event_loop;
   CHECK(!FLAGS_output_path.empty());
   std::unique_ptr<aos::McapLogger> relogger;
-  factory.GetNodeEventLoopFactory(node)->OnStartup([&relogger, &mcap_event_loop,
-                                                    &reader, node]() {
+  auto startup_handler = [&relogger, &mcap_event_loop, &reader,
+                          &clock_event_loop, &clock_publisher, &factory,
+                          node]() {
+    CHECK(!mcap_event_loop) << ": log_to_mcap does not support generating MCAP "
+                               "files from multi-boot logs.";
     mcap_event_loop = reader.event_loop_factory()->MakeEventLoop("mcap", node);
     relogger = std::make_unique<aos::McapLogger>(
         mcap_event_loop.get(), FLAGS_output_path,
@@ -98,7 +98,22 @@
             : aos::McapLogger::CanonicalChannelNames::kShortened,
         FLAGS_compress ? aos::McapLogger::Compression::kLz4
                        : aos::McapLogger::Compression::kNone);
-  });
+    if (FLAGS_include_clocks) {
+      clock_event_loop =
+          reader.event_loop_factory()->MakeEventLoop("clock", node);
+      clock_publisher = std::make_unique<aos::ClockPublisher>(
+          &factory, clock_event_loop.get());
+    }
+  };
+  if (FLAGS_include_pre_start_messages) {
+    // Note: This condition is subtly different from just using --fetch from
+    // mcap_logger.cc. Namely, if there is >1 message on a given channel prior
+    // to the logfile start, then fetching in the reader OnStart() is
+    // insufficient to get *all* log data.
+    factory.GetNodeEventLoopFactory(node)->OnStartup(startup_handler);
+  } else {
+    reader.OnStart(node, startup_handler);
+  }
   reader.event_loop_factory()->Run();
   reader.Deregister();
 }