Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Use explicit histogram buckets for tool and skill context metrics (#48819)

Matthew Zeng456212ca2155
diff --git a/codex-rs/core/src/context/world_state/tools.rs b/codex-rs/core/src/context/world_state/tools.rs
index 7d206b9a03..b3f3ff3665 100644
--- a/codex-rs/core/src/context/world_state/tools.rs
+++ b/codex-rs/core/src/context/world_state/tools.rs
@@ -9,8 +9,8 @@ use super::WorldStateSection;
use crate::context::ContextualUserFragment;
use codex_extension_api::ExtensionMetrics;
use codex_extension_api::RenderedWorldStateFragment;
-use codex_otel::CONTEXT_FRAGMENT_BYTES_BUCKETS;
use codex_otel::THREAD_TOOLS_FRAGMENT_BYTES_METRIC;
+use codex_otel::THREAD_TOOLS_METRIC_BUCKETS;
use codex_otel::THREAD_TOOLS_NAMESPACES_TOTAL_METRIC;
use codex_protocol::models::ContentItemKind;
use codex_protocol::protocol::TOOLS_CLOSE_TAG;
@@ -231,15 +231,16 @@ fn record_fragment_metrics(
};
for (stage, size) in [("before", &rendered.before), ("after", &rendered.after)] {
let tags = [("stage", stage), ("kind", kind)];
- metrics.histogram(
+ metrics.histogram_with_boundaries(
THREAD_TOOLS_NAMESPACES_TOTAL_METRIC,
i64::try_from(size.namespaces).unwrap_or(i64::MAX),
+ THREAD_TOOLS_METRIC_BUCKETS.as_slice(),
&tags,
);
metrics.histogram_with_boundaries(
THREAD_TOOLS_FRAGMENT_BYTES_METRIC,
i64::try_from(size.bytes).unwrap_or(i64::MAX),
- CONTEXT_FRAGMENT_BYTES_BUCKETS,
+ THREAD_TOOLS_METRIC_BUCKETS.as_slice(),
&tags,
);
}
diff --git a/codex-rs/core/src/context/world_state/tools_tests.rs b/codex-rs/core/src/context/world_state/tools_tests.rs
index 2321daa0dc..4d4d49c217 100644
--- a/codex-rs/core/src/context/world_state/tools_tests.rs
+++ b/codex-rs/core/src/context/world_state/tools_tests.rs
@@ -6,6 +6,7 @@ use crate::context::world_state::WorldStateSection;
use crate::context::world_state::test_support::render_section_cases;
use codex_extension_api::ExtensionMetrics;
use codex_otel::THREAD_TOOLS_FRAGMENT_BYTES_METRIC;
+use codex_otel::THREAD_TOOLS_METRIC_BUCKETS;
use codex_otel::THREAD_TOOLS_NAMESPACES_TOTAL_METRIC;
use pretty_assertions::assert_eq;
use std::collections::BTreeMap;
@@ -398,7 +399,13 @@ fn reserves_the_empty_state_notice_when_all_namespaces_are_removed() {
#[derive(Default)]
struct RecordingMetrics {
- samples: Mutex<BTreeMap<(String, String, String), i64>>,
+ samples: Mutex<BTreeMap<(String, String, String), RecordedHistogram>>,
+}
+
+#[derive(Debug, PartialEq)]
+struct RecordedHistogram {
+ value: i64,
+ boundaries: Vec<f64>,
}
impl ExtensionMetrics for RecordingMetrics {
@@ -410,25 +417,28 @@ impl ExtensionMetrics for RecordingMetrics {
&self,
name: &str,
value: i64,
- _boundaries: &[f64],
+ boundaries: &[f64],
tags: &[(&str, &str)],
) {
- self.histogram(name, value, tags);
- }
-
- fn histogram(&self, name: &str, value: i64, tags: &[(&str, &str)]) {
let [("stage", stage), ("kind", kind)] = tags else {
panic!("unexpected tags: {tags:?}")
};
self.samples.lock().expect("metric samples lock").insert(
(name.to_string(), (*stage).to_string(), (*kind).to_string()),
- value,
+ RecordedHistogram {
+ value,
+ boundaries: boundaries.to_vec(),
+ },
);
}
+
+ fn histogram(&self, name: &str, _value: i64, _tags: &[(&str, &str)]) {
+ panic!("expected explicit boundaries for {name}");
+ }
}
impl RecordingMetrics {
- fn take(&self) -> BTreeMap<(String, String, String), i64> {
+ fn take(&self) -> BTreeMap<(String, String, String), RecordedHistogram> {
std::mem::take(&mut *self.samples.lock().expect("metric samples lock"))
}
}
@@ -437,7 +447,7 @@ fn expected_metrics(
kind: &str,
before: (usize, &str),
after: (usize, &str),
-) -> BTreeMap<(String, String, String), i64> {
+) -> BTreeMap<(String, String, String), RecordedHistogram> {
[("before", before), ("after", after)]
.into_iter()
.flat_map(|(stage, (count, text))| {
@@ -448,7 +458,10 @@ fn expected_metrics(
.map(|(name, value)| {
(
(name.to_string(), stage.to_string(), kind.to_string()),
- value as i64,
+ RecordedHistogram {
+ value: value as i64,
+ boundaries: THREAD_TOOLS_METRIC_BUCKETS.to_vec(),
+ },
)
})
})
diff --git a/codex-rs/ext/skills/src/render_observability.rs b/codex-rs/ext/skills/src/render_observability.rs
index f5e1d2eeb0..0d3a14f43b 100644
--- a/codex-rs/ext/skills/src/render_observability.rs
+++ b/codex-rs/ext/skills/src/render_observability.rs
@@ -1,7 +1,10 @@
use codex_extension_api::ExtensionMetrics;
+use codex_otel::THREAD_SKILLS_COUNT_METRIC_BUCKETS;
+use codex_otel::THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_BUCKETS;
use codex_otel::THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_METRIC;
use codex_otel::THREAD_SKILLS_ENABLED_TOTAL_METRIC;
use codex_otel::THREAD_SKILLS_KEPT_TOTAL_METRIC;
+use codex_otel::THREAD_SKILLS_TRUNCATED_BUCKETS;
use codex_otel::THREAD_SKILLS_TRUNCATED_METRIC;
use crate::render::SkillMetadataBudget;
@@ -78,23 +81,27 @@ pub(crate) fn record_catalog_metrics(
(
THREAD_SKILLS_ENABLED_TOTAL_METRIC,
i64::try_from(total_count).unwrap_or(i64::MAX),
+ THREAD_SKILLS_COUNT_METRIC_BUCKETS.as_slice(),
),
(
THREAD_SKILLS_KEPT_TOTAL_METRIC,
i64::try_from(included_count).unwrap_or(i64::MAX),
+ THREAD_SKILLS_COUNT_METRIC_BUCKETS.as_slice(),
),
(
THREAD_SKILLS_TRUNCATED_METRIC,
if omitted_count > 0 { 1 } else { 0 },
+ THREAD_SKILLS_TRUNCATED_BUCKETS,
),
(
THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_METRIC,
i64::try_from(truncated_description_chars).unwrap_or(i64::MAX),
+ THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_BUCKETS.as_slice(),
),
];
let tags = [("catalog_surface", catalog_surface.as_str())];
- for (name, value) in samples {
- extension_metrics.histogram(name, value, &tags);
+ for (name, value, boundaries) in samples {
+ extension_metrics.histogram_with_boundaries(name, value, boundaries, &tags);
}
}
diff --git a/codex-rs/ext/skills/src/render_observability_tests.rs b/codex-rs/ext/skills/src/render_observability_tests.rs
index f18ee7d08d..b1f4f47e3e 100644
--- a/codex-rs/ext/skills/src/render_observability_tests.rs
+++ b/codex-rs/ext/skills/src/render_observability_tests.rs
@@ -5,10 +5,11 @@ use pretty_assertions::assert_eq;
use super::*;
-#[derive(Debug, Eq, PartialEq)]
+#[derive(Debug, PartialEq)]
struct RecordedHistogram {
name: String,
value: i64,
+ boundaries: Vec<f64>,
tags: Vec<(String, String)>,
}
@@ -22,29 +23,30 @@ impl ExtensionMetrics for RecordingMetrics {
&self,
name: &str,
value: i64,
- _boundaries: &[f64],
+ boundaries: &[f64],
tags: &[(&str, &str)],
) {
- self.histogram(name, value, tags);
- }
-
- fn counter(&self, name: &str, _inc: i64, _tags: &[(&str, &str)]) {
- panic!("unexpected counter: {name}");
- }
-
- fn histogram(&self, name: &str, value: i64, tags: &[(&str, &str)]) {
self.samples
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push(RecordedHistogram {
name: name.to_string(),
value,
+ boundaries: boundaries.to_vec(),
tags: tags
.iter()
.map(|(key, value)| ((*key).to_string(), (*value).to_string()))
.collect(),
});
}
+
+ fn counter(&self, name: &str, _inc: i64, _tags: &[(&str, &str)]) {
+ panic!("unexpected counter: {name}");
+ }
+
+ fn histogram(&self, name: &str, _value: i64, _tags: &[(&str, &str)]) {
+ panic!("unexpected histogram without context boundaries: {name}");
+ }
}
#[test]
@@ -74,21 +76,25 @@ fn records_core_equivalent_catalog_render_metrics_with_surface() {
RecordedHistogram {
name: THREAD_SKILLS_ENABLED_TOTAL_METRIC.to_string(),
value: 5,
+ boundaries: THREAD_SKILLS_COUNT_METRIC_BUCKETS.to_vec(),
tags: vec![("catalog_surface".to_string(), "turn_input".to_string())],
},
RecordedHistogram {
name: THREAD_SKILLS_KEPT_TOTAL_METRIC.to_string(),
value: 3,
+ boundaries: THREAD_SKILLS_COUNT_METRIC_BUCKETS.to_vec(),
tags: vec![("catalog_surface".to_string(), "turn_input".to_string())],
},
RecordedHistogram {
name: THREAD_SKILLS_TRUNCATED_METRIC.to_string(),
value: 1,
+ boundaries: THREAD_SKILLS_TRUNCATED_BUCKETS.to_vec(),
tags: vec![("catalog_surface".to_string(), "turn_input".to_string())],
},
RecordedHistogram {
name: THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_METRIC.to_string(),
value: 700,
+ boundaries: THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_BUCKETS.to_vec(),
tags: vec![("catalog_surface".to_string(), "turn_input".to_string())],
},
]
diff --git a/codex-rs/otel/src/metrics/names.rs b/codex-rs/otel/src/metrics/names.rs
index fcc15025dd..e93d19ed85 100644
--- a/codex-rs/otel/src/metrics/names.rs
+++ b/codex-rs/otel/src/metrics/names.rs
@@ -1,3 +1,5 @@
+use std::sync::LazyLock;
+
pub const TOOL_CALL_COUNT_METRIC: &str = "codex.tool.call";
pub const TOOL_CALL_DURATION_METRIC: &str = "codex.tool.call.duration_ms";
pub const TOOL_CALL_UNIFIED_EXEC_METRIC: &str = "codex.tool.unified_exec";
@@ -75,6 +77,25 @@ pub const THREAD_SKILLS_TRUNCATED_METRIC: &str = "codex.thread.skills.truncated"
pub const THREAD_TOOLS_NAMESPACES_TOTAL_METRIC: &str = "codex.thread.tools.namespaces_total";
pub const THREAD_TOOLS_FRAGMENT_BYTES_METRIC: &str = "codex.thread.tools.fragment_bytes";
-/// Byte buckets for context-budget planning, with larger fragments in the overflow bucket.
-pub const CONTEXT_FRAGMENT_BYTES_BUCKETS: &[f64] =
- &[256., 512., 1_024., 2_048., 4_096., 8_192., 16_384.];
+/// Logarithmic boundaries up to 32,768 for tools bytes and namespace counts.
+pub static THREAD_TOOLS_METRIC_BUCKETS: LazyLock<[f64; 511]> =
+ LazyLock::new(|| context_log_buckets(/*max_exponent*/ 15.0));
+
+pub static THREAD_SKILLS_COUNT_METRIC_BUCKETS: LazyLock<[f64; 513]> =
+ LazyLock::new(|| std::array::from_fn(|index| index as f64));
+
+/// Logarithmic boundaries up to 131,072 removed description characters.
+pub static THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_BUCKETS: LazyLock<[f64; 511]> =
+ LazyLock::new(|| context_log_buckets(/*max_exponent*/ 17.0));
+
+pub const THREAD_SKILLS_TRUNCATED_BUCKETS: &[f64] = &[0.0, 1.0];
+
+fn context_log_buckets(max_exponent: f64) -> [f64; 511] {
+ std::array::from_fn(|index| {
+ if index == 0 {
+ 0.0
+ } else {
+ 2.0_f64.powf(max_exponent * (index - 1) as f64 / 509.0)
+ }
+ })
+}
diff --git a/codex-rs/otel/tests/suite/send.rs b/codex-rs/otel/tests/suite/send.rs
index e4d956a5fb..e112ddcc03 100644
--- a/codex-rs/otel/tests/suite/send.rs
+++ b/codex-rs/otel/tests/suite/send.rs
@@ -4,6 +4,14 @@ use crate::harness::find_metric;
use crate::harness::histogram_data;
use crate::harness::latest_metrics;
use codex_otel::Result;
+use codex_otel::THREAD_SKILLS_COUNT_METRIC_BUCKETS;
+use codex_otel::THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_BUCKETS;
+use codex_otel::THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_METRIC;
+use codex_otel::THREAD_SKILLS_ENABLED_TOTAL_METRIC;
+use codex_otel::THREAD_SKILLS_TRUNCATED_BUCKETS;
+use codex_otel::THREAD_SKILLS_TRUNCATED_METRIC;
+use codex_otel::THREAD_TOOLS_FRAGMENT_BYTES_METRIC;
+use codex_otel::THREAD_TOOLS_METRIC_BUCKETS;
use pretty_assertions::assert_eq;
use std::collections::BTreeMap;
@@ -127,6 +135,62 @@ fn histogram_uses_explicit_bucket_boundaries() -> Result<()> {
Ok(())
}
+#[test]
+fn context_histograms_preserve_zero_and_family_ranges() -> Result<()> {
+ let (metrics, exporter) = build_metrics_with_defaults(&[])?;
+ let cases = [
+ (
+ THREAD_TOOLS_FRAGMENT_BYTES_METRIC,
+ THREAD_TOOLS_METRIC_BUCKETS.as_slice(),
+ 32_768_i64,
+ 512,
+ ),
+ (
+ THREAD_SKILLS_ENABLED_TOTAL_METRIC,
+ THREAD_SKILLS_COUNT_METRIC_BUCKETS.as_slice(),
+ 512,
+ 514,
+ ),
+ (
+ THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_METRIC,
+ THREAD_SKILLS_DESCRIPTION_TRUNCATED_CHARS_BUCKETS.as_slice(),
+ 131_072,
+ 512,
+ ),
+ (
+ THREAD_SKILLS_TRUNCATED_METRIC,
+ THREAD_SKILLS_TRUNCATED_BUCKETS,
+ 1,
+ 3,
+ ),
+ ];
+ for (name, boundaries, maximum, _) in cases {
+ for value in [0, 1, maximum, maximum + 1] {
+ metrics.histogram_with_boundaries(name, value, boundaries, &[])?;
+ }
+ }
+ metrics.shutdown()?;
+
+ let resource_metrics = latest_metrics(&exporter);
+ for (name, expected_bounds, maximum, bucket_count) in cases {
+ let (bounds, counts, sum, count) = histogram_data(&resource_metrics, name);
+ assert_eq!(bounds.as_slice(), expected_bounds);
+ assert_eq!(bounds.len(), bucket_count - 1);
+ assert_eq!(bounds[0], 0.0);
+ assert_eq!(bounds[1], 1.0);
+ assert_eq!(bounds[bucket_count - 2], maximum as f64);
+ assert!(bounds.windows(/*size*/ 2).all(|pair| pair[0] < pair[1]));
+ let mut expected_counts = vec![0; bucket_count];
+ for index in [0, 1, bucket_count - 2, bucket_count - 1] {
+ expected_counts[index] += 1;
+ }
+ assert_eq!(counts, expected_counts);
+ assert_eq!((sum, count), ((2 * maximum + 2) as f64, 4));
+ }
+
+ Ok(())
+}
+
// Ensures defaults merge per line and overrides take precedence.
#[test]
fn send_merges_default_tags_per_line() -> Result<()> {