feat: Add DSMIL telemetry level control and annotations

cursoragent · SWORDIntel · cursoragent · commit f59d623f2b6f · 2025-12-05T01:14:45.000Z
This commit introduces a new command-line option and module flag to control the DSMIL telemetry instrumentation level. It also adds new annotations for various categories like network I/O, crypto, process, file, untrusted data, and error handling. The runtime library is updated to support these new features, including level-based filtering and the ability to log more detailed telemetry events.

Co-authored-by: intel &lt;intel@swordintelligence.airforce&gt;
diff --git a/clang/include/clang/Basic/CodeGenOptions.h b/clang/include/clang/Basic/CodeGenOptions.h
@@ -298,6 +298,9 @@ class CodeGenOptions : public CodeGenOptionsBase {
   /// file, for example with -save-temps.
   std::string MainFileName;
 
+  /// DSMIL telemetry instrumentation level: "off", "min", "normal", "debug", "trace"
+  std::string DSMILTelemetryLevel = "normal";
+
   /// The name for the split debug info file used for the DW_AT_[GNU_]dwo_name
   /// attribute in the skeleton CU.
   std::string SplitDwarfFile;
diff --git a/clang/include/clang/Options/Options.td b/clang/include/clang/Options/Options.td
@@ -3029,6 +3029,12 @@ def finstrument_function_entry_bare : Flag<["-"], "finstrument-function-entry-ba
   Visibility<[ClangOption, CC1Option]>,
   HelpText<"Instrument function entry only, after inlining, without arguments to the instrumentation call">,
   MarshallingInfoFlag<CodeGenOpts<"InstrumentFunctionEntryBare">>;
+def fdsmil_telemetry_level_EQ : Joined<["-"], "fdsmil-telemetry-level=">,
+  Group<f_Group>,
+  Visibility<[ClangOption, CC1Option]>,
+  HelpText<"Set DSMIL telemetry instrumentation level: off, min, normal, debug, trace">,
+  Values<"off,min,normal,debug,trace">,
+  MarshallingInfoString<CodeGenOpts<"DSMILTelemetryLevel">, "normal">;
 def fcf_protection_EQ : Joined<["-"], "fcf-protection=">,
   Visibility<[ClangOption, CLOption, CC1Option]>, Group<f_Group>,
   HelpText<"Instrument control-flow architecture protection">, Values<"return,branch,full,none">;
diff --git a/dsmil/include/dsmil_attributes.h b/dsmil/include/dsmil_attributes.h
@@ -1596,6 +1596,147 @@
 
 /** @} */
 
+/**
+ * @defgroup DSMIL_TELEMETRY_ANNOTATIONS Generic Telemetry Annotations (v1.9)
+ * @{
+ */
+
+/**
+ * @brief Mark function for network I/O telemetry
+ *
+ * Functions annotated with DSMIL_NET_IO are instrumented with telemetry
+ * for network operations (connect, send, recv, etc.).
+ *
+ * Example:
+ * @code
+ * DSMIL_NET_IO
+ * int connect_to_server(const char *host, int port) {
+ *     // Automatically instrumented with network I/O telemetry
+ *     return socket_connect(host, port);
+ * }
+ * @endcode
+ *
+ * @note Maps to DSMIL_TELEMETRY_NET_IO event type
+ * @note Category: "net"
+ */
+#define DSMIL_NET_IO \
+    __attribute__((annotate("dsmil.net_io")))
+
+/**
+ * @brief Mark function for cryptographic operation telemetry
+ *
+ * Functions annotated with DSMIL_CRYPTO are instrumented with telemetry
+ * for cryptographic operations (encrypt, decrypt, sign, verify, etc.).
+ *
+ * Example:
+ * @code
+ * DSMIL_CRYPTO
+ * int aes_encrypt(const uint8_t *key, const uint8_t *plaintext, uint8_t *ciphertext) {
+ *     // Automatically instrumented with crypto telemetry
+ *     return do_aes_encrypt(key, plaintext, ciphertext);
+ * }
+ * @endcode
+ *
+ * @note Maps to DSMIL_TELEMETRY_CRYPTO event type
+ * @note Category: "crypto"
+ */
+#define DSMIL_CRYPTO \
+    __attribute__((annotate("dsmil.crypto")))
+
+/**
+ * @brief Mark function for process/system operation telemetry
+ *
+ * Functions annotated with DSMIL_PROCESS are instrumented with telemetry
+ * for process/system operations (fork, exec, kill, etc.).
+ *
+ * Example:
+ * @code
+ * DSMIL_PROCESS
+ * int spawn_child_process(const char *cmd) {
+ *     // Automatically instrumented with process telemetry
+ *     return fork_and_exec(cmd);
+ * }
+ * @endcode
+ *
+ * @note Maps to DSMIL_TELEMETRY_PROCESS event type
+ * @note Category: "process"
+ */
+#define DSMIL_PROCESS \
+    __attribute__((annotate("dsmil.process")))
+
+/**
+ * @brief Mark function for file I/O telemetry
+ *
+ * Functions annotated with DSMIL_FILE are instrumented with telemetry
+ * for file operations (open, read, write, close, etc.).
+ *
+ * Example:
+ * @code
+ * DSMIL_FILE
+ * FILE* open_config_file(const char *filename) {
+ *     // Automatically instrumented with file I/O telemetry
+ *     return fopen(filename, "r");
+ * }
+ * @endcode
+ *
+ * @note Maps to DSMIL_TELEMETRY_FILE event type
+ * @note Category: "file"
+ */
+#define DSMIL_FILE \
+    __attribute__((annotate("dsmil.file")))
+
+/**
+ * @brief Mark function handling untrusted data
+ *
+ * Functions annotated with DSMIL_UNTRUSTED are instrumented with telemetry
+ * for operations on untrusted data (network input, user input, etc.).
+ *
+ * Example:
+ * @code
+ * DSMIL_UNTRUSTED
+ * void process_user_input(const char *input) {
+ *     // Automatically instrumented with untrusted data telemetry
+ *     validate_and_process(input);
+ * }
+ * @endcode
+ *
+ * @note Maps to DSMIL_TELEMETRY_UNTRUSTED event type
+ * @note Category: "untrusted"
+ * @note Related to DSMIL_UNTRUSTED_INPUT attribute
+ */
+#define DSMIL_UNTRUSTED \
+    __attribute__((annotate("dsmil.untrusted")))
+
+/**
+ * @brief Mark function as error handler
+ *
+ * Functions annotated with DSMIL_ERROR_HANDLER are instrumented with telemetry
+ * for error handling operations. If function name suggests panic (e.g., panic,
+ * fatal), emits PANIC events instead of ERROR events.
+ *
+ * Example:
+ * @code
+ * DSMIL_ERROR_HANDLER
+ * void handle_error(int err_code, const char *msg) {
+ *     // Automatically instrumented with error telemetry
+ *     log_error(err_code, msg);
+ * }
+ *
+ * DSMIL_ERROR_HANDLER
+ * void panic(const char *msg) {
+ *     // Automatically emits PANIC events (name suggests panic)
+ *     abort();
+ * }
+ * @endcode
+ *
+ * @note Maps to DSMIL_TELEMETRY_ERROR or DSMIL_TELEMETRY_PANIC event type
+ * @note Category: "error"
+ */
+#define DSMIL_ERROR_HANDLER \
+    __attribute__((annotate("dsmil.error_handler")))
+
+/** @} */
+
 /**
  * @defgroup DSMIL_MEMORY Memory and Performance Attributes
  * @{
diff --git a/dsmil/include/dsmil_ot_telemetry.h b/dsmil/include/dsmil_ot_telemetry.h
@@ -26,6 +26,18 @@ extern "C" {
  * @{
  */
 
+/**
+ * Telemetry instrumentation levels
+ * Lattice: off < min < normal < debug < trace
+ */
+typedef enum {
+    DSMIL_TELEMETRY_LEVEL_OFF = 0,    /**< No telemetry */
+    DSMIL_TELEMETRY_LEVEL_MIN = 1,    /**< Minimal telemetry (safety-critical only) */
+    DSMIL_TELEMETRY_LEVEL_NORMAL = 2, /**< Normal telemetry (entry probes) */
+    DSMIL_TELEMETRY_LEVEL_DEBUG = 3,   /**< Debug telemetry (entry + exit + timing) */
+    DSMIL_TELEMETRY_LEVEL_TRACE = 4   /**< Trace telemetry (all + sampling) */
+} dsmil_telemetry_level_t;
+
 /**
  * OT telemetry event types
  */
@@ -43,7 +55,16 @@ typedef enum {
     DSMIL_TELEMETRY_SS7_MSG_TX = 21,      /**< SS7 message transmitted */
     DSMIL_TELEMETRY_SIGTRAN_MSG_RX = 22,  /**< SIGTRAN message received */
     DSMIL_TELEMETRY_SIGTRAN_MSG_TX = 23,  /**< SIGTRAN message transmitted */
-    DSMIL_TELEMETRY_SIG_ANOMALY = 24      /**< Signaling anomaly detected */
+    DSMIL_TELEMETRY_SIG_ANOMALY = 24,     /**< Signaling anomaly detected */
+
+    // Generic annotation event types (30-36)
+    DSMIL_TELEMETRY_NET_IO = 30,          /**< Network I/O operation */
+    DSMIL_TELEMETRY_CRYPTO = 31,          /**< Cryptographic operation */
+    DSMIL_TELEMETRY_PROCESS = 32,         /**< Process/system operation */
+    DSMIL_TELEMETRY_FILE = 33,            /**< File I/O operation */
+    DSMIL_TELEMETRY_UNTRUSTED = 34,       /**< Untrusted data handling */
+    DSMIL_TELEMETRY_ERROR = 35,           /**< Error handler invocation */
+    DSMIL_TELEMETRY_PANIC = 36            /**< Panic/fatal error */
 } dsmil_telemetry_event_type_t;
 
 /**
@@ -84,6 +105,14 @@ typedef struct {
     uint32_t    sigtran_rctx;                 /**< SIGTRAN Routing Context (M3UA/SUA), 0 if not set */
     uint8_t     ss7_msg_class;                /**< MTP3/TCAP/CAP message class (if mapped) */
     uint8_t     ss7_msg_type;                 /**< Message type (approximate mapping) */
+
+    // Generic annotation fields (for event types 30-36)
+    const char *category;                     /**< Event category: "net", "crypto", "process", "file", "untrusted", "error" */
+    const char *op;                           /**< Operation name (e.g., "connect", "encrypt", "open") */
+    int32_t     status_code;                  /**< Status/return code (0 = success, negative = error) */
+    const char *resource;                     /**< Resource identifier (e.g., filename, socket, key name) */
+    const char *error_msg;                    /**< Error message (if status_code != 0) */
+    uint64_t    elapsed_ns;                   /**< Elapsed time in nanoseconds (debug/trace levels) */
 } dsmil_telemetry_event_t;
 
 /**
@@ -181,6 +210,31 @@ void dsmil_ot_telemetry_shutdown(void);
  */
 int dsmil_ot_telemetry_is_enabled(void);
 
