Merge pull request #316 from cipherstash/refactor-logging-targets

refactor: centralize log target definitions using declarative macro

Author: tobyhede

DEVELOPMENT.md

@@ -244,17 +244,23 @@ Default level is `Info`.
 
 Proxy has multiple "log targets" corresponding to the internal domains.
 
-Set log levels for a specific log target to turn on or turn of more verbose logging:
+Set log levels for a specific log target to turn on or turn off more verbose logging:
 
 ```
 Target          | ENV
 --------------- | -------------------------------------
 DEVELOPMENT     | CS_LOG__DEVELOPMENT_LEVEL
 AUTHENTICATION  | CS_LOG__AUTHENTICATION_LEVEL
+CONFIG          | CS_LOG__CONFIG_LEVEL
 CONTEXT         | CS_LOG__CONTEXT_LEVEL
+ENCODING        | CS_LOG__ENCODING_LEVEL
 ENCRYPT         | CS_LOG__ENCRYPT_LEVEL
+DECRYPT         | CS_LOG__DECRYPT_LEVEL
+ENCRYPT_CONFIG  | CS_LOG__ENCRYPT_CONFIG_LEVEL
 KEYSET          | CS_LOG__KEYSET_LEVEL
+MIGRATE         | CS_LOG__MIGRATE_LEVEL
 PROTOCOL        | CS_LOG__PROTOCOL_LEVEL
+PROXY           | CS_LOG__PROXY_LEVEL
 MAPPER          | CS_LOG__MAPPER_LEVEL
 SCHEMA          | CS_LOG__SCHEMA_LEVEL
 ```
@@ -547,12 +553,39 @@ Debug logging is very verbose, and targets allow configuration of granular log l
 A `target` is a string value that is added to the standard tracing macro calls (`debug!, error!, etc`).
 Log levels can be configured for each `target` individually.
 
-A number of targets are already defined in `log.rs`.
+### Logging Architecture
 
-The targets are aligned with the different components and contexts (`PROTOCOL, AUTHENTICATION, MAPPER, etc`)
+The logging system uses a declarative macro approach for managing log targets:
+
+- **Single source of truth**: All log targets are defined in `packages/cipherstash-proxy/src/log/targets.rs` using the `define_log_targets!` macro
+- **Automatic generation**: The macro generates target constants, configuration struct fields, and accessor functions
+- **Type safety**: Uses a generated `LogTargetLevels` struct with serde flattening for config integration
+- **Self-documenting**: Clear separation between core config and target-specific levels
+
+The targets are aligned with the different components and contexts (`PROTOCOL`, `AUTHENTICATION`, `MAPPER`, etc.).
 
 There is a general `DEVELOPMENT` target for logs that don't quite fit into a specific category.
 
+### Adding a New Log Target
+
+To add a new log target, you only need to add **one line** to the macro in `packages/cipherstash-proxy/src/log/targets.rs`:
+
+```rust
+define_log_targets!(
+    (DEVELOPMENT, development_level),
+    (AUTHENTICATION, authentication_level),
+    // ... existing targets ...
+    (NEW_TARGET, new_target_level), // <- Add this line
+);
+```
+
+The constant name (e.g., `NEW_TARGET`) is automatically converted to a string value using `stringify!()`, so `NEW_TARGET` becomes `"NEW_TARGET"` for use in logging calls.
+
+This automatically:
+- Creates the `NEW_TARGET` constant for use in logging calls
+- Generates the `new_target_level` field in `LogTargetLevels` struct
+- Creates the environment variable `CS_LOG__NEW_TARGET_LEVEL`
+- Adds the target to all logging functions and validation
 
 ### Available targets
 
@@ -561,15 +594,20 @@ Target          | ENV
 --------------- | -------------------------------------
 DEVELOPMENT     | CS_LOG__DEVELOPMENT_LEVEL
 AUTHENTICATION  | CS_LOG__AUTHENTICATION_LEVEL
+CONFIG          | CS_LOG__CONFIG_LEVEL
 CONTEXT         | CS_LOG__CONTEXT_LEVEL
