document file writer

targets/file/src/internal_metrics.rs

@@ -1,29 +1,53 @@
-use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{
+    atomic::{AtomicUsize, Ordering},
+    Arc,
+};
 
 macro_rules! metrics {
-    ($container:ident {
-        $($name:ident: $ty:ty,)*
-    }) => {
+    (
+        $pub_container:ty {
+            $field:ident: $internal_container:ident {
+                $(
+                    $(#[$meta:meta])*
+                    $metric:ident: $ty:ident -> $pub_ty:ident,
+                )*
+            }
+        }
+    ) => {
         #[derive(Default)]
-        pub(crate) struct $container { $(pub(crate) $name: $ty),* }
+        pub(crate) struct $internal_container {
+            $(
+                $(#[$meta])*
+                pub(crate) $metric: $ty,
+            )*
+        }
 
-        impl $container {
+        impl $internal_container {
             pub fn sample(&self) -> impl Iterator<Item = emit::metric::Metric<'static, emit::empty::Empty>> + 'static {
-                let $container { $($name),* } = self;
+                let $internal_container { $($metric),* } = self;
 
                 [$(
                     emit::metric::Metric::new(
                         env!("CARGO_PKG_NAME"),
                         emit::empty::Empty,
-                        stringify!($name),
+                        stringify!($metric),
                         <$ty>::AGG,
-                        $name.sample(),
+                        $metric.sample(),
                         emit::empty::Empty,
-                    )
-                ),*]
+                    ),
+                )*]
                 .into_iter()
             }
         }
+
+        impl $pub_container {
+            $(
+                $(#[$meta])*
+                pub fn $metric(&self) -> $pub_ty {
+                    self.$field.$metric.sample()
+                }
+            )*
+        }
     };
 }
 
@@ -46,13 +70,66 @@ impl Counter {
     }
 }
 
-metrics!(InternalMetrics {
-    file_set_read_failed: Counter,
-    file_open_failed: Counter,
-    file_create: Counter,
-    file_create_failed: Counter,
-    file_write_failed: Counter,
-    file_delete: Counter,
-    file_delete_failed: Counter,
-    file_format_failed: Counter,
-});
+metrics!(
+    FileSetMetrics {
+        metrics: InternalMetrics {
+            /**
+            Attempting to read the set of log files failed.
+            */
+            file_set_read_failed: Counter -> usize,
+            /**
+            Attempting to open a log file failed.
+            */
+            file_open_failed: Counter -> usize,
+            /**
+            A new log file was created.
+            */
+            file_create: Counter -> usize,
+            /**
+            Attempting to create a new log file failed.
+            */
+            file_create_failed: Counter -> usize,
+            /**
+            Attempting to write to a log file failed.
+            */
+            file_write_failed: Counter -> usize,
+            /**
+            A log file was deleted.
+            */
+            file_delete: Counter -> usize,
+            /**
+            Attempting to delete a log file failed.
+            */
+            file_delete_failed: Counter -> usize,
+            /**
+            Attempting to format an event into a batch failed and was discarded.
+
+            This happens before the event is written to any log files.
+            */
+            event_format_failed: Counter -> usize,
+        }
+    }
+);
+
+/**
+Metrics produced by the file writer.
+
+You can enumerate the metrics using the [`emit::metric::Source`] implementation. See [`emit::metric`] for details.
+*/
+pub struct FileSetMetrics {
+    pub(crate) channel_metrics: emit_batcher::ChannelMetrics<crate::EventBatch>,
+    pub(crate) metrics: Arc<InternalMetrics>,
+}
+
+impl emit::metric::Source for FileSetMetrics {
+    fn sample_metrics<S: emit::metric::sampler::Sampler>(&self, sampler: S) {
+        self.channel_metrics
+            .sample_metrics(emit::metric::sampler::from_fn(|metric| {
+                sampler.metric(metric.by_ref().with_module(env!("CARGO_PKG_NAME")));
+            }));
+
+        for metric in self.metrics.sample() {
+            sampler.metric(metric);
+        }
+    }
+}