Support OTel header helpers in local managed requirements (#62110)

## What changed

- Allow system `requirements.toml` and MDM requirements to set `otel.headers_helper` and `otel.headers_helper_refresh_interval_ms`, and expose both fields through the requirements API.
- Require an absolute executable path and run managed helpers directly from their installation directory. Reject helper settings from cloud requirements.
- Restrict managed helper headers to OTLP HTTP exporters with nonempty endpoints configured in the same requirements layer. Replacing the helper or an exporter revokes the previous binding.
- Document deployment and rollback requirements, including client compatibility and pausing affected exports until a failed helper recovers.

## Testing

Add coverage for exporter layer boundaries, cloud policy rejection, relative path rejection, managed helper execution and recovery, missing executable diagnostics, and requirements API output.

GitOrigin-RevId: 271058010c2e3090eb97cb357b70be4dc41b43db
This commit is contained in:
Abhinav
2026-11-17 21:10:09 +00:00
committed by copyberry
parent 8011b92bc8
commit 8fca6ffb92
24 changed files with 507 additions and 10 deletions
@@ -17556,6 +17556,20 @@
}
]
},
"headers_helper": {
"type": [
"string",
"null"
]
},
"headers_helper_refresh_interval_ms": {
"format": "uint64",
"minimum": 1.0,
"type": [
"integer",
"null"
]
},
"log_agent_responses": {
"type": [
"boolean",
@@ -13510,6 +13510,20 @@
}
]
},
"headers_helper": {
"type": [
"string",
"null"
]
},
"headers_helper_refresh_interval_ms": {
"format": "uint64",
"minimum": 1.0,
"type": [
"integer",
"null"
]
},
"log_agent_responses": {
"type": [
"boolean",
@@ -1266,6 +1266,20 @@
}
]
},
"headers_helper": {
"type": [
"string",
"null"
]
},
"headers_helper_refresh_interval_ms": {
"format": "uint64",
"minimum": 1.0,
"type": [
"integer",
"null"
]
},
"log_agent_responses": {
"type": [
"boolean",
@@ -4,4 +4,4 @@
import type { OtelExporter } from "./OtelExporter";
import type { OtelToolResultLogConfig } from "./OtelToolResultLogConfig";
export type OtelRequirements = { tool_result: OtelToolResultLogConfig | null, log_sse_deltas: boolean | null, log_user_prompt: boolean | null, log_agent_responses: boolean | null, log_guardian_assessments: boolean | null, environment: string | null, exporter: OtelExporter | null, trace_exporter: OtelExporter | null, metrics_exporter: OtelExporter | null, span_attributes: { [key in string]?: string } | null, tracestate: { [key in string]?: { [key in string]?: string } } | null, };
export type OtelRequirements = { headers_helper: string | null, headers_helper_refresh_interval_ms: bigint | null, tool_result: OtelToolResultLogConfig | null, log_sse_deltas: boolean | null, log_user_prompt: boolean | null, log_agent_responses: boolean | null, log_guardian_assessments: boolean | null, environment: string | null, exporter: OtelExporter | null, trace_exporter: OtelExporter | null, metrics_exporter: OtelExporter | null, span_attributes: { [key in string]?: string } | null, tracestate: { [key in string]?: { [key in string]?: string } } | null, };
@@ -25,6 +25,7 @@ use serde::Serialize;
use serde_json::Value as JsonValue;
use std::collections::BTreeMap;
use std::collections::HashMap;
use std::num::NonZeroU64;
use std::path::PathBuf;
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
@@ -507,6 +508,8 @@ pub struct FeedbackRequirements {
#[serde(rename_all = "snake_case")]
#[ts(export_to = "v2/")]
pub struct OtelRequirements {
pub headers_helper: Option<String>,
pub headers_helper_refresh_interval_ms: Option<NonZeroU64>,
pub tool_result: Option<OtelToolResultLogConfig>,
pub log_sse_deltas: Option<bool>,
pub log_user_prompt: Option<bool>,
+22
View File
@@ -965,6 +965,28 @@ managed fields. Configuration writes that overlap managed settings are rejected.
Exporter header values are redacted in effective config, source layers, managed
requirements, and write-override metadata. Runtime exporters retain the original values.
A system `requirements.toml` file or MDM requirements payload can set
`otel.headers_helper` and its optional `otel.headers_helper_refresh_interval_ms`.
Put the helper and each OTLP HTTP exporter that should receive its headers in
the same requirements layer. If another layer replaces an exporter, that
exporter uses its own configured headers.
Set the managed helper to the absolute path of an executable, for example
`/opt/company/bin/otel-auth`. Install it in a directory controlled by the
administrator and grant Codex users permission to execute it. Codex launches
the executable directly with its parent as the working directory. A relative
path makes the managed requirements invalid. If the executable is missing or
cannot run, Codex warns and pauses exports that depend on its headers until a
refresh succeeds.
**Rollout.** Install the helper and upgrade targeted clients to a release that
supports both keys in managed requirements before enabling either key in policy.
Older clients can reject the requirements at startup even if they support the
helper in ordinary config. For a mixed fleet, target only upgraded devices.
**Rollback.** Remove both managed keys and confirm each device has received the
updated policy before downgrading its client or uninstalling the helper.
Managed span attributes and tracestate metadata are included in effective config
and requirements reads. Unmanaged metadata remains writable.
+2
View File
@@ -15,6 +15,8 @@ use std::collections::HashMap;
pub(crate) fn map_otel_requirements_to_api(otel: OtelRequirementsToml) -> OtelRequirements {
OtelRequirements {
headers_helper: otel.headers_helper,
headers_helper_refresh_interval_ms: otel.headers_helper_refresh_interval_ms,
tool_result: otel.tool_result.map(|value| OtelToolResultLogConfig {
max_bytes: value.max_bytes,
}),
@@ -57,6 +57,26 @@ impl JsonLogCapture {
}
}
pub(crate) async fn wait_for_stderr_line(&self, text: &str, timeout: Duration) -> Result<()> {
tokio::time::timeout(timeout, async {
loop {
let updated = self.updated.notified();
if self
.lines
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.iter()
.any(|line| line.contains(text))
{
break;
}
updated.await;
}
})
.await
.with_context(|| format!("timed out waiting for stderr containing {text:?}"))
}
pub(crate) fn events(&self) -> Result<Vec<Value>> {
let lines = self
.lines
@@ -251,6 +251,11 @@ impl TestAppServer {
})
}
/// Waits for a substring in the child's captured stderr, including plain-text warnings.
pub async fn wait_for_stderr_line(&self, text: &str, timeout: Duration) -> anyhow::Result<()> {
self.json_logs.wait_for_stderr_line(text, timeout).await
}
/// Waits up to `timeout` for a JSON stderr event whose structured `event.name` field matches.
pub async fn wait_for_json_log_event(
&self,
+126
View File
@@ -52,6 +52,7 @@ use tokio::time::timeout;
use wiremock::Mock;
use wiremock::MockServer;
use wiremock::ResponseTemplate;
use wiremock::matchers::header;
use wiremock::matchers::method;
use wiremock::matchers::path;
@@ -440,6 +441,131 @@ fn standalone_app_server_emits_json_info_events() -> Result<()> {
Ok(())
}
async fn metrics_collector_expecting_helper_headers() -> (MockServer, wiremock::MockGuard) {
let collector = MockServer::start().await;
let export = Mock::given(method("POST"))
.and(path("/v1/metrics"))
.and(header("x-collector-auth", "from-helper"))
.respond_with(ResponseTemplate::new(200))
.expect(1..)
.mount_as_scoped(&collector)
.await;
(collector, export)
}
fn metrics_helper_config(command: &str, collector: &MockServer) -> String {
let endpoint = collector.uri();
format!(
r#"[otel]
headers_helper = '{command}'
headers_helper_refresh_interval_ms = 100
[otel.metrics_exporter.otlp-http]
endpoint = "{endpoint}/v1/metrics"
protocol = "json"
headers = {{ "x-collector-auth" = "static" }}
"#
)
}
fn install_otel_test_helper(dir: &std::path::Path) -> Result<&'static str> {
#[cfg(unix)]
let name = {
codex_utils_cargo_bin::write_executable(
&dir.join("otel-auth"),
"#!/bin/sh\ncat headers.json\n",
)?;
"otel-auth"
};
#[cfg(windows)]
let name = {
std::fs::write(dir.join("otel-auth.cmd"), "@type headers.json\r\n")?;
"otel-auth.cmd"
};
std::fs::write(
dir.join("headers.json"),
r#"{"x-collector-auth":"from-helper"}"#,
)?;
Ok(name)
}
#[tokio::test]
async fn user_otel_helper_runs_from_codex_home_with_managed_environment() -> Result<()> {
let home = TempDir::new()?;
let name = install_otel_test_helper(home.path())?;
let (collector, export) = metrics_collector_expecting_helper_headers().await;
std::fs::write(
home.path().join("config.toml"),
metrics_helper_config(name, &collector),
)?;
std::fs::write(
home.path().join("requirements.toml"),
"[otel]\nenvironment = 'managed'",
)?;
let _server = TestAppServer::builder()
.with_codex_home(home.path())
.without_auto_env()
.with_env_overrides(&[("OTEL_METRIC_EXPORT_INTERVAL", Some("100"))])
.build_initialized_with_timeout(READ_TIMEOUT)
.await?;
timeout(READ_TIMEOUT, export.wait_until_satisfied()).await?;
Ok(())
}
#[tokio::test]
async fn managed_otel_helper_runs_from_its_install_directory() -> Result<()> {
let home = TempDir::new()?;
let install = tempfile::Builder::new()
.prefix("managed helpers ")
.tempdir()?;
let name = install_otel_test_helper(install.path())?;
let executable = install.path().join(name);
let decoy = home.path().join(name);
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
codex_utils_cargo_bin::write_executable(&decoy, "#!/bin/sh\ntouch decoy-ran\n")?;
std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o644))?;
}
#[cfg(windows)]
std::fs::write(&decoy, "@echo decoy>decoy-ran")?;
let (collector, export) = metrics_collector_expecting_helper_headers().await;
let command = executable.to_str().context("UTF-8 helper path")?;
std::fs::write(
home.path().join("requirements.toml"),
metrics_helper_config(command, &collector),
)?;
let mut server = TestAppServer::builder()
.with_codex_home(home.path())
.without_auto_env()
.with_env_overrides(&[("OTEL_METRIC_EXPORT_INTERVAL", Some("100"))])
.build_initialized_with_timeout(READ_TIMEOUT)
.await?;
#[cfg(unix)]
{
let error = std::io::Error::from_raw_os_error(libc::EACCES);
server
.wait_for_stderr_line(
&format!("managed OTel helper {command}: headers helper failed to start: {error}"),
READ_TIMEOUT,
)
.await?;
}
let request = server.send_config_requirements_read_request().await?;
let _: Value = timeout(READ_TIMEOUT, server.read_response(request)).await??;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o755))?;
}
timeout(READ_TIMEOUT, export.wait_until_satisfied()).await?;
assert!(!home.path().join("decoy-ran").exists());
assert!(!install.path().join("decoy-ran").exists());
for request in collector.received_requests().await.unwrap() {
assert_eq!(request.headers["x-collector-auth"], "from-helper");
}
Ok(())
}
#[tokio::test]
async fn sqlite_log_metrics_exports_do_not_create_log_cycles() -> Result<()> {
let quiet_period = codex_state::log_db::LogSinkQueueConfig::default().flush_interval
@@ -101,6 +101,31 @@ foo = "bar"
Ok(())
}
#[test_case::test_case("otel-auth"; "bare_name")]
#[test_case::test_case("./otel-auth"; "relative_path")]
fn relative_managed_otel_helper_fails_startup(command: &str) -> Result<()> {
let home = TempDir::new()?;
std::fs::write(
home.path().join("requirements.toml"),
format!("[otel]\nheaders_helper = '{command}'"),
)?;
let output = Command::new(codex_utils_cargo_bin::cargo_bin("codex-app-server")?)
.env("CODEX_HOME", home.path())
.env(
"CODEX_APP_SERVER_MANAGED_CONFIG_PATH",
home.path().join("managed_config.toml"),
)
.args(["--listen", "off"])
.output()?;
let stderr = String::from_utf8(output.stderr)?;
assert!(!output.status.success(), "{stderr}");
assert!(
stderr.contains("otel.headers_helper must be an absolute executable path"),
"{stderr}"
);
Ok(())
}
#[test]
fn managed_auth_requirements_fail_closed_for_standalone_app_server() -> Result<()> {
for (requirements, config) in [
@@ -711,10 +711,17 @@ async fn config_requirements_read_redacts_otel_exporter_headers(
.without_auto_env()
.build_initialized_with_timeout(DEFAULT_READ_TIMEOUT)
.await?;
let helper = if cfg!(windows) {
"C:/company/otel-headers.exe"
} else {
"/opt/company/otel-headers"
};
// Read policy without starting exporters or opening the example TLS files.
std::fs::write(
codex_home.path().join("requirements.toml"),
r#"[otel]
headers_helper = "$HELPER"
headers_helper_refresh_interval_ms = 60000
tool_result = { max_bytes = 1024 }
log_user_prompt = false
log_sse_deltas = false
@@ -726,6 +733,7 @@ trace_exporter = { otlp-grpc = { endpoint = "http://127.0.0.1:4317", headers = {
metrics_exporter = "$METRICS_EXPORTER"
span_attributes = { "service.name" = "managed-service" }
tracestate = { managed = { tenant = "enterprise" } }"#
.replace("$HELPER", helper)
.replace("$PROTOCOL", protocol)
.replace("$METRICS_EXPORTER", metrics_exporter),
)?;
@@ -735,6 +743,8 @@ tracestate = { managed = { tenant = "enterprise" } }"#
assert_eq!(
response["requirements"]["otel"],
json!({
"headers_helper": helper,
"headers_helper_refresh_interval_ms": 60000,
"tool_result": { "max_bytes": 1024 },
"log_user_prompt": false,
"log_sse_deltas": false,
+71 -2
View File
@@ -21,6 +21,7 @@ use std::collections::BTreeSet;
use std::collections::HashMap;
use std::convert::Infallible;
use std::fmt;
use std::num::NonZeroU64;
use std::path::PathBuf;
use std::str::FromStr;
use wildmatch::WildMatchPattern;
@@ -1253,6 +1254,11 @@ pub struct ConfigRequirementsToml {
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct OtelRequirementsToml {
pub headers_helper: Option<String>,
pub headers_helper_refresh_interval_ms: Option<NonZeroU64>,
// Computed during composition. A policy cannot grant a helper access to another layer's collector.
#[serde(skip)]
managed_helper_targets: OtelHeadersHelperTargets,
pub tool_result: Option<ToolResultLogConfig>,
pub log_sse_deltas: Option<bool>,
pub log_user_prompt: Option<bool>,
@@ -1266,9 +1272,49 @@ pub struct OtelRequirementsToml {
pub tracestate: Option<BTreeMap<String, BTreeMap<String, String>>>,
}
/// Signals whose collector may receive the configured helper's credentials.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct OtelHeadersHelperTargets {
pub logs: bool,
pub traces: bool,
pub metrics: bool,
}
impl OtelHeadersHelperTargets {
fn merge_layer(&mut self, layer: &OtelRequirementsToml) {
let has_helper = layer.headers_helper.is_some();
let update = |target: &mut bool, exporter: &Option<OtelExporterKind>| {
// Replacing either side of the binding revokes the previous grant.
// An empty HTTP endpoint falls back to the process environment in the OTLP SDK.
if has_helper || exporter.is_some() {
*target = has_helper
&& matches!(exporter, Some(OtelExporterKind::OtlpHttp { endpoint, .. }) if !endpoint.is_empty());
}
};
update(&mut self.logs, &layer.exporter);
update(&mut self.traces, &layer.trace_exporter);
update(&mut self.metrics, &layer.metrics_exporter);
}
}
impl OtelRequirementsToml {
/// A managed helper serves its own layer's exporters. A user helper serves unmanaged exporters.
pub fn headers_helper_targets(&self) -> OtelHeadersHelperTargets {
if self.headers_helper.is_some() {
self.managed_helper_targets
} else {
OtelHeadersHelperTargets {
logs: self.exporter.is_none(),
traces: self.trace_exporter.is_none(),
metrics: self.metrics_exporter.is_none(),
}
}
}
pub(crate) fn is_empty(&self) -> bool {
self.tool_result.is_none()
self.headers_helper.is_none()
&& self.headers_helper_refresh_interval_ms.is_none()
&& self.tool_result.is_none()
&& self.log_sse_deltas.is_none()
&& self.log_user_prompt.is_none()
&& self.log_agent_responses.is_none()
@@ -1951,7 +1997,7 @@ impl ConfigRequirementsToml {
return Some("model_providers");
}
let otel = self.otel.as_ref();
let managed_fields: [(bool, &[&str], &'static str); 18] = [
let managed_fields: [(bool, &[&str], &'static str); 20] = [
(
self.model_provider.is_some(),
&["model_provider"],
@@ -1997,6 +2043,16 @@ impl ConfigRequirementsToml {
&["otel", "tool_result"],
"otel.tool_result",
),
(
otel.is_some_and(|otel| otel.headers_helper.is_some()),
&["otel", "headers_helper"],
"otel.headers_helper",
),
(
otel.is_some_and(|otel| otel.headers_helper_refresh_interval_ms.is_some()),
&["otel", "headers_helper_refresh_interval_ms"],
"otel.headers_helper_refresh_interval_ms",
),
(
otel.is_some_and(|otel| otel.log_user_prompt.is_some()),
&["otel", "log_user_prompt"],
@@ -2073,6 +2129,9 @@ macro_rules! otel_merge_functions {
);
contributed = true;
}
if let Some(merged) = requirements {
merged.managed_helper_targets.merge_layer(higher_priority);
}
contributed
}
@@ -2097,6 +2156,8 @@ macro_rules! otel_merge_functions {
}
otel_merge_functions!(
headers_helper,
headers_helper_refresh_interval_ms,
tool_result,
log_sse_deltas,
log_user_prompt,
@@ -2753,6 +2814,8 @@ mod tests {
#[test_case::test_case(&["otel"], Some("otel.tool_result"); "otel_parent")]
#[test_case::test_case(&["otel", "tool_result"], Some("otel.tool_result"); "tool_result")]
#[test_case::test_case(&["otel", "tool_result", "max_bytes"], Some("otel.tool_result"); "tool_result_max_bytes")]
#[test_case::test_case(&["otel", "headers_helper"], Some("otel.headers_helper"); "headers_helper")]
#[test_case::test_case(&["otel", "headers_helper_refresh_interval_ms"], Some("otel.headers_helper_refresh_interval_ms"); "headers_helper_refresh_interval_ms")]
#[test_case::test_case(&["otel", "log_user_prompt"], Some("otel.log_user_prompt"); "log_user_prompt")]
#[test_case::test_case(&["otel", "log_sse_deltas"], Some("otel.log_sse_deltas"); "log_sse_deltas")]
#[test_case::test_case(&["otel", "environment"], Some("otel.environment"); "environment")]
@@ -2776,6 +2839,8 @@ mod tests {
r#"
[otel]
tool_result = { max_bytes = 1024 }
headers_helper = "/opt/company/otel-headers"
headers_helper_refresh_interval_ms = 60000
log_user_prompt = false
environment = "managed"
log_sse_deltas = false
@@ -2790,6 +2855,8 @@ tracestate = { managed = { tenant = "enterprise" }, empty = {} }
r#"
[otel]
tool_result = { max_bytes = 4096 }
headers_helper = "user-headers"
headers_helper_refresh_interval_ms = 90000
log_user_prompt = true
environment = "user"
log_sse_deltas = true
@@ -2808,6 +2875,8 @@ tracestate = { managed = { tenant = "user", region = "us" }, other = { keep = "y
r#"
[otel]
tool_result = { max_bytes = 1024 }
headers_helper = "/opt/company/otel-headers"
headers_helper_refresh_interval_ms = 60000
log_user_prompt = false
environment = "managed"
log_sse_deltas = false
+1
View File
@@ -139,6 +139,7 @@ pub use config_requirements::NetworkRequirementsToml;
pub use config_requirements::NetworkUnixSocketPermissionToml;
pub use config_requirements::NetworkUnixSocketPermissionsToml;
pub use config_requirements::NewThreadModelDefaultsToml;
pub use config_requirements::OtelHeadersHelperTargets;
pub use config_requirements::OtelRequirementsToml;
pub use config_requirements::RemoteSandboxConfigToml;
pub use config_requirements::RequirementSource;
@@ -112,6 +112,44 @@ impl ComposableRequirementsLayer {
});
}
if let Some(otel) = regular_toml.get("otel")
&& (otel.get("headers_helper").is_some()
|| otel.get("headers_helper_refresh_interval_ms").is_some())
&& !matches!(
source,
RequirementSource::SystemRequirementsToml { .. }
| RequirementSource::MdmManagedPreferences { .. }
)
{
return Err(RequirementsCompositionError::Parse {
layer_source: source,
message:
"OTel headers helpers may only be configured in local managed requirements"
.into(),
});
}
if let Some(command) = regular_toml
.get("otel")
.and_then(|otel| otel.get("headers_helper"))
.and_then(TomlValue::as_str)
{
let convention = path_context.as_ref().map_or_else(
crate::path_context::convention,
ConfigPathContext::convention,
);
if codex_utils_path_uri::PathUri::resolve_config_path_uri(
command, convention, /*base*/ None, /*user_home_dir*/ None,
)
.is_err()
{
return Err(RequirementsCompositionError::Parse {
layer_source: source,
message: "otel.headers_helper must be an absolute executable path in managed requirements".into(),
});
}
}
// These fields can only be set locally; ignore them before validating cloud policy.
strip_cloud_auth_requirements(&source, &mut regular_toml);
@@ -6,6 +6,7 @@ use super::compose_requirements_for_hostname_and_hook_directory;
use super::compose_requirements_with_hostname_resolver;
use crate::ConfigRequirementsToml;
use crate::ConfigRequirementsWithSources;
use crate::OtelHeadersHelperTargets;
use crate::RequirementSource;
use crate::Sourced;
use codex_protocol::protocol::AskForApproval;
@@ -452,6 +453,89 @@ tracestate = { shared = { tenant = "replacement", region = "us" }, lower = { ten
}
}
#[test]
fn otel_managed_headers_follow_each_exporters_owning_layer() -> anyhow::Result<()> {
let dir = tempdir()?;
let system_command = if cfg!(windows) {
"C:/company/headers.exe"
} else {
"/opt/company/headers"
};
let mdm_command = if cfg!(windows) {
"C:/company/mdm-headers.exe"
} else {
"/opt/company/mdm-headers"
};
let system = RequirementsLayerEntry::from_toml(
RequirementSource::SystemRequirementsToml {
file: AbsolutePathBuf::try_from(dir.path().join("requirements.toml"))?,
},
r#"[otel]
headers_helper = "$HELPER"
exporter = { otlp-http = { endpoint = "https://collector.example/logs", protocol = "binary" } }
trace_exporter = { otlp-http = { endpoint = "https://collector.example/traces", protocol = "binary" } }
metrics_exporter = { otlp-http = { endpoint = "https://collector.example/metrics", protocol = "binary" } }
"#.replace("$HELPER", system_command),
);
let cloud = layer(
"cloud",
"Cloud",
r#"[otel]
trace_exporter = { otlp-http = { endpoint = "https://other.example/traces", protocol = "binary" } }
"#,
);
let mdm = RequirementsLayerEntry::from_toml(
RequirementSource::MdmManagedPreferences {
domain: "com.openai.codex".into(),
key: "requirements".into(),
},
r#"[otel]
headers_helper = "$HELPER"
metrics_exporter = { otlp-http = { endpoint = "https://mdm.example/metrics", protocol = "binary" } }
exporter = { otlp-http = { endpoint = "", protocol = "binary" } }
"#
.replace("$HELPER", mdm_command),
);
for (layers, command, logs, traces, metrics) in [
(vec![system.clone()], system_command, true, true, true),
(
vec![system.clone(), cloud.clone()],
system_command,
true,
false,
true,
),
(vec![system, cloud, mdm], mdm_command, false, false, true),
] {
let otel = compose(layers)?.unwrap().otel.unwrap();
assert_eq!(otel.headers_helper.as_deref(), Some(command));
assert_eq!(
otel.headers_helper_targets(),
OtelHeadersHelperTargets {
logs,
traces,
metrics
}
);
}
Ok(())
}
#[test]
fn otel_cloud_requirements_cannot_install_or_reschedule_a_helper() {
for setting in [
"headers_helper = 'headers'",
"headers_helper_refresh_interval_ms = 1",
] {
let err =
compose(vec![layer("cloud", "Cloud", &format!("[otel]\n{setting}"))]).unwrap_err();
assert!(
matches!(err, RequirementsCompositionError::Parse { message, .. } if message.contains("local managed requirements"))
);
}
}
#[test]
fn provider_auth_missing_command_is_rejected_after_composition() {
let err = compose(vec![
+7 -4
View File
@@ -87,20 +87,23 @@ pub fn build_provider(
let service_name = service_name_override.unwrap_or(originator.value.as_str());
let runtime_metrics = config.features.enabled(Feature::RuntimeMetrics);
let managed = config
let managed_otel = config
.config_layer_stack
.requirements_toml()
.otel
.as_deref();
let helper_targets =
managed_otel.map(codex_config::OtelRequirementsToml::headers_helper_targets);
let headers_helper = config
.otel
.headers_helper
.as_ref()
.map(|command| OtelHeadersHelper {
command: command.clone(),
apply_to_logs: managed.is_none_or(|otel| otel.exporter.is_none()),
apply_to_traces: managed.is_none_or(|otel| otel.trace_exporter.is_none()),
apply_to_metrics: managed.is_none_or(|otel| otel.metrics_exporter.is_none()),
managed: managed_otel.is_some_and(|otel| otel.headers_helper.is_some()),
apply_to_logs: helper_targets.is_none_or(|targets| targets.logs),
apply_to_traces: helper_targets.is_none_or(|targets| targets.traces),
apply_to_metrics: helper_targets.is_none_or(|targets| targets.metrics),
refresh_interval: Duration::from_millis(
config
.otel
+4 -2
View File
@@ -67,13 +67,15 @@ pub struct OtelSettings {
}
/// A shared command for explicit OTLP HTTP exporters; never used by built-in analytics.
/// The command runs from `OtelSettings::codex_home` and prints a JSON object of strings.
/// The command prints a JSON object of strings.
/// Its headers override static headers. A failed run suspends exports until recovery.
#[derive(Clone)]
pub struct OtelHeadersHelper {
pub command: String,
/// A managed executable runs directly from its parent directory. User commands run from Codex home.
pub managed: bool,
pub refresh_interval: Duration,
/// Exporters set by admin requirements ignore the headers helper.
/// Signals whose exporter is authorized to receive this helper's headers.
pub apply_to_logs: bool,
pub apply_to_traces: bool,
pub apply_to_metrics: bool,
+17 -1
View File
@@ -106,7 +106,7 @@ async fn refresh_headers(
// permit as an SDK that cannot enforce individual destinations.
let result = match policy.acquire_for_unsupported_sdk() {
Ok(permit) => permit
.run(run_helper(&config.command, cwd))
.run(run_configured_helper(config, cwd))
.await
.unwrap_or_else(|error| Err(error.to_string())),
Err(error) => Err(error.to_string()),
@@ -132,6 +132,22 @@ async fn refresh_headers(
}
}
async fn run_configured_helper(config: &OtelHeadersHelper, cwd: &Path) -> HeaderResult {
if !config.managed {
return run_helper(&config.command, cwd).await;
}
let executable = Path::new(&config.command);
let parent = executable
.parent()
.filter(|_| executable.is_absolute())
.ok_or("managed OTel helper requires an absolute executable path")?;
let mut process = codex_utils_process::background_command(executable);
process.current_dir(parent);
codex_http_headers_helper::run(process)
.await
.map_err(|error| format!("managed OTel helper {}: {error}", executable.display()))
}
async fn run_helper(command: &str, cwd: &Path) -> HeaderResult {
#[cfg(windows)]
let mut process = codex_http_headers_helper::shell_command(command);
+26
View File
@@ -31,6 +31,7 @@ async fn restricted_policy_skips_command_until_a_refresh_is_permitted() {
);
let helper = HeadersHelper::start(
&OtelHeadersHelper {
managed: false,
command: format!("echo invocation >> calls && {}", read_command()),
refresh_interval: Duration::from_millis(20),
apply_to_logs: true,
@@ -66,6 +67,7 @@ async fn concurrent_exports_share_one_helper_execution() {
.unwrap();
let helper = HeadersHelper::start(
&OtelHeadersHelper {
managed: false,
command: format!("echo invocation >> calls && {}", read_command()),
refresh_interval: Duration::from_secs(3600),
apply_to_logs: true,
@@ -101,6 +103,7 @@ async fn periodic_refresh_replaces_credentials_and_recovers_after_failure() {
std::fs::write(&path, r#"{"Authorization":"first","X-Old":"old"}"#).unwrap();
let helper = HeadersHelper::start(
&OtelHeadersHelper {
managed: false,
command: read_command().to_string(),
refresh_interval: Duration::from_millis(20),
apply_to_logs: true,
@@ -138,6 +141,27 @@ async fn periodic_refresh_replaces_credentials_and_recovers_after_failure() {
helper.shutdown();
}
#[tokio::test]
async fn missing_managed_executable_reports_path_and_os_error() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("missing-helper.exe");
let helper = OtelHeadersHelper {
command: path.to_str().unwrap().to_owned(),
managed: true,
refresh_interval: Duration::from_secs(60),
apply_to_logs: true,
apply_to_traces: true,
apply_to_metrics: true,
};
let error = run_configured_helper(&helper, dir.path())
.await
.unwrap_err();
assert!(error.contains(path.to_str().unwrap()), "{error}");
let os_error = std::fs::metadata(&path).unwrap_err();
assert_eq!(os_error.kind(), std::io::ErrorKind::NotFound);
assert!(error.contains(&os_error.to_string()), "{error}");
}
#[tokio::test]
async fn helper_failure_is_an_export_error_and_output_is_bounded() {
let dir = tempfile::tempdir().unwrap();
@@ -157,6 +181,7 @@ async fn failed_helper_prevents_http_export_even_with_static_credentials() {
listener.set_nonblocking(true).unwrap();
let helper = HeadersHelper::start(
&OtelHeadersHelper {
managed: false,
command: "exit 1".to_string(),
refresh_interval: Duration::from_secs(3600),
apply_to_logs: true,
@@ -193,6 +218,7 @@ async fn failed_helper_prevents_http_export_even_with_static_credentials() {
async fn grpc_and_builtin_metrics_do_not_start_the_helper() {
use crate::config::OtelExporter;
let helper = OtelHeadersHelper {
managed: false,
command: String::new(),
refresh_interval: Duration::ZERO,
apply_to_logs: true,
@@ -64,6 +64,7 @@ fn check_all_signals(protocol: OtelHttpProtocol, managed_logs: bool) {
"cat headers.json"
};
let helper = OtelHeadersHelper {
managed: false,
command: format!("echo invocation >> calls && {command}"),
refresh_interval: Duration::from_secs(3600),
apply_to_logs: !managed_logs,
@@ -9874,6 +9874,8 @@ class OtelRequirements(BaseModel):
)
environment: str | None = None
exporter: OtelExporter | None = None
headers_helper: str | None = None
headers_helper_refresh_interval_ms: Annotated[int | None, Field(ge=1)] = None
log_agent_responses: bool | None = None
log_guardian_assessments: bool | None = None
log_sse_deltas: bool | None = None