+ENCODING        | CS_LOG__ENCODING_LEVEL
 ENCRYPT         | CS_LOG__ENCRYPT_LEVEL
+DECRYPT         | CS_LOG__DECRYPT_LEVEL
+ENCRYPT_CONFIG  | CS_LOG__ENCRYPT_CONFIG_LEVEL
 KEYSET          | CS_LOG__KEYSET_LEVEL
+MIGRATE         | CS_LOG__MIGRATE_LEVEL
 PROTOCOL        | CS_LOG__PROTOCOL_LEVEL
+PROXY           | CS_LOG__PROXY_LEVEL
 MAPPER          | CS_LOG__MAPPER_LEVEL
 SCHEMA          | CS_LOG__SCHEMA_LEVEL
 ```
 
-
 ### Example
 
 The default log level for the proxy is `info`.
@@ -585,13 +623,23 @@ CS_LOG__MAPPER_LEVEL = "debug"
 Log `debug` output for the `MAPPER` target:
 
 ```rust
-    debug!(
-        target: MAPPER,
-        client_id = self.context.client_id,
-        identifier = ?identifier
-    );
+debug!(
+    target: MAPPER,
+    client_id = self.context.client_id,
+    identifier = ?identifier
+);
 ```
 
+### Implementation Details
+
+The logging system uses these key components:
+
+- **`define_log_targets!` macro** in `log/targets.rs`: Generates all logging infrastructure
+- **`LogTargetLevels` struct**: Auto-generated struct containing all target level fields
+- **`LogConfig` struct**: Main configuration with `#[serde(flatten)]` integration
+- **Target constants**: Exported for use in logging calls (e.g., `MAPPER`, `PROTOCOL`)
+- **Environment variables**: Auto-generated from target names (e.g., `CS_LOG__MAPPER_LEVEL`)
+
 ## Benchmarks
 
 Benchmarking is integrated into CI, and can be run locally.

packages/cipherstash-proxy/src/config/log.rs

@@ -3,6 +3,9 @@ use std::{fmt::Display, io::IsTerminal};
 use clap::ValueEnum;
 use serde::Deserialize;
 
+// Import the generated LogTargetLevels struct
+use crate::log::targets::LogTargetLevels;
+
 #[derive(Clone, Debug, Deserialize)]
 pub struct LogConfig {
     #[serde(default = "LogConfig::default_ansi_enabled")]
@@ -17,44 +20,10 @@ pub struct LogConfig {
     #[serde(default = "LogConfig::default_log_level")]
     pub level: LogLevel,
 
-    #[serde(default = "LogConfig::default_log_level")]
-    pub development_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub authentication_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub config_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub context_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub encoding_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub encrypt_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub decrypt_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub encrypt_config_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub keyset_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub migrate_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub protocol_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub mapper_level: LogLevel,
-
-    #[serde(default = "LogConfig::default_log_level")]
-    pub schema_level: LogLevel,
+    // All log target levels - automatically generated and flattened from LogTargetLevels
+    // To add a new target: just add it to the define_log_targets! macro in log/targets.rs
+    #[serde(flatten)]
+    pub targets: LogTargetLevels,
 }
 
 #[derive(Clone, Copy, Debug, Deserialize, PartialEq, ValueEnum)]
@@ -121,19 +90,8 @@ impl LogConfig {
             output: LogConfig::default_log_output(),
             ansi_enabled: LogConfig::default_ansi_enabled(),
             level,
-            development_level: level,
-            authentication_level: level,
-            context_level: level,
-            encoding_level: level,
-            encrypt_level: level,
-            encrypt_config_level: level,
-            decrypt_level: level,
-            keyset_level: level,
-            migrate_level: level,
-            protocol_level: level,
-            mapper_level: level,
-            schema_level: level,
-            config_level: level,
+            // All target levels automatically set using generated LogTargetLevels
+            targets: LogTargetLevels::with_level(level),
         }
     }
 

packages/cipherstash-proxy/src/log/mod.rs

@@ -1,4 +1,5 @@
 pub mod subscriber;
+pub mod targets;
 
 use crate::config::{LogConfig, LogFormat};
 use std::sync::Once;
