fix(topology): clarify disk buffer lifecycle messages

List each lifecycle counter event in the changelog with when it fires
and what it means. Explain that unavailable buffer usage means a disk
buffer writer was busy. Remove a semicolon from the unreferenced buffer
warning and pass the usage snapshot through directly when emitting the
replacement event.

Author: Jansen-w

changelog.d/disk_buffer_orphan_safety.enhancement.md

@@ -1,3 +1,7 @@
-Vector now detects unreferenced disk buffers and reports disk-buffer lifecycle events during configuration reloads through logs and the `topology_disk_buffer_lifecycle_events_total` counter.
+Vector now reports disk buffer lifecycle events during startup and configuration reloads. Each event is logged and increments the `topology_disk_buffer_lifecycle_events_total` counter with an `event` tag:
+
+- `removed`: A removed sink still had data in its disk buffer, or Vector could not read how much data it held. The log says whether the sink's current instance keeps draining the buffer in the background or whether the reload waits for it to finish.
+- `replacement_unreferenced`: A changed sink no longer uses its previous disk buffer. If the reload succeeds, the new sink will not read any data left in the old buffer.
+- `unreferenced`: A disk buffer in the data directory is not used by the current configuration. It may still be draining through a detached sink instance. If not, any data it holds is not being processed.
 
 authors: Jansen-w

src/internal_events/disk_buffer.rs

@@ -26,10 +26,10 @@ impl InternalEvent for TopologyDiskBufferRemoved<'_> {
                 "Removing sink with attached disk buffer containing buffered bytes. Configuration reload will wait for its current instance to drain the buffer."
             }
             (false, true) => {
-                "Removing sink with attached disk buffer whose buffered-byte count is unavailable. Its current instance will continue draining in the background until the buffer is empty or Vector shuts down."
+                "Removing sink with attached disk buffer. A disk buffer writer was busy writing or waiting for free space, so the buffer's usage could not be read. Its current instance will continue draining in the background until the buffer is empty or Vector shuts down."
             }
             (false, false) => {
-                "Removing sink with attached disk buffer whose buffered-byte count is unavailable. Configuration reload will wait for its current instance to drain the buffer."
+                "Removing sink with attached disk buffer. A disk buffer writer was busy writing or waiting for free space, so the buffer's usage could not be read. Configuration reload will wait for its current instance to drain the buffer."
             }
         };
         if let Some(usage) = self.usage {
@@ -90,7 +90,7 @@ impl InternalEvent for TopologyDiskBufferReplacementUnreferenced<'_> {
                 buffer_dirs = ?self.buffer_dirs,
                 new_buffer_dirs = ?self.new_buffer_dirs,
                 usage_unavailable = true,
-                message = "Replacement sink does not use the previous disk buffer, and its buffered-byte count is unavailable. If reload succeeds, any buffered bytes will be left unreferenced.",
+                message = "Replacement sink does not use the previous disk buffer. A disk buffer writer was busy writing or waiting for free space, so the buffer's usage could not be read. If reload succeeds, any buffered bytes will be left unreferenced.",
             ),
         }
         counter!(
@@ -112,7 +112,7 @@ impl InternalEvent for TopologyDiskBufferUnreferenced<'_> {
         warn!(
             buffer_id = self.buffer_id.to_string_lossy().as_ref(),
             buffer_dir = self.buffer_dir.to_string_lossy().as_ref(),
-            message = "Found disk buffer not referenced by the current configuration. It may still be draining through a detached sink instance; otherwise its buffered bytes are not being processed.",
+            message = "Found disk buffer not referenced by the current configuration. It may still be draining through a detached sink instance. If not, any buffered bytes it holds are not being processed.",
         );
         counter!(
             CounterName::TopologyDiskBufferLifecycleEventsTotal,

src/topology/running.rs

@@ -725,24 +725,12 @@ impl RunningTopology {
                         .iter()
                         .any(|path| new_buffer_dirs.contains(path))
                 {
-                    match usage {
-                        Some(usage) => {
-                            emit!(TopologyDiskBufferReplacementUnreferenced {
-                                component_id: key,
-                                buffer_dirs: &buffer_dirs,
-                                new_buffer_dirs: &new_buffer_dirs,
-                                usage: Some(usage),
-                            });
-                        }
-                        None => {
-                            emit!(TopologyDiskBufferReplacementUnreferenced {
-                                component_id: key,
-                                buffer_dirs: &buffer_dirs,
-                                new_buffer_dirs: &new_buffer_dirs,
-                                usage: None,
-                            });
-                        }
-                    }
+                    emit!(TopologyDiskBufferReplacementUnreferenced {
+                        component_id: key,
+                        buffer_dirs: &buffer_dirs,
+                        new_buffer_dirs: &new_buffer_dirs,
+                        usage,
+                    });
                 }
             }