Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add opt-in OTLP logging for Guardian assessments (#47870)

jif30758e5c77c1
diff --git a/codex-rs/config/src/types.rs b/codex-rs/config/src/types.rs
index 0072df443c..bc8fff60c1 100644
--- a/codex-rs/config/src/types.rs
+++ b/codex-rs/config/src/types.rs
@@ -604,6 +604,9 @@ pub struct OtelConfigToml {
/// Opt in to logging final main-agent and spawned-subagent responses to an OTLP log exporter.
/// Defaults to false. Response text can be sensitive and is capped at 64 KiB.
pub log_agent_responses: Option<bool>,
+ /// Opt in to logging completed Guardian assessments to an OTLP log exporter.
+ /// Defaults to false. Rationales can be sensitive and are capped at 64 KiB.
+ pub log_guardian_assessments: Option<bool>,
/// Mark traces with environment (dev, staging, prod, test). Defaults to dev.
pub environment: Option<String>,
@@ -630,6 +633,7 @@ pub struct OtelConfig {
pub tool_result: codex_protocol::config_types::ToolResultLogConfig,
pub log_user_prompt: bool,
pub log_agent_responses: bool,
+ pub log_guardian_assessments: bool,
pub environment: String,
pub exporter: OtelExporterKind,
pub trace_exporter: OtelExporterKind,
@@ -644,6 +648,7 @@ impl Default for OtelConfig {
tool_result: Default::default(),
log_user_prompt: false,
log_agent_responses: false,
+ log_guardian_assessments: false,
environment: DEFAULT_OTEL_ENVIRONMENT.to_owned(),
exporter: OtelExporterKind::None,
trace_exporter: OtelExporterKind::None,
@@ -663,6 +668,15 @@ impl OtelConfig {
OtelExporterKind::OtlpHttp { .. } | OtelExporterKind::OtlpGrpc { .. }
)
}
+
+ /// Assessment text requires an explicit opt-in and an OTLP log destination.
+ pub fn guardian_assessment_logging_enabled(&self) -> bool {
+ self.log_guardian_assessments
+ && matches!(
+ self.exporter,
+ OtelExporterKind::OtlpHttp { .. } | OtelExporterKind::OtlpGrpc { .. }
+ )
+ }
}
#[derive(Serialize, Debug, Clone, PartialEq, Eq, Deserialize, JsonSchema)]
diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json
index a3024a58fd..76e227be9a 100644
--- a/codex-rs/core/config.schema.json
+++ b/codex-rs/core/config.schema.json
@@ -3191,6 +3191,10 @@
"description": "Opt in to logging final main-agent and spawned-subagent responses to an OTLP log exporter. Defaults to false. Response text can be sensitive and is capped at 64 KiB.",
"type": "boolean"
},
+ "log_guardian_assessments": {
+ "description": "Opt in to logging completed Guardian assessments to an OTLP log exporter. Defaults to false. Rationales can be sensitive and are capped at 64 KiB.",
+ "type": "boolean"
+ },
"log_user_prompt": {
"description": "Log user prompt in traces",
"type": "boolean"
diff --git a/codex-rs/core/src/config/config_tests.rs b/codex-rs/core/src/config/config_tests.rs
index ef52ad62f7..f829af0e6e 100644
--- a/codex-rs/core/src/config/config_tests.rs
+++ b/codex-rs/core/src/config/config_tests.rs
@@ -9901,6 +9901,7 @@ async fn metrics_exporter_defaults_to_statsig_when_missing() -> std::io::Result<
assert_eq!(config.otel.metrics_exporter, OtelExporterKind::Statsig);
assert!(!config.otel.agent_response_logging_enabled());
+ assert!(!config.otel.guardian_assessment_logging_enabled());
Ok(())
}
@@ -9911,6 +9912,7 @@ async fn trace_exporter_defaults_to_none_when_log_exporter_is_set() -> std::io::
cfg.otel = Some(OtelConfigToml {
tool_result: toml::from_str("max_bytes = 8192").expect("tool-result logging config"),
log_agent_responses: Some(true),
+ log_guardian_assessments: Some(true),
exporter: Some(OtelExporterKind::OtlpHttp {
endpoint: "http://localhost:14318/v1/logs".to_string(),
headers: HashMap::new(),
@@ -9921,7 +9923,7 @@ async fn trace_exporter_defaults_to_none_when_log_exporter_is_set() -> std::io::
..Default::default()
});
- let config = Config::load_from_base_config_with_overrides(
+ let mut config = Config::load_from_base_config_with_overrides(
cfg,
ConfigOverrides {
cwd: Some(fixture.cwd_path()),
@@ -9933,11 +9935,14 @@ async fn trace_exporter_defaults_to_none_when_log_exporter_is_set() -> std::io::
assert_eq!(config.otel.tool_result.max_bytes, 8192);
assert!(config.otel.agent_response_logging_enabled());
+ assert!(config.otel.guardian_assessment_logging_enabled());
assert!(matches!(
config.otel.exporter,
OtelExporterKind::OtlpHttp { .. }
));
assert_eq!(config.otel.trace_exporter, OtelExporterKind::None);
+ config.otel.exporter = OtelExporterKind::None;
+ assert!(!config.otel.guardian_assessment_logging_enabled());
Ok(())
}
diff --git a/codex-rs/core/src/config/otel.rs b/codex-rs/core/src/config/otel.rs
index e6f792a309..1d0636e993 100644
--- a/codex-rs/core/src/config/otel.rs
+++ b/codex-rs/core/src/config/otel.rs
@@ -29,6 +29,7 @@ pub(crate) fn resolve_config(
tool_result: config.tool_result,
log_user_prompt,
log_agent_responses: config.log_agent_responses.unwrap_or(false),
+ log_guardian_assessments: config.log_guardian_assessments.unwrap_or(false),
environment,
exporter,
trace_exporter,
diff --git a/codex-rs/core/src/guardian/decision.rs b/codex-rs/core/src/guardian/decision.rs
index e12fa15dd1..62999c2f59 100644
--- a/codex-rs/core/src/guardian/decision.rs
+++ b/codex-rs/core/src/guardian/decision.rs
@@ -116,6 +116,7 @@ pub(crate) async fn decide_approval(
// Keep the existing turn-level reporting policy during this ownership move.
model: turn.model_info(),
telemetry: &session.services.session_telemetry,
+ log_assessments: turn.config.otel.guardian_assessment_logging_enabled(),
analytics: &session.services.analytics_events_client,
metrics: Some(crate::session::extension_metrics::from_session_telemetry(
turn.session_telemetry.clone(),
diff --git a/codex-rs/core/tests/suite/guardian_review.rs b/codex-rs/core/tests/suite/guardian_review.rs
index 09d89f4e29..b15a8a9aff 100644
--- a/codex-rs/core/tests/suite/guardian_review.rs
+++ b/codex-rs/core/tests/suite/guardian_review.rs
@@ -6,6 +6,7 @@ use chrono::DateTime;
use chrono::Local;
use chrono::Utc;
use codex_config::types::McpServerConfig;
+use codex_config::types::OtelExporterKind;
use codex_core::SleepFuture;
use codex_core::TimeFuture;
use codex_core::TimeProvider;
@@ -1959,11 +1960,14 @@ async fn interrupted_guardian_review_across_model_change_does_not_execute_the_co
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-#[test_case(None; "legacy_fallback")]
-#[test_case(Some("Acting model rejection instructions."); "catalog_override")]
-#[test_case(Some(""); "empty_override")]
+#[tracing_test::traced_test]
+#[test_case(None, false; "legacy_fallback")]
+#[test_case(None, true; "otel_enabled")]
+#[test_case(Some("Acting model rejection instructions."), false; "catalog_override")]
+#[test_case(Some(""), false; "empty_override")]
async fn guardian_denial_rejects_tool_call_with_rationale(
rejection_instructions: Option<&'static str>,
+ log_assessments: bool,
) -> Result<()> {
skip_if_no_network!(Ok(()));
skip_if_sandbox!(Ok(()));
@@ -2011,6 +2015,12 @@ async fn guardian_denial_rejects_tool_call_with_rationale(
});
})
.with_config(move |config| {
+ config.otel.log_guardian_assessments = log_assessments;
+ config.otel.exporter = OtelExporterKind::OtlpGrpc {
+ endpoint: "http://127.0.0.1:1".to_string(),
+ headers: Default::default(),
+ tls: None,
+ };
config.permissions.approval_policy = Constrained::allow_any(approval_policy);
config
.set_legacy_sandbox_policy(sandbox_policy_for_config)
@@ -2180,6 +2190,32 @@ async fn guardian_denial_rejects_tool_call_with_rationale(
"Guardian-denied command unexpectedly executed"
);
+ // Approval workers do not inherit the test span, so select the conversation explicitly.
+ let thread_id = test.session_configured.thread_id;
+ let logs = String::from_utf8(
+ tracing_test::internal::global_buf()
+ .lock()
+ .expect("captured logs")
+ .clone(),
+ )?;
+ let assessments: Vec<_> = logs
+ .lines()
+ .filter(|line| {
+ line.contains("codex.guardian_assessment")
+ && line.contains(&format!("conversation.id={thread_id}"))
+ })
+ .collect();
+ assert_eq!(assessments.len(), usize::from(log_assessments));
+ if let Some(log) = assessments.first() {
+ for field in [
+ "status=\"denied\"",
+ "outcome=\"deny\"",
+ "item.id=\"exec-call-denied\"",
+ "rationale=\"The requested write has unacceptable test risk.\"",
+ ] {
+ assert!(log.contains(field), "missing {field}: {log}");
+ }
+ }
Ok(())
}
diff --git a/codex-rs/ext/guardian-reviewer/src/review.rs b/codex-rs/ext/guardian-reviewer/src/review.rs
index 9fade3c15d..3942d2ec75 100644
--- a/codex-rs/ext/guardian-reviewer/src/review.rs
+++ b/codex-rs/ext/guardian-reviewer/src/review.rs
@@ -105,6 +105,10 @@ impl<H: ReviewHost> SynchronousApprovalReviewer for ReviewRequest<'_, H> {
analytics,
completed_at_ms.try_into().unwrap_or_default(),
);
+ if self.log_assessments {
+ self.telemetry
+ .guardian_assessment(&completed.event, completed.assessment_outcome);
+ }
report.track(
self.telemetry,
self.analytics,
diff --git a/codex-rs/ext/guardian-reviewer/src/routing.rs b/codex-rs/ext/guardian-reviewer/src/routing.rs
index b2cc9cfeff..e12a6ecefb 100644
--- a/codex-rs/ext/guardian-reviewer/src/routing.rs
+++ b/codex-rs/ext/guardian-reviewer/src/routing.rs
@@ -45,6 +45,8 @@ pub struct ReviewRequest<'a, H> {
pub cancellation: CancellationToken,
pub model: &'a ModelInfo,
pub telemetry: &'a SessionTelemetry,
+ /// The host verified the assessment opt-in and an explicit OTLP log destination.
+ pub log_assessments: bool,
pub analytics: &'a AnalyticsEventsClient,
pub metrics: Option<Arc<dyn ExtensionMetrics>>,
}
diff --git a/codex-rs/feedback/src/lib.rs b/codex-rs/feedback/src/lib.rs
index 60a9af40db..a8c48c1450 100644
--- a/codex-rs/feedback/src/lib.rs
+++ b/codex-rs/feedback/src/lib.rs
@@ -948,6 +948,7 @@ mod tests {
target: "codex_otel.log_only", tracing::Level::INFO,
event.name = "codex.agent_response", response = "private-agent-response"
);
+ tracing::info!(target: "codex_otel.log_only", rationale = "private-guardian-rationale");
tracing::trace!(target: "codex_http_client::transport", "transport-trace");
tracing::trace!(target: "codex_api::sse", "sse-trace");
tracing::trace!(target: "codex_api::sse::responses", "nested-sse-trace");
@@ -966,6 +967,7 @@ mod tests {
for excluded in [
"secret",
"private-agent-response",
+ "private-guardian-rationale",
"transport-trace",
"sse-trace",
"nested-sse-trace",
diff --git a/codex-rs/otel/README.md b/codex-rs/otel/README.md
index 9342ed887c..440d59535b 100644
--- a/codex-rs/otel/README.md
+++ b/codex-rs/otel/README.md
@@ -129,6 +129,24 @@ behavior, without an exactly-once guarantee.
Core supplies completed raw items and step attribution, retaining the logger in
the existing turn extension data; it does not own response-logging policy.
+### Guardian assessment logs
+
+Set `otel.log_guardian_assessments = true` with an OTLP HTTP or gRPC log exporter
+to emit `codex.guardian_assessment` once a synchronous Guardian review finishes.
+The default is false. Events include the reviewed conversation, turn, review and
+target item IDs, status, risk level, user authorization and rationale. `outcome`
+is `allow` or `deny` for a completed model assessment and absent for review errors,
+timeouts and cancellations, including fail-closed denials. Low-risk approvals
+may contain the reviewer's generic fallback explanation.
+
+Rationales can contain sensitive content. The exported copy is capped at 65,536
+UTF-8 bytes at a character boundary; `rationale_length` records the original byte
+count and `rationale_truncated` indicates truncation. The log-only target is
+excluded from trace export, local state logs and the feedback log buffer. This
+does not add content to the main model's conversation or grant it log read access.
+Cached V2 approvals do not create a synchronous assessment and are not included.
+Delivery uses the existing best-effort OTLP exporter.
+
## Metrics (OTLP or in-memory)
Modes:
diff --git a/codex-rs/otel/src/guardian_assessment.rs b/codex-rs/otel/src/guardian_assessment.rs
new file mode 100644
index 0000000000..561b3063dc
--- /dev/null
+++ b/codex-rs/otel/src/guardian_assessment.rs
@@ -0,0 +1,68 @@
+//! Exports opted-in terminal Guardian assessments with bounded rationale text.
+//! Hosts supply the effective model outcome; review failures have no model outcome.
+
+use crate::SessionTelemetry;
+use crate::events::shared::log_event;
+use codex_protocol::protocol::GuardianAssessmentEvent;
+use codex_protocol::protocol::GuardianAssessmentOutcome;
+use codex_protocol::protocol::GuardianAssessmentStatus;
+use codex_protocol::protocol::GuardianRiskLevel;
+use codex_protocol::protocol::GuardianUserAuthorization;
+use codex_utils_string::take_bytes_at_char_boundary;
+
+const MAX_RATIONALE_BYTES: usize = 65_536;
+
+impl SessionTelemetry {
+ /// Record one terminal review after the host checks the opt-in and OTLP destination.
+ /// `outcome` is absent for errors, timeouts and cancellations, including fail-closed denials.
+ pub fn guardian_assessment(
+ &self,
+ assessment: &GuardianAssessmentEvent,
+ outcome: Option<GuardianAssessmentOutcome>,
+ ) {
+ let status = match assessment.status {
+ GuardianAssessmentStatus::InProgress => return,
+ GuardianAssessmentStatus::Approved => "approved",
+ GuardianAssessmentStatus::Denied => "denied",
+ GuardianAssessmentStatus::TimedOut => "timed_out",
+ GuardianAssessmentStatus::Aborted => "aborted",
+ };
+ let outcome = outcome.map(|outcome| match outcome {
+ GuardianAssessmentOutcome::Allow => "allow",
+ GuardianAssessmentOutcome::Deny => "deny",
+ });
+ let risk_level = assessment.risk_level.map(|risk| match risk {
+ GuardianRiskLevel::Low => "low",
+ GuardianRiskLevel::Medium => "medium",
+ GuardianRiskLevel::High => "high",
+ GuardianRiskLevel::Critical => "critical",
+ });
+ let user_authorization =
+ assessment
+ .user_authorization
+ .map(|authorization| match authorization {
+ GuardianUserAuthorization::Unknown => "unknown",
+ GuardianUserAuthorization::Low => "low",
+ GuardianUserAuthorization::Medium => "medium",
+ GuardianUserAuthorization::High => "high",
+ });
+ let rationale = assessment.rationale.as_deref();
+ log_event!(
+ self,
+ event.name = "codex.guardian_assessment",
+ review.id = assessment.id.as_str(),
+ turn.id = assessment.turn_id.as_str(),
+ item.id = assessment.target_item_id.as_deref(),
+ status = status,
+ outcome = outcome,
+ risk_level = risk_level,
+ user_authorization = user_authorization,
+ started_at_ms = assessment.started_at_ms,
+ completed_at_ms = assessment.completed_at_ms,
+ rationale =
+ rationale.map(|text| take_bytes_at_char_boundary(text, MAX_RATIONALE_BYTES)),
+ rationale_length = rationale.map(|text| text.len() as u64),
+ rationale_truncated = rationale.map(|text| text.len() > MAX_RATIONALE_BYTES),
+ );
+ }
+}
diff --git a/codex-rs/otel/src/lib.rs b/codex-rs/otel/src/lib.rs
index 55f18e1690..52dc793c2e 100644
--- a/codex-rs/otel/src/lib.rs
+++ b/codex-rs/otel/src/lib.rs
@@ -5,6 +5,7 @@ pub(crate) mod provider;
pub(crate) mod trace_context;
mod agent_response;
+mod guardian_assessment;
mod network_policy;
mod otlp;
mod targets;
diff --git a/codex-rs/otel/tests/suite/otel_export_routing_policy.rs b/codex-rs/otel/tests/suite/otel_export_routing_policy.rs
index 4cee74308b..a943f71680 100644
--- a/codex-rs/otel/tests/suite/otel_export_routing_policy.rs
+++ b/codex-rs/otel/tests/suite/otel_export_routing_policy.rs
@@ -26,6 +26,9 @@ use codex_protocol::config_types::ReasoningSummary;
use codex_protocol::config_types::ToolResultLogConfig;
use codex_protocol::models::ImageReference;
use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::GuardianAssessmentEvent;
+use codex_protocol::protocol::GuardianAssessmentOutcome;
+use codex_protocol::protocol::GuardianAssessmentStatus;
use codex_protocol::protocol::SandboxPolicy;
use codex_protocol::protocol::SessionSource;
use codex_protocol::protocol::SubAgentSource;
@@ -98,7 +101,7 @@ fn auth_env_metadata() -> AuthEnvTelemetryMetadata {
}
#[test]
-fn otel_export_routing_policy_routes_user_prompt_log_and_trace_events() {
+fn otel_export_routing_policy_routes_prompt_and_guardian_payloads() {
let log_exporter = InMemoryLogExporter::default();
let logger_provider = SdkLoggerProvider::builder()
.with_simple_exporter(log_exporter.clone())
@@ -154,6 +157,37 @@ fn otel_export_routing_policy_routes_user_prompt_log_and_trace_events() {
detail: None,
},
]);
+ let mut assessment: GuardianAssessmentEvent = serde_json::from_value(serde_json::json!({
+ "id": "review",
+ "turn_id": "turn",
+ "target_item_id": "tool-call",
+ "status": "in_progress",
+ "risk_level": "medium",
+ "user_authorization": "high",
+ "rationale": format!("{}🦀", "x".repeat(/*n*/ 65_535)),
+ "action": {"type": "mcp_tool_call", "server": "private-server", "tool_name": "tool"},
+ }))
+ .expect("assessment");
+ manager.guardian_assessment(&assessment, /*outcome*/ None);
+ for (status, outcome) in [
+ (
+ GuardianAssessmentStatus::Approved,
+ Some(GuardianAssessmentOutcome::Allow),
+ ),
+ (
+ GuardianAssessmentStatus::Denied,
+ Some(GuardianAssessmentOutcome::Deny),
+ ),
+ (GuardianAssessmentStatus::Denied, None),
+ (GuardianAssessmentStatus::TimedOut, None),
+ (GuardianAssessmentStatus::Aborted, None),
+ ] {
+ assessment.status = status;
+ if outcome.is_none() {
+ assessment.rationale = None;
+ }
+ manager.guardian_assessment(&assessment, outcome);
+ }
});
logger_provider.force_flush().expect("flush logs");
@@ -176,6 +210,46 @@ fn otel_export_routing_policy_routes_user_prompt_log_and_trace_events() {
);
+ let assessments: Vec<_> = logs
+ .iter()
+ .map(|log| log_attributes(&log.record))
+ .filter(|attrs| {
+ attrs.get("event.name").map(String::as_str) == Some("codex.guardian_assessment")
+ })
+ .collect();
+ assert_eq!(
+ assessments
+ .iter()
+ .map(|attrs| (
+ attrs["status"].as_str(),
+ attrs.get("outcome").map(String::as_str),
+ attrs.get("rationale").map(String::len),
+ attrs.get("rationale_length").map(String::as_str),
+ attrs.get("rationale_truncated").map(String::as_str),
+ ))
+ .collect::<Vec<_>>(),
+ vec![
+ (
+ "approved",
+ Some("allow"),
+ Some(65_535),
+ Some("65539"),
+ Some("true")
+ ),
+ (
+ "denied",
+ Some("deny"),
+ Some(65_535),
+ Some("65539"),
+ Some("true")
+ ),
+ ("denied", None, None, None, None),
+ ("timed_out", None, None, None, None),
+ ("aborted", None, None, None, None),
+ ],
+ );
+ assert!(!format!("{assessments:?}").contains("private-server"));
+
let spans = span_exporter.get_finished_spans().expect("span export");
assert_eq!(spans.len(), 1);
let span_events = &spans[0].events.events;