@@ -12,22 +13,11 @@ use tracing_subscriber::{
 };
 
 // Log targets used in logs like `debug!(target: DEVELOPMENT, "Flush message buffer");`
-// If you add one, make sure `log_targets()` and `log_level_for()` functions are updated.
-pub const DEVELOPMENT: &str = "development"; // one for various hidden "development mode" messages
-pub const AUTHENTICATION: &str = "authentication";
-pub const CONFIG: &str = "config";
-pub const CONTEXT: &str = "context";
-pub const ENCRYPT: &str = "encrypt";
-pub const PROXY: &str = "proxy";
-pub const DECRYPT: &str = "decrypt";
-pub const ENCODING: &str = "encoding";
-pub const ENCRYPT_CONFIG: &str = "encrypt_config";
-pub const KEYSET: &str = "keyset";
-pub const MIGRATE: &str = "migrate";
-pub const PARSER: &str = "parser";
-pub const PROTOCOL: &str = "protocol";
-pub const MAPPER: &str = "mapper";
-pub const SCHEMA: &str = "schema";
+// All targets are now defined in the targets module using the define_log_targets! macro.
+pub use targets::{
+    AUTHENTICATION, CONFIG, CONTEXT, DECRYPT, DEVELOPMENT, ENCODING, ENCRYPT, ENCRYPT_CONFIG,
+    KEYSET, MAPPER, MIGRATE, PROTOCOL, PROXY, SCHEMA,
+};
 
 static INIT: Once = Once::new();
 
