[codex-analytics] Analytics Capture to File in Debug Builds (#27093)

## This PR

The original [combined remote plugin analytics PR
#26281](https://github.com/openai/codex/pull/26281) mixed reusable
analytics test infrastructure, two manual smoke workflows, a metadata
refactor, and the final identity behavior. This PR isolates the generic
capture mechanism so it can be reviewed and landed before any
plugin-specific behavior.

- Add a debug-only analytics destination that writes final request
payloads as JSONL.
- Suppress HTTP delivery whenever capture mode is selected, including
after capture write failures.
- Keep release behavior unchanged even when the capture environment
variable is present.
- Keep the mechanism generic; this PR contains no plugin-specific
behavior.

Set `CODEX_ANALYTICS_EVENTS_CAPTURE_FILE=/path/events.jsonl` when
running a debug Codex binary to inspect the exact batched payload that
would otherwise be sent to the analytics endpoint.

## Testing

- `just test -p codex-analytics` (76 passed)
- `just test --release -p codex-analytics` (73 passed)
- CI is green across the required platform matrix.

## Split Overview

```text
main
├── #27093  Debug analytics capture                 ← you are here
│   └── #27099  Non-mutating plugin smoke
│       └── #27100  Remote install/uninstall smoke
└── #27102  Plugin telemetry metadata refactor

After #27093, #27099, #27100, and #27102 merge:
└── Final PR: add remote_plugin_id to plugin analytics
```

Review order and dependencies:

1. [#27093 Add debug-only analytics event
capture](https://github.com/openai/codex/pull/27093) **(this PR, based
on `main`)**
2. [#27099 Add a plugin analytics smoke
workflow](https://github.com/openai/codex/pull/27099) (stacked on
#27093)
3. [#27100 Add a remote plugin analytics mutation smoke
workflow](https://github.com/openai/codex/pull/27100) (stacked on
#27099)
4. [#27102 Centralize plugin telemetry metadata
construction](https://github.com/openai/codex/pull/27102) (independent,
based on `main`)
5. Final remote-ID behavior PR (created after PRs 1-4 merge)

The original [#26281](https://github.com/openai/codex/pull/26281)
remains open as the green aggregate reference until the final PR is
published.
This commit is contained in:
jameswt-oai authored and GitHub committed 2026-06-15 16:32:38 -07:00
1 parent 1d8ff89aa3
commit e512e884ed
4 files changed
+286 -8

No files matched your search

+95 -8
View File
@@ -38,6 +38,7 @@ use codex_login::default_client::create_client;
use codex_plugin::PluginTelemetryMetadata;
use codex_protocol::request_permissions::RequestPermissionsResponse;
use std::collections::HashSet;
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::Mutex;
use std::time::Duration;
@@ -59,15 +60,70 @@ pub struct AnalyticsEventsClient {
queue: Option<AnalyticsEventsQueue>,
}
#[derive(Clone, Debug, Eq, PartialEq)]
enum AnalyticsEventsDestination {
Http {
url: String,
},
#[cfg(debug_assertions)]
CaptureFile {
path: PathBuf,
},
}
impl AnalyticsEventsDestination {
fn from_base_url(base_url: String) -> Self {
let capture_file = analytics_capture_file_from_env();
Self::from_base_url_and_capture_file(base_url, capture_file)
}
fn from_base_url_and_capture_file(base_url: String, capture_file: Option<PathBuf>) -> Self {
#[cfg(debug_assertions)]
if let Some(path) = capture_file {
if let Err(err) = crate::analytics_capture::initialize(&path) {
tracing::error!(
path = %path.display(),
"failed to initialize analytics event capture; network delivery remains disabled: {err}"
);
}
tracing::warn!(
path = %path.display(),
"analytics event capture enabled; network delivery is disabled"
);
return Self::CaptureFile { path };
}
#[cfg(not(debug_assertions))]
let _ = capture_file;
let base_url = base_url.trim_end_matches('/');
Self::Http {
url: format!("{base_url}/codex/analytics-events/events"),
}
}
}
fn analytics_capture_file_from_env() -> Option<PathBuf> {
#[cfg(debug_assertions)]
{
std::env::var_os(crate::analytics_capture::ANALYTICS_EVENTS_CAPTURE_FILE_ENV_VAR)
.filter(|value| !value.is_empty())
.map(PathBuf::from)
}
#[cfg(not(debug_assertions))]
None
}
impl AnalyticsEventsQueue {
pub(crate) fn new(auth_manager: Arc<AuthManager>, base_url: String) -> Self {
fn new(auth_manager: Arc<AuthManager>, destination: AnalyticsEventsDestination) -> Self {
let (sender, mut receiver) = mpsc::channel(ANALYTICS_EVENTS_QUEUE_SIZE);
tokio::spawn(async move {
let mut reducer = AnalyticsReducer::default();
while let Some(input) = receiver.recv().await {
let mut events = Vec::new();
reducer.ingest(input, &mut events).await;
send_track_events(&auth_manager, &base_url, events).await;
send_track_events(&auth_manager, &destination, events).await;
}
});
Self {
@@ -124,9 +180,10 @@ impl AnalyticsEventsClient {
base_url: String,
analytics_enabled: Option<bool>,
) -> Self {
let destination = AnalyticsEventsDestination::from_base_url(base_url);
Self {
queue: (analytics_enabled != Some(false))
.then(|| AnalyticsEventsQueue::new(Arc::clone(&auth_manager), base_url)),
.then(|| AnalyticsEventsQueue::new(Arc::clone(&auth_manager), destination)),
}
}
@@ -410,7 +467,7 @@ impl AnalyticsEventsClient {
async fn send_track_events(
auth_manager: &AuthManager,
base_url: &str,
destination: &AnalyticsEventsDestination,
events: Vec<TrackEventRequest>,
) {
if events.is_empty() {
@@ -424,10 +481,8 @@ async fn send_track_events(
return;
}
let base_url = base_url.trim_end_matches('/');
let url = format!("{base_url}/codex/analytics-events/events");
for events in track_event_request_batches(events) {
send_track_events_request(&auth, &url, events).await;
send_track_events_request(&auth, destination, events).await;
}
}
@@ -454,13 +509,27 @@ fn track_event_request_batches(events: Vec<TrackEventRequest>) -> Vec<Vec<TrackE
batches
}
async fn send_track_events_request(auth: &CodexAuth, url: &str, events: Vec<TrackEventRequest>) {
async fn send_track_events_request(
auth: &CodexAuth,
destination: &AnalyticsEventsDestination,
events: Vec<TrackEventRequest>,
) {
if events.is_empty() {
return;
}
let payload = TrackEventsRequest { events };
#[cfg(debug_assertions)]
if capture_track_events_request(destination, &payload) {
return;
}
let url = match destination {
AnalyticsEventsDestination::Http { url } => url,
#[cfg(debug_assertions)]
AnalyticsEventsDestination::CaptureFile { .. } => return,
};
let response = create_client()
.post(url)
.timeout(ANALYTICS_EVENTS_TIMEOUT)
@@ -483,6 +552,24 @@ async fn send_track_events_request(auth: &CodexAuth, url: &str, events: Vec<Trac
}
}
#[cfg(debug_assertions)]
fn capture_track_events_request(
destination: &AnalyticsEventsDestination,
payload: &TrackEventsRequest,
) -> bool {
let AnalyticsEventsDestination::CaptureFile { path } = destination else {
return false;
};
if let Err(err) = crate::analytics_capture::append_payload(path, payload) {
tracing::error!(
path = %path.display(),
"failed to capture analytics events; network delivery remains disabled: {err}"
);
}
true
}
#[cfg(test)]
#[path = "client_tests.rs"]
mod tests;