+/**
+ * Get current telemetry level
+ *
+ * @return Current telemetry level (combines compile-time and runtime settings)
+ *
+ * Combines compile-time level (from module flag) with runtime override
+ * (from DSMIL_TELEMETRY_LEVEL environment variable). Enforces lattice:
+ * off < min < normal < debug < trace. Mission profile overrides may
+ * force minimum levels unless CLI demanded stricter.
+ */
+dsmil_telemetry_level_t dsmil_telemetry_get_level(void);
+
+/**
+ * Check if telemetry level allows event category
+ *
+ * @param event_type Event type
+ * @param category Event category (e.g., "net", "crypto", "process")
+ * @return 1 if allowed, 0 if filtered
+ *
+ * Centralized logic for level-based gating. Events are filtered based on
+ * current telemetry level and event category.
+ */
+int dsmil_telemetry_level_allows(dsmil_telemetry_event_type_t event_type,
+                                  const char *category);
+
 /** @} */
 
 #ifdef __cplusplus
diff --git a/dsmil/lib/Passes/DsmilTelemetryPass.cpp b/dsmil/lib/Passes/DsmilTelemetryPass.cpp
diff --git a/dsmil/runtime/dsmil_ot_telemetry.c b/dsmil/runtime/dsmil_ot_telemetry.c