@@ -59,6 +49,9 @@ mod tests {
     use crate::config::LogLevel;
 
     use super::*;
+    use crate::log::targets::{
+        LogTargetLevels, AUTHENTICATION, CONTEXT, DEVELOPMENT, KEYSET, MAPPER, PROTOCOL, SCHEMA,
+    };
     use crate::test_helpers::MockMakeWriter;
     use tracing::dispatcher::set_default;
     use tracing::{debug, error, info, trace, warn};
@@ -119,19 +112,22 @@ mod tests {
             output: LogConfig::default_log_output(),
             ansi_enabled: LogConfig::default_ansi_enabled(),
             level: LogLevel::Info,
-            development_level: LogLevel::Info,
-            authentication_level: LogLevel::Debug,
-            context_level: LogLevel::Error,
-            encoding_level: LogLevel::Error,
-            encrypt_level: LogLevel::Error,
-            encrypt_config_level: LogLevel::Error,
-            decrypt_level: LogLevel::Error,
-            keyset_level: LogLevel::Trace,
-            migrate_level: LogLevel::Trace,
-            protocol_level: LogLevel::Info,
-            mapper_level: LogLevel::Info,
-            schema_level: LogLevel::Info,
-            config_level: LogLevel::Info,
+            targets: LogTargetLevels {
+                development_level: LogLevel::Info,
+                authentication_level: LogLevel::Debug,
+                context_level: LogLevel::Error,
+                encoding_level: LogLevel::Error,
+                encrypt_level: LogLevel::Error,
+                encrypt_config_level: LogLevel::Error,
+                decrypt_level: LogLevel::Error,
+                keyset_level: LogLevel::Trace,
+                migrate_level: LogLevel::Trace,
+                protocol_level: LogLevel::Info,
+                proxy_level: LogLevel::Info,
+                mapper_level: LogLevel::Info,
+                schema_level: LogLevel::Info,
+                config_level: LogLevel::Info,
+            },
         };
 
         let subscriber =
@@ -142,48 +138,48 @@ mod tests {
         let _default = set_default(&subscriber.into());
 
         // with development level 'info', info should be logged but not debug
-        debug!(target: "development", "debug/development");
-        info!(target: "development", "info/development");
+        debug!(target: DEVELOPMENT, "debug/development");
+        info!(target: DEVELOPMENT, "info/development");
         let log_contents = make_writer.get_string();
         assert!(!log_contents.contains("debug/development"));
         assert!(log_contents.contains("info/development"));
 
         // with authentication level 'debug', debug should be logged but not trace
-        trace!(target: "authentication", "trace/authentication");
-        debug!(target: "authentication", "debug/authentication");
+        trace!(target: AUTHENTICATION, "trace/authentication");
+        debug!(target: AUTHENTICATION, "debug/authentication");
         let log_contents = make_writer.get_string();
         assert!(!log_contents.contains("trace/authentication"));
         assert!(log_contents.contains("debug/authentication"));
 
         // with context level 'error', error should be logged but not warn
-        warn!(target: "context", "warn/context");
-        error!(target: "context", "error/context");
+        warn!(target: CONTEXT, "warn/context");
+        error!(target: CONTEXT, "error/context");
         let log_contents = make_writer.get_string();
         assert!(!log_contents.contains("warn/context"));
         assert!(log_contents.contains("error/context"));
 
         // with keyset level 'trace', trace should be logged
-        trace!(target: "keyset", "trace/keyset");
+        trace!(target: KEYSET, "trace/keyset");
         let log_contents = make_writer.get_string();
         assert!(log_contents.contains("trace/keyset"));
 
         // with protocol level 'info', info should be logged but not debug
-        debug!(target: "protocol", "debug/protocol");
-        info!(target: "protocol", "info/protocol");
+        debug!(target: PROTOCOL, "debug/protocol");
+        info!(target: PROTOCOL, "info/protocol");
         let log_contents = make_writer.get_string();
         assert!(!log_contents.contains("debug/protocol"));
         assert!(log_contents.contains("info/protocol"));
 
         // with mapper level 'info', info should be logged but not debug
-        debug!(target: "mapper", "debug/mapper");
-        info!(target: "mapper", "info/mapper");
+        debug!(target: MAPPER, "debug/mapper");
+        info!(target: MAPPER, "info/mapper");
         let log_contents = make_writer.get_string();
         assert!(!log_contents.contains("debug/mapper"));
         assert!(log_contents.contains("info/mapper"));
 
         // with schema level 'info', info should be logged but not debug
-        debug!(target: "schema", "debug/schema");
-        info!(target: "schema", "info/schema");
+        debug!(target: SCHEMA, "debug/schema");
+        info!(target: SCHEMA, "info/schema");
         let log_contents = make_writer.get_string();
         assert!(!log_contents.contains("debug/schema"));
         assert!(log_contents.contains("info/schema"));

packages/cipherstash-proxy/src/log/subscriber.rs

@@ -1,42 +1,11 @@
 use crate::config::{LogConfig, LogLevel, LogOutput};
-use crate::log::{AUTHENTICATION, CONTEXT, DEVELOPMENT, ENCRYPT, KEYSET, MAPPER, PROTOCOL, SCHEMA};
+use crate::log::targets::{log_level_for, log_targets};
 use tracing_subscriber::filter::EnvFilter;
 use tracing_subscriber::fmt::format::{DefaultFields, Format};
 use tracing_subscriber::fmt::writer::BoxMakeWriter;
 use tracing_subscriber::fmt::SubscriberBuilder;
 use tracing_subscriber::FmtSubscriber;
 
-use super::DECRYPT;
-
-fn log_targets() -> Vec<&'static str> {
-    vec![
-        DEVELOPMENT,
-        AUTHENTICATION,
-        CONTEXT,
-        DECRYPT,
-        ENCRYPT,
-        KEYSET,
-        PROTOCOL,
-        MAPPER,
-        SCHEMA,
-    ]
-}
-
-fn log_level_for(config: &LogConfig, target: &str) -> LogLevel {
-    match target {
-        DEVELOPMENT => config.development_level,
-        AUTHENTICATION => config.authentication_level,
-        CONTEXT => config.context_level,
-        DECRYPT => config.decrypt_level,
-        ENCRYPT => config.encrypt_level,
-        KEYSET => config.keyset_level,
-        PROTOCOL => config.protocol_level,
-        MAPPER => config.mapper_level,
-        SCHEMA => config.schema_level,
-        _ => config.level,
-    }
-}
-
 pub fn builder(
     config: &LogConfig,
 ) -> SubscriberBuilder<DefaultFields, Format, EnvFilter, BoxMakeWriter> {