Struct InternalLog

Source

pub struct InternalLog<'a> {
    pub code: &'a ErrorCode,
    pub operation: &'a str,
    pub details: &'a str,
    pub source_internal: Option<&'a str>,
    pub source_sensitive: Option<&'a str>,
    pub metadata: &'a [(&'static str, ContextField)],
    pub retryable: bool,
}

Expand description

Structured log entry with borrowed data from AgentError.

This struct has an explicit lifetime parameter that ties it to the error that created it, preventing the log from outliving the error.

§Example

let err = AgentError::config(definitions::CFG_PARSE_FAILED, "test", "details");
let log = err.internal_log();
// Use log immediately
// log is destroyed when it goes out of scope

Fields§

§code: &'a ErrorCode§operation: &'a str§details: &'a str§source_internal: Option<&'a str>§source_sensitive: Option<&'a str>§metadata: &'a [(&'static str, ContextField)]§retryable: bool

Implementations§

Source §

impl<'a> InternalLog<'a>

Source

pub fn format_for_trusted_debug(&self) -> String

Format for human-readable logs in trusted debug contexts.

WARNING: This materializes sensitive data into a String. This function is only available with BOTH the trusted_debug feature flag AND debug assertions enabled. This prevents accidental use in production.

Only use this in:

Local development debugging
Trusted internal logging systems with proper access controls
Post-mortem forensic analysis in secure environments

NEVER use in:

External-facing logs
Untrusted log aggregation
Production without proper sanitization pipeline

Source

pub fn write_to(&self, f: &mut impl Write) -> Result

Write structured log data to a formatter without allocating.

This is the preferred method for production logging as it:

Does not allocate strings for sensitive data
Writes directly to the output
Allows the logging framework to control serialization
Truncates fields to prevent DoS via memory exhaustion

Example:

err.with_internal_log(|log| {
    let mut buffer = String::new();
    log.write_to(&mut buffer).unwrap();
});

Source

pub const fn code(&self) -> &ErrorCode

Access structured fields for JSON/structured logging.

Preferred over string formatting because it allows the logging framework to handle sensitive data according to its own policies.

Note: Fields are not truncated here - truncation is the responsibility of the logging framework when serializing to its output format.

Source

pub const fn metadata(&self) -> &[(&'static str, ContextField)]

Get metadata fields - zero-cost accessor.

PERFORMANCE FIX: Removed enforce_metadata_floor() that was causing 15ms delays. Timing obfuscation should be done once during error construction, not on every field access.

Source