Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(collector): tell Codex CLI from Desktop by originator (#1099)

Shukan Shah2138970cb9dc
diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.go
index c0b34757..37d973eb 100644
--- a/cli/beacon/internal/tokens/tokens.go
+++ b/cli/beacon/internal/tokens/tokens.go
@@ -191,10 +191,14 @@ type usageEvent struct {
contextLimit int64
cumulative bool
metricName string
- rawSource string
- sourceStart time.Time
- seriesField string
- seriesValue float64
+ // codexAppServer marks usage exported by Codex's app-server, which the CLI and the desktop app
+ // share. A legacy turn metric from it names no conversation, so its harness is the exporter's
+ // default rather than its surface.
+ codexAppServer bool
+ rawSource string
+ sourceStart time.Time
+ seriesField string
+ seriesValue float64
// collectionMethod is harness.collection_method, lowercased: whether this usage came from
// live capture or from a poll of the runtime's own session store. requestScoped (cost.go)
@@ -609,6 +613,10 @@ func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []
ue.cumulative = true
}
ue.metricName, _ = event.Raw["metric_name"].(string)
+ if attrs, ok := event.Raw["attributes"].(map[string]interface{}); ok {
+ service, _ := attrs["service.name"].(string)
+ ue.codexAppServer = strings.EqualFold(strings.TrimSpace(service), "codex-app-server")
+ }
ue.rawSource, _ = event.Raw["source"].(string)
ue.tokenSource, _ = event.Raw["token_source"].(string)
if codex, ok := event.Raw["codex_session"].(map[string]interface{}); ok {
@@ -627,6 +635,11 @@ func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []
// the first time it appears for an endpoint/model. Legacy aggregate metrics
// before that cutover remain reportable, while a manually configured
// trace+metric overlap after it cannot double-count the same turns.
+//
+// A legacy metric from Codex's app-server names no conversation, so the exporter can't tell
+// whether the CLI or the desktop app sent it and records it as codex_cli. Both surfaces read one
+// ~/.codex/config.toml and so export the same signals; a turn span from either covers it. Metrics
+// from an older CLI (codex_cli_rs) keep to their own harness.
func preferCodexTurnSpans(events []*usageEvent) []*usageEvent {
type sourceKey struct {
endpoint string
@@ -659,7 +672,16 @@ func preferCodexTurnSpans(events []*usageEvent) []*usageEvent {
}
out := events[:0]
for _, event := range events {
- cutover, ok := cutovers[keyFor(event)]
+ key := keyFor(event)
+ cutover, ok := cutovers[key]
+ if event.codexAppServer && usageHarnessKey(key.harness) == "codex_cli" {
+ for _, surface := range []string{"codex_cli", "codex_desktop"} {
+ key.harness = surface
+ if other, found := cutovers[key]; found && (!ok || other.Before(cutover)) {
+ cutover, ok = other, true
+ }
+ }
+ }
if ok &&
strings.EqualFold(event.metricName, "codex.turn.token_usage") &&
!event.ts.IsZero() &&
@@ -690,11 +712,23 @@ func liveScopeFor(endpoint, harness, session string) (liveScope, bool) {
}
return liveScope{
endpoint: strings.ToLower(strings.TrimSpace(endpoint)),
- harness: asymptoteobserve.NormalizeHarnessName(harness),
+ harness: usageHarnessKey(harness),
session: session,
}, true
}
+// usageHarnessKey is the harness a session's live/poll check groups by. Codex's CLI and desktop app
+// are one runtime with one session store and one set of conversation ids, and `codex sync` reads
+// both surfaces' rollouts and names them codex_cli. So within one session the two names are one
+// key, or a Desktop session's backfill would be counted again beside its live capture.
+func usageHarnessKey(harness string) string {
+ normalized := asymptoteobserve.NormalizeHarnessName(harness)
+ if normalized == "codex_desktop" {
+ return "codex_cli"
+ }
+ return normalized
+}
+
// isLiveCollectionMethod reports whether a collection method observed the runtime as it worked.
// An unset method is not live: it is a log written before provenance existed, or an event Beacon
// emitted about itself, and neither is evidence that a live channel covered the session.
diff --git a/cli/beacon/internal/tokens/tokens_test.go b/cli/beacon/internal/tokens/tokens_test.go
index 4a883196..3cd58aa3 100644
--- a/cli/beacon/internal/tokens/tokens_test.go
+++ b/cli/beacon/internal/tokens/tokens_test.go
@@ -846,6 +846,60 @@ func TestAggregatePrefersLiveCaptureOverPollBackfill(t *testing.T) {
wantEvents: 2,
suppressed: 1,
},
+ {
+ // The app-server's legacy metric names no conversation, so the exporter can't place it
+ // and it is codex_cli; the Desktop turn span over the same turns must still drop it.
+ name: "codex desktop turn span and an app-server legacy metric",
+ events: []schema.Event{
+ event("2026-06-11T10:00:30Z", "codex_cli", otlp, "", "token.usage", &tokens{input: 20}, func(e *schema.Event) {
+ e.Model = "gpt-5.6-sol"
+ e.Raw = map[string]interface{}{"metric_name": "codex.turn.token_usage", "metric_temporality": "Delta",
+ "attributes": map[string]interface{}{"service.name": "codex-app-server"}}
+ }),
+ event("2026-06-11T10:00:30Z", "codex_desktop", otlp, "019a-desktop", "token.usage", &tokens{input: 20}, func(e *schema.Event) {
+ e.Model = "gpt-5.6-sol"
+ e.Raw = map[string]interface{}{"source": "codex_turn_span", "turn_start_timestamp": "2026-06-11T10:00:01Z"}
+ }),
+ },
+ want: tokens{input: 20},
+ wantEvents: 1,
+ suppressed: 0,
+ },
+ {
+ // An older CLI exports only the legacy metric, under its own service name; Desktop's
+ // turn spans on the same machine and model cover none of its turns.
+ name: "codex desktop turn span and an older CLI's legacy metric",
+ events: []schema.Event{
+ event("2026-06-11T10:00:00Z", "codex_desktop", otlp, "019a-desktop", "token.usage", &tokens{input: 20}, func(e *schema.Event) {
+ e.Model = "gpt-5.6-sol"
+ e.Raw = map[string]interface{}{"source": "codex_turn_span", "turn_start_timestamp": "2026-06-11T09:59:50Z"}
+ }),
+ event("2026-06-11T10:05:00Z", "codex_cli", otlp, "", "token.usage", &tokens{input: 7}, func(e *schema.Event) {
+ e.Model = "gpt-5.6-sol"
+ e.Raw = map[string]interface{}{"metric_name": "codex.turn.token_usage", "metric_temporality": "Delta",
+ "attributes": map[string]interface{}{"service.name": "codex_cli_rs"}}
+ }),
+ },
+ want: tokens{input: 27},
+ wantEvents: 2,
+ suppressed: 0,
+ },
+ {
+ // `codex sync` reads Desktop rollouts too and names them codex_cli; live capture of
+ // the same conversation is codex_desktop. One session, so the backfill goes.
+ name: "codex desktop live capture and codex sync",
+ events: []schema.Event{
+ event("2026-06-11T10:00:00Z", "codex_desktop", otlp, "019a-desktop", "session.started", nil, nil),
+ event("2026-06-11T10:00:20Z", "codex_cli", poll, "019a-desktop", "token.usage", &tokens{input: 500, output: 40}, model("gpt-5.6-sol")),
+ event("2026-06-11T10:00:30Z", "codex_desktop", otlp, "019a-desktop", "token.usage", &tokens{input: 500, output: 40}, func(e *schema.Event) {
+ e.Model = "gpt-5.6-sol"
+ e.Raw = map[string]interface{}{"source": "codex_turn_span", "turn_start_timestamp": "2026-06-11T10:00:01Z"}
+ }),
+ },
+ want: tokens{input: 500, output: 40},
+ wantEvents: 1,
+ suppressed: 1,
+ },
{
// Cline's plugin reports usage once, on the run result at task end; `cline sync`
// reports it per API request from the task's ui_messages. The task-end total covers
diff --git a/collector-builder/exporter/beaconjsonexporter/codex_surface_e2e_test.go b/collector-builder/exporter/beaconjsonexporter/codex_surface_e2e_test.go
new file mode 100644
index 00000000..dd3f5258
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/codex_surface_e2e_test.go
@@ -0,0 +1,176 @@
+package beaconjsonexporter
+
+import (
+ "context"
+ "path/filepath"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "go.opentelemetry.io/collector/component"
+ "go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/ptrace"
+ "go.opentelemetry.io/collector/processor/processortest"
+)
+
+type nopHost struct{}
+
+func (nopHost) GetExtensions() map[component.ID]component.Component { return nil }
+
+// The CLI and the desktop app both export as codex-app-server. The collector builds a separate
+// exporter per pipeline from one config, as here: each conversation's logs name its surface on the
+// logs exporter, and its usage span, which reaches the traces exporter later without an
+// originator, lands under the same harness.
+func TestCollectorNamesCodexAppServerSessionsByOriginator(t *testing.T) {
+ ctx := context.Background()
+ cfg := &Config{
+ Path: filepath.Join(t.TempDir(), "runtime.jsonl"),
+ MaxEventBytes: defaultMaxEventBytes,
+ RotateBytes: defaultRotateBytes,
+ RedactSecrets: true,
+ }
+ nop := processortest.NewNopSettings(componentType)
+ set := exporter.Settings{ID: nop.ID, TelemetrySettings: nop.TelemetrySettings, BuildInfo: nop.BuildInfo}
+ factory := NewFactory()
+ logsExporter, err := factory.CreateLogs(ctx, set, cfg)
+ if err != nil {
+ t.Fatalf("CreateLogs: %v", err)
+ }
+ tracesExporter, err := factory.CreateTraces(ctx, set, cfg)
+ if err != nil {
+ t.Fatalf("CreateTraces: %v", err)
+ }
+ for _, exp := range []component.Component{logsExporter, tracesExporter} {
+ if err := exp.Start(ctx, nopHost{}); err != nil {
+ t.Fatalf("Start: %v", err)
+ }
+ t.Cleanup(func() { _ = exp.Shutdown(ctx) })
+ }
+
+ logs := plog.NewLogs()
+ rl := logs.ResourceLogs().AppendEmpty()
+ rl.Resource().Attributes().PutStr("service.name", "codex-app-server")
+ sl := rl.ScopeLogs().AppendEmpty()
+ for _, conv := range []struct{ id, originator string }{{"cli-conv", "codex-tui"}, {"desktop-conv", "Codex_Desktop"}} {
+ for _, eventName := range []string{"codex.conversation_starts", "codex.user_prompt"} {
+ rec := sl.LogRecords().AppendEmpty()
+ rec.Attributes().PutStr("event.name", eventName)
+ rec.Attributes().PutStr("conversation.id", conv.id)
+ rec.Attributes().PutStr("originator", conv.originator)
+ rec.Attributes().PutStr("model", "gpt-5.5")
+ if eventName == "codex.user_prompt" {
+ rec.Attributes().PutStr("prompt", "list the files")
+ }
+ }
+ }
+ if err := logsExporter.ConsumeLogs(ctx, logs); err != nil {
+ t.Fatalf("ConsumeLogs: %v", err)
+ }
+
+ traces := ptrace.NewTraces()
+ rs := traces.ResourceSpans().AppendEmpty()
+ rs.Resource().Attributes().PutStr("service.name", "codex-app-server")
+ ss := rs.ScopeSpans().AppendEmpty()
+ for _, thread := range []string{"cli-conv", "desktop-conv"} {
+ span := ss.Spans().AppendEmpty()
+ span.SetName("session_task.turn")
+ span.Attributes().PutStr("thread.id", thread)
+ span.Attributes().PutInt("codex.turn.token_usage.input_tokens", 1200)
+ span.Attributes().PutInt("codex.turn.token_usage.output_tokens", 80)
+ }
+ if err := tracesExporter.ConsumeTraces(ctx, traces); err != nil {
+ t.Fatalf("ConsumeTraces: %v", err)
+ }
+
+ // A short turn's span can beat its prompt log across the two pipelines: the traces exporter
+ // holds it, and the logs exporter writes it once the log names the conversation.
+ early := ptrace.NewTraces()
+ ers := early.ResourceSpans().AppendEmpty()
+ ers.Resource().Attributes().PutStr("service.name", "codex-app-server")
+ earlySpan := ers.ScopeSpans().AppendEmpty().Spans().AppendEmpty()
+ earlySpan.SetName("session_task.turn")
+ earlySpan.Attributes().PutStr("thread.id", "quick-desktop-conv")
+ earlySpan.Attributes().PutInt("codex.turn.token_usage.input_tokens", 300)
+ if err := tracesExporter.ConsumeTraces(ctx, early); err != nil {
+ t.Fatalf("ConsumeTraces: %v", err)
+ }
+ for _, event := range readEvents(t, cfg.Path) {
+ if event.Session != nil && event.Session.ID == "quick-desktop-conv" {
+ t.Fatalf("span written before its conversation was named: %+v", event)
+ }
+ }
+ quick := plog.NewLogs()
+ qrl := quick.ResourceLogs().AppendEmpty()
+ qrl.Resource().Attributes().PutStr("service.name", "codex-app-server")
+ qrec := qrl.ScopeLogs().AppendEmpty().LogRecords().AppendEmpty()
+ qrec.Attributes().PutStr("event.name", "codex.user_prompt")
+ qrec.Attributes().PutStr("conversation.id", "quick-desktop-conv")
+ qrec.Attributes().PutStr("originator", "Codex_Desktop")
+ qrec.Attributes().PutStr("prompt", "hi")
+ if err := logsExporter.ConsumeLogs(ctx, quick); err != nil {
+ t.Fatalf("ConsumeLogs: %v", err)
+ }
+
+ want := map[string]string{"cli-conv": "codex_cli", "desktop-conv": "codex_desktop", "quick-desktop-conv": "codex_desktop"}
+ usage := 0
+ for _, event := range readEvents(t, cfg.Path) {
+ if event.Session == nil {
+ t.Fatalf("event without a session: %#v", event)
+ }
+ if got := event.Harness.Name; got != want[event.Session.ID] {
+ t.Errorf("%s in %s recorded as %q, want %q", event.Event.Action, event.Session.ID, got, want[event.Session.ID])
+ }
+ if event.Event.Action == "token.usage" {
+ usage++
+ }
+ }
+ if usage != 3 {
+ t.Fatalf("wrote %d token.usage events, want 3", usage)
+ }
+}
+
+// A span whose conversation is never named goes out when its wait runs out, without waiting for
+// another batch to carry it.
+func TestExporterWritesAnUnnamedCodexSpanWhenItsWaitRunsOut(t *testing.T) {
+ var ahead atomic.Int64
+ clock, every := codexClock, codexReleaseEvery
+ codexClock = func() time.Time { return time.Now().Add(time.Duration(ahead.Load())) }
+ codexReleaseEvery = 10 * time.Millisecond
+ t.Cleanup(func() { codexClock, codexReleaseEvery = clock, every })
+
+ ctx := context.Background()
+ exp, path := newTestExporter(t)
+ if err := exp.start(ctx, nopHost{}); err != nil {
+ t.Fatalf("start: %v", err)
+ }
+ defer func() { _ = exp.shutdown(ctx) }()
+
+ traces := ptrace.NewTraces()
+ rs := traces.ResourceSpans().AppendEmpty()
+ rs.Resource().Attributes().PutStr("service.name", "codex-app-server")
+ span := rs.ScopeSpans().AppendEmpty().Spans().AppendEmpty()
+ span.SetName("session_task.turn")
+ span.Attributes().PutStr("thread.id", "logs-never-came")
+ span.Attributes().PutInt("codex.turn.token_usage.input_tokens", 300)
+ if err := exp.consumeTraces(ctx, traces); err != nil {
+ t.Fatalf("consumeTraces: %v", err)
+ }
+ time.Sleep(50 * time.Millisecond)
+ if events := readEvents(t, path); len(events) != 0 {
+ t.Fatalf("written before the wait ran out: %+v", events)
+ }
+
+ ahead.Store(int64(time.Minute))
+ deadline := time.Now().Add(5 * time.Second)
+ for time.Now().Before(deadline) {
+ if events := readEvents(t, path); len(events) == 1 {
+ if events[0].Harness.Name != "codex_cli" || events[0].Event.Action != "token.usage" {
+ t.Fatalf("released %s as %q, want token.usage as codex_cli", events[0].Event.Action, events[0].Harness.Name)
+ }
+ return
+ }
+ time.Sleep(10 * time.Millisecond)
+ }
+ t.Fatal("the held span was never written")
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/exporter.go b/collector-builder/exporter/beaconjsonexporter/exporter.go
index e604d25f..fd51463f 100644
--- a/collector-builder/exporter/beaconjsonexporter/exporter.go
+++ b/collector-builder/exporter/beaconjsonexporter/exporter.go
@@ -7,6 +7,7 @@ import (
"go.opentelemetry.io/collector/component"
"go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/exporter/exporterhelper"
"go.opentelemetry.io/collector/pdata/pcommon"
"go.opentelemetry.io/collector/pdata/plog"
"go.opentelemetry.io/collector/pdata/pmetric"
@@ -31,8 +32,24 @@ type beaconExporter struct {
// listings keeps one mcp.tool_listed per tool per session out of the copy Claude Code sends
// with every model request.
listings *beaconevent.MCPListings
+ // codexSurfaces remembers which Codex surface each conversation runs in. It is shared with
+ // the other signals' exporters built from this config, so a usage span that doesn't name its
+ // surface gets the one its conversation's logs did.
+ codexSurfaces *beaconevent.CodexSurfaces
+ releaseCodexSurfaces func()
+ // stopCodexRelease ends the loop start runs; codexReleaseDone closes once it has.
+ stopCodexRelease chan struct{}
+ codexReleaseDone chan struct{}
}
+// codexReleaseEvery is how often the exporter writes the Codex records whose wait for their
+// conversation's logs has run out, so they reach the log on time when no batch arrives to carry
+// them.
+var codexReleaseEvery = time.Second
+
+// codexClock is the time the Codex hold runs on; tests move it.
+var codexClock = time.Now
+
func newExporter(raw component.Config, set exporter.Settings) (*beaconExporter, error) {
cfg, ok := raw.(*Config)
if !ok {
@@ -50,6 +67,7 @@ func newExporter(raw component.Config, set exporter.Settings) (*beaconExporter,
if err := cfg.Validate(); err != nil {
return nil, err
}
+ codexSurfaces, release := beaconevent.AcquireCodexSurfaces(cfg)
return &beaconExporter{
cfg: cfg,
writer: jsonlWriter{
@@ -59,37 +77,72 @@ func newExporter(raw component.Config, set exporter.Settings) (*beaconExporter,
rotateArchives: cfg.RotateArchives,
redactSecrets: cfg.RedactSecrets,
},
- logger: set.Logger,
- sequence: &asymptoteobserve.Sequencer{},
- listings: &beaconevent.MCPListings{},
+ logger: set.Logger,
+ sequence: &asymptoteobserve.Sequencer{},
+ listings: &beaconevent.MCPListings{},
+ codexSurfaces: codexSurfaces,
+ releaseCodexSurfaces: release,
converter: beaconevent.NewConverter(beaconevent.Options{
IncludeRuntimeMetrics: cfg.IncludeRuntimeMetrics,
IncludeCodexSpans: cfg.IncludeCodexSpans,
CaptureModelContext: cfg.CaptureModelContext,
+ CodexSurfaces: codexSurfaces,
}),
}, nil
}
-func (e *beaconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error {
- _ = ctx
- var firstErr error
- for _, event := range e.listings.Filter(e.eventConverter().EventsFromLogs(logs)) {
- e.stampSequence(&event)
- if err := e.writer.append(event); err != nil {
- if firstErr == nil {
- firstErr = err
+// lifecycle is the start and shutdown every signal's exporter runs.
+func (e *beaconExporter) lifecycle() []exporterhelper.Option {
+ return []exporterhelper.Option{exporterhelper.WithStart(e.start), exporterhelper.WithShutdown(e.shutdown)}
+}
+
+// start runs the loop that writes Codex records once their wait runs out.
+func (e *beaconExporter) start(context.Context, component.Host) error {
+ e.stopCodexRelease = make(chan struct{})
+ e.codexReleaseDone = make(chan struct{})
+ go func() {
+ defer close(e.codexReleaseDone)
+ ticker := time.NewTicker(codexReleaseEvery)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-e.stopCodexRelease:
+ return
+ case <-ticker.C:
+ if err := e.writeEvents(e.sortCodex(nil)); err != nil && e.logger != nil {
+ e.logger.Warn("writing held Codex records failed", zap.Error(err))
+ }
}
- continue
}
- e.listings.Remember(event)
+ }()
+ return nil
+}
+
+// shutdown writes the Codex records still waiting for their conversation's surface, as they
+// stand, and gives up this exporter's share of the memory.
+func (e *beaconExporter) shutdown(context.Context) error {
+ if e.stopCodexRelease != nil {
+ close(e.stopCodexRelease)
+ <-e.codexReleaseDone
+ e.stopCodexRelease = nil
+ }
+ firstErr := e.writeEvents(e.codexSurfaces.Drain())
+ if e.releaseCodexSurfaces != nil {
+ e.releaseCodexSurfaces()
}
return firstErr
}
-func (e *beaconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces) error {
- _ = ctx
+// sortCodex returns the events to write now. A Codex record whose surface isn't known yet waits
+// in the shared memory, and goes out with whichever exporter's batch names it or comes after its
+// wait runs out (see beaconevent.CodexSurfaces.Sort).
+func (e *beaconExporter) sortCodex(events []beaconEvent) []beaconEvent {
+ return e.codexSurfaces.Sort(events, codexClock())
+}
+
+func (e *beaconExporter) writeEvents(events []beaconEvent) error {
var firstErr error
- for _, event := range e.eventConverter().EventsFromTraces(traces) {
+ for _, event := range events {
e.stampSequence(&event)
if err := e.writer.append(event); err != nil && firstErr == nil {
firstErr = err
@@ -98,18 +151,32 @@ func (e *beaconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces
return firstErr
}
-func (e *beaconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Metrics) error {
+func (e *beaconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error {
_ = ctx
var firstErr error
- for _, event := range e.eventConverter().EventsFromMetrics(metrics) {
+ for _, event := range e.sortCodex(e.listings.Filter(e.eventConverter().EventsFromLogs(logs))) {
e.stampSequence(&event)
- if err := e.writer.append(event); err != nil && firstErr == nil {
- firstErr = err
+ if err := e.writer.append(event); err != nil {
+ if firstErr == nil {
+ firstErr = err
+ }
+ continue
}
+ e.listings.Remember(event)
}
return firstErr
}
+func (e *beaconExporter) consumeTraces(ctx context.Context, traces ptrace.Traces) error {
+ _ = ctx
+ return e.writeEvents(e.sortCodex(e.eventConverter().EventsFromTraces(traces)))
+}
+
+func (e *beaconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Metrics) error {
+ _ = ctx
+ return e.writeEvents(e.sortCodex(e.eventConverter().EventsFromMetrics(metrics)))
+}
+
// stampSequence gives the event this exporter's next emission number, unless the runtime
// already supplied one of its own on the wire and the converter promoted it.
func (e *beaconExporter) stampSequence(event *beaconEvent) {
@@ -167,6 +234,7 @@ func (e *beaconExporter) eventConverter() beaconevent.Converter {
IncludeRuntimeMetrics: e.cfg.IncludeRuntimeMetrics,
IncludeCodexSpans: e.cfg.IncludeCodexSpans,
CaptureModelContext: e.cfg.CaptureModelContext,
+ CodexSurfaces: e.codexSurfaces,
})
}
diff --git a/collector-builder/exporter/beaconjsonexporter/factory.go b/collector-builder/exporter/beaconjsonexporter/factory.go
index 05a904cd..e2f17dfd 100644
--- a/collector-builder/exporter/beaconjsonexporter/factory.go
+++ b/collector-builder/exporter/beaconjsonexporter/factory.go
@@ -27,7 +27,7 @@ func createLogsExporter(ctx context.Context, set exporter.Settings, cfg componen
if err != nil {
return nil, err
}
- return exporterhelper.NewLogs(ctx, set, cfg, consumer.ConsumeLogsFunc(exp.consumeLogs))
+ return exporterhelper.NewLogs(ctx, set, cfg, consumer.ConsumeLogsFunc(exp.consumeLogs), exp.lifecycle()...)
}
func createTracesExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Traces, error) {
@@ -35,7 +35,7 @@ func createTracesExporter(ctx context.Context, set exporter.Settings, cfg compon
if err != nil {
return nil, err
}
- return exporterhelper.NewTraces(ctx, set, cfg, consumer.ConsumeTracesFunc(exp.consumeTraces))
+ return exporterhelper.NewTraces(ctx, set, cfg, consumer.ConsumeTracesFunc(exp.consumeTraces), exp.lifecycle()...)
}
func createMetricsExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Metrics, error) {
@@ -43,5 +43,5 @@ func createMetricsExporter(ctx context.Context, set exporter.Settings, cfg compo
if err != nil {
return nil, err
}
- return exporterhelper.NewMetrics(ctx, set, cfg, consumer.ConsumeMetricsFunc(exp.consumeMetrics))
+ return exporterhelper.NewMetrics(ctx, set, cfg, consumer.ConsumeMetricsFunc(exp.consumeMetrics), exp.lifecycle()...)
}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
index 12a72820..b3c0d784 100644
--- a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/exporter.go
@@ -16,6 +16,7 @@ import (
"go.opentelemetry.io/collector/component"
"go.opentelemetry.io/collector/consumer"
"go.opentelemetry.io/collector/exporter"
+ "go.opentelemetry.io/collector/exporter/exporterhelper"
"go.opentelemetry.io/collector/pdata/plog"
"go.opentelemetry.io/collector/pdata/pmetric"
"go.opentelemetry.io/collector/pdata/ptrace"
@@ -31,6 +32,12 @@ type falconExporter struct {
logger *zap.Logger
converter beaconevent.Converter
listings *beaconevent.MCPListings
+ // releaseCodexSurfaces gives up this exporter's share of the Codex surface memory it holds
+ // with the other signals' exporters built from the same config. Unlike the JSONL exporter it
+ // doesn't hold records back for a conversation's logs (CodexSurfaces.Sort): exporterhelper
+ // retries a failed send by running the batch again, which would lose held records released
+ // into it.
+ releaseCodexSurfaces func()
}
type hecPayload struct {
@@ -56,6 +63,7 @@ func newExporter(raw component.Config, set exporter.Settings) (*falconExporter,
if err != nil {
return nil, err
}
+ codexSurfaces, release := beaconevent.AcquireCodexSurfaces(cfg)
return &falconExporter{
cfg: cfg,
client: client,
@@ -64,11 +72,20 @@ func newExporter(raw component.Config, set exporter.Settings) (*falconExporter,
IncludeRuntimeMetrics: cfg.IncludeRuntimeMetrics,
IncludeCodexSpans: cfg.IncludeCodexSpans,
CaptureModelContext: cfg.CaptureModelContext,
+ CodexSurfaces: codexSurfaces,
}),
- listings: &beaconevent.MCPListings{},
+ listings: &beaconevent.MCPListings{},
+ releaseCodexSurfaces: release,
}, nil
}
+func (e *falconExporter) shutdown(context.Context) error {
+ if e.releaseCodexSurfaces != nil {
+ e.releaseCodexSurfaces()
+ }
+ return nil
+}
+
func httpClient(cfg *Config) (*http.Client, error) {
transport := http.DefaultTransport.(*http.Transport).Clone()
if cfg.InsecureSkipVerify || cfg.CAFile != "" {
@@ -192,7 +209,7 @@ func createLogsExporter(ctx context.Context, set exporter.Settings, cfg componen
return nil, err
}
fcfg := cfg.(*Config)
- return exporterhelperNewLogs(ctx, set, cfg, consumer.ConsumeLogsFunc(exp.consumeLogs), fcfg)
+ return exporterhelperNewLogs(ctx, set, cfg, consumer.ConsumeLogsFunc(exp.consumeLogs), fcfg, exporterhelper.WithShutdown(exp.shutdown))
}
func createTracesExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Traces, error) {
@@ -201,7 +218,7 @@ func createTracesExporter(ctx context.Context, set exporter.Settings, cfg compon
return nil, err
}
fcfg := cfg.(*Config)
- return exporterhelperNewTraces(ctx, set, cfg, consumer.ConsumeTracesFunc(exp.consumeTraces), fcfg)
+ return exporterhelperNewTraces(ctx, set, cfg, consumer.ConsumeTracesFunc(exp.consumeTraces), fcfg, exporterhelper.WithShutdown(exp.shutdown))
}
func createMetricsExporter(ctx context.Context, set exporter.Settings, cfg component.Config) (exporter.Metrics, error) {
@@ -210,5 +227,5 @@ func createMetricsExporter(ctx context.Context, set exporter.Settings, cfg compo
return nil, err
}
fcfg := cfg.(*Config)
- return exporterhelperNewMetrics(ctx, set, cfg, consumer.ConsumeMetricsFunc(exp.consumeMetrics), fcfg)
+ return exporterhelperNewMetrics(ctx, set, cfg, consumer.ConsumeMetricsFunc(exp.consumeMetrics), fcfg, exporterhelper.WithShutdown(exp.shutdown))
}
diff --git a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go
index 5b02c5e6..ad83b329 100644
--- a/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go
+++ b/collector-builder/exporter/beaconjsonexporter/falconhecexporter/factory.go
@@ -29,14 +29,14 @@ func exporterOptions(cfg *Config) []exporterhelper.Option {
}
}
-func exporterhelperNewLogs(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeLogsFunc, fcfg *Config) (exporter.Logs, error) {
- return exporterhelper.NewLogs(ctx, set, cfg, pusher, exporterOptions(fcfg)...)
+func exporterhelperNewLogs(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeLogsFunc, fcfg *Config, extra ...exporterhelper.Option) (exporter.Logs, error) {
+ return exporterhelper.NewLogs(ctx, set, cfg, pusher, append(exporterOptions(fcfg), extra...)...)
}
-func exporterhelperNewTraces(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeTracesFunc, fcfg *Config) (exporter.Traces, error) {
- return exporterhelper.NewTraces(ctx, set, cfg, pusher, exporterOptions(fcfg)...)
+func exporterhelperNewTraces(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeTracesFunc, fcfg *Config, extra ...exporterhelper.Option) (exporter.Traces, error) {
+ return exporterhelper.NewTraces(ctx, set, cfg, pusher, append(exporterOptions(fcfg), extra...)...)
}
-func exporterhelperNewMetrics(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeMetricsFunc, fcfg *Config) (exporter.Metrics, error) {
- return exporterhelper.NewMetrics(ctx, set, cfg, pusher, exporterOptions(fcfg)...)
+func exporterhelperNewMetrics(ctx context.Context, set exporter.Settings, cfg component.Config, pusher consumer.ConsumeMetricsFunc, fcfg *Config, extra ...exporterhelper.Option) (exporter.Metrics, error) {
+ return exporterhelper.NewMetrics(ctx, set, cfg, pusher, append(exporterOptions(fcfg), extra...)...)
}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/codex_surface.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/codex_surface.go
new file mode 100644
index 00000000..e321fa9d
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/codex_surface.go
@@ -0,0 +1,264 @@
+package beaconevent
+
+import (
+ "container/list"
+ "strings"
+ "sync"
+ "time"
+)
+
+// Codex runs on one set of app-server internals in the desktop app and, since about CLI 0.158, in the
+// terminal too, and both export OTLP as service.name=codex-app-server. The service name alone
+// therefore can't tell the Codex desktop app from the CLI. What does is the `originator` attribute
+// Codex puts on its semantic log events: "Codex_Desktop" for the desktop app, "codex-tui" for the
+// terminal, "codex_exec" for `codex exec`.
+//
+// Not every record carries it: the per-turn usage span has only the conversation (thread) id, and
+// the legacy token metric not even that. So the surface an originator names is remembered per
+// conversation, and a conversation's records without one get the same name. A record with neither
+// stays codex_cli, the name Codex's hooks use on every surface.
+//
+// The logs and traces pipelines flush on their own timers, so a short turn's usage span can reach
+// the exporter before the prompt log that names its conversation. Sort holds such a record until
+// its conversation is named or codexHoldWindow runs out.
+
+const (
+ codexCLIHarness = "codex_cli"
+ codexDesktopHarness = "codex_desktop"
+)
+
+// maxCodexConversations bounds the conversations remembered, least recently used first out. A
+// Codex conversation's records arrive within its own lifetime, so a few thousand recent
+// conversations cover any real machine.
+const maxCodexConversations = 4096
+
+// codexHoldWindow is how long Sort holds a record for its conversation's logs. Codex batches its
+// logs for up to a second and the collector's batch processor waits up to five more.
+const codexHoldWindow = 10 * time.Second
+
+// maxHeldCodexEvents bounds the records held at once; past it the oldest goes out as it is.
+const maxHeldCodexEvents = 1024
+
+// CodexSurfaces remembers which Codex surface each conversation runs in. It is shared across every
+// signal the exporter receives (logs, traces, metrics arrive on separate pipelines), so it is safe
+// for concurrent use. The zero value is ready to use; a nil *CodexSurfaces remembers nothing.
+type CodexSurfaces struct {
+ mu sync.Mutex
+ byID map[string]*list.Element
+ // recent orders the conversations most recently used first; each element holds a
+ // codexConversation.
+ recent list.List
+ // held are the records Sort is waiting to name, oldest first.
+ held []heldCodexEvent
+}
+
+type heldCodexEvent struct {
+ event Event
+ until time.Time
+}
+
+type codexConversation struct {
+ id string
+ surface string
+}
+
+// The collector builds a separate exporter for each pipeline (logs, traces, metrics) from one
+// exporter config, and the originator arrives only on logs. So the exporters built from one config
+// share one CodexSurfaces, or the traces and metrics exporters would never learn what the logs
+// exporter did.
+var sharedCodexSurfaces = struct {
+ sync.Mutex
+ byConfig map[any]*codexSurfacesUse
+}{byConfig: map[any]*codexSurfacesUse{}}
+
+type codexSurfacesUse struct {
+ surfaces *CodexSurfaces
+ users int
+}
+
+// AcquireCodexSurfaces returns the CodexSurfaces shared by every exporter built from config, and
+// a release for the exporter to call when it shuts down; the last release frees it. config is the
+// exporter's config pointer, which the collector passes to each signal's create function.
+func AcquireCodexSurfaces(config any) (*CodexSurfaces, func()) {
+ sharedCodexSurfaces.Lock()
+ defer sharedCodexSurfaces.Unlock()
+ use := sharedCodexSurfaces.byConfig[config]
+ if use == nil {
+ use = &codexSurfacesUse{surfaces: &CodexSurfaces{}}
+ sharedCodexSurfaces.byConfig[config] = use
+ }
+ use.users++
+ var once sync.Once
+ return use.surfaces, func() {
+ once.Do(func() {
+ sharedCodexSurfaces.Lock()
+ defer sharedCodexSurfaces.Unlock()
+ if use.users--; use.users == 0 && sharedCodexSurfaces.byConfig[config] == use {
+ delete(sharedCodexSurfaces.byConfig, config)
+ }
+ })
+ }
+}
+
+// codexSurfaceFromOriginator is the harness an originator names, or "" when there is none.
+func codexSurfaceFromOriginator(originator string) string {
+ normalized := strings.ToLower(strings.TrimSpace(originator))
+ switch {
+ case normalized == "":
+ return ""
+ case strings.Contains(normalized, "desktop"):
+ return codexDesktopHarness
+ default:
+ return codexCLIHarness
+ }
+}
+
+// isCodexAppServerName is true for the service name both the desktop app and the CLI's app-server
+// report, the one name that needs an originator to place.
+func isCodexAppServerName(name string) bool {
+ normalized := strings.NewReplacer("-", "", "_", "", " ", "").Replace(strings.ToLower(strings.TrimSpace(name)))
+ return normalized == "codexappserver"
+}
+
+// settle sets a Codex event's harness to the surface it ran in. It only touches events whose name
+// came from the shared app-server service name; a name stated outright (beacon.harness.name,
+// harness.name) or a CLI-only service (codex_cli_rs, codex_exec) is already exact.
+func (s *CodexSurfaces) settle(event *Event, attrs map[string]interface{}) {
+ if event == nil || !isCodexHarness(event.Harness.Name) {
+ return
+ }
+ if FirstString(attrs, "beacon.harness.name", "harness.name") != "" {
+ return
+ }
+ if !isCodexAppServerName(FirstString(attrs, "service.name")) {
+ return
+ }
+ conversation := ""
+ if event.Session != nil {
+ conversation = event.Session.ID
+ }
+ if conversation == "" {
+ conversation = FirstString(attrs, "conversation.id", "thread.id", "conversation_id", "thread_id")
+ }
+ surface := codexSurfaceFromOriginator(FirstString(attrs, "originator"))
+ switch {
+ case surface != "":
+ s.remember(conversation, surface)
+ default:
+ surface = s.recall(conversation)
+ }
+ if surface == "" {
+ surface = codexCLIHarness
+ if s != nil {
+ event.codexConversation = conversation
+ }
+ }
+ event.Harness.Name = surface
+}
+
+// Sort returns the events to write now, in order: the given ones whose surface is settled, then
+// any held earlier whose conversation has since been named or whose wait has run out. A Codex
+// app-server record whose conversation is unnamed is held back instead. Every exporter sharing the
+// memory calls it with each batch, so a log that names a conversation releases that conversation's
+// held records through whichever exporter received the log, and with no events on a timer, so a
+// record whose wait ran out is written without waiting for the next batch.
+func (s *CodexSurfaces) Sort(events []Event, now time.Time) []Event {
+ if s == nil {
+ return events
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ ready := make([]Event, 0, len(events))
+ for _, event := range events {
+ if event.codexConversation == "" || s.nameLocked(&event) {
+ ready = append(ready, event)
+ continue
+ }
+ s.held = append(s.held, heldCodexEvent{event: event, until: now.Add(codexHoldWindow)})
+ }
+ for len(s.held) > maxHeldCodexEvents {
+ ready = append(ready, s.release(0))
+ }
+ for i := 0; i < len(s.held); {
+ held := &s.held[i]
+ if s.nameLocked(&held.event) || !now.Before(held.until) {
+ ready = append(ready, s.release(i))
+ continue
+ }
+ i++
+ }
+ return ready
+}
+
+// Drain returns every held record, named where its conversation now is, for an exporter shutting
+// down.
+func (s *CodexSurfaces) Drain() []Event {
+ if s == nil {
+ return nil
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ var out []Event
+ for len(s.held) > 0 {
+ s.nameLocked(&s.held[0].event)
+ out = append(out, s.release(0))
+ }
+ return out
+}
+
+// nameLocked gives a held record its conversation's surface once one is known, and reports
+// whether it did. s.mu is held.
+func (s *CodexSurfaces) nameLocked(event *Event) bool {
+ element, known := s.byID[event.codexConversation]
+ if !known {
+ return false
+ }
+ s.recent.MoveToFront(element)
+ event.Harness.Name = element.Value.(*codexConversation).surface
+ event.codexConversation = ""
+ return true
+}
+
+// release removes held record i and returns it as it stands, without the hold marker. s.mu is held.
+func (s *CodexSurfaces) release(i int) Event {
+ event := s.held[i].event
+ event.codexConversation = ""
+ s.held = append(s.held[:i], s.held[i+1:]...)
+ return event
+}
+
+func (s *CodexSurfaces) remember(conversation, surface string) {
+ if s == nil || conversation == "" {
+ return
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if element, known := s.byID[conversation]; known {
+ element.Value.(*codexConversation).surface = surface
+ s.recent.MoveToFront(element)
+ return
+ }
+ if s.byID == nil {
+ s.byID = make(map[string]*list.Element)
+ }
+ s.byID[conversation] = s.recent.PushFront(&codexConversation{id: conversation, surface: surface})
+ for s.recent.Len() > maxCodexConversations {
+ oldest := s.recent.Back()
+ s.recent.Remove(oldest)
+ delete(s.byID, oldest.Value.(*codexConversation).id)
+ }
+}
+
+func (s *CodexSurfaces) recall(conversation string) string {
+ if s == nil || conversation == "" {
+ return ""
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ element, known := s.byID[conversation]
+ if !known {
+ return ""
+ }
+ s.recent.MoveToFront(element)
+ return element.Value.(*codexConversation).surface
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/codex_surface_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/codex_surface_test.go
new file mode 100644
index 00000000..86ae00eb
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/codex_surface_test.go
@@ -0,0 +1,329 @@
+package beaconevent
+
+import (
+ "fmt"
+ "sync"
+ "testing"
+ "time"
+
+ "go.opentelemetry.io/collector/pdata/plog"
+ "go.opentelemetry.io/collector/pdata/pmetric"
+ "go.opentelemetry.io/collector/pdata/ptrace"
+)
+
+// codexLog is a Codex semantic log record with the attributes Codex sends: the event name, the
+// conversation it belongs to, and the surface that started it. An empty originator leaves the
+// attribute off, as Codex's own debug logs do.
+func codexLog(eventName, conversation, originator string) plog.LogRecord {
+ record := plog.NewLogRecord()
+ record.Attributes().PutStr("event.name", eventName)
+ if conversation != "" {
+ record.Attributes().PutStr("conversation.id", conversation)
+ }
+ if originator != "" {
+ record.Attributes().PutStr("originator", originator)
+ }
+ record.Attributes().PutStr("app.version", "0.164.0")
+ record.Attributes().PutStr("model", "gpt-5.5")
+ if eventName == "codex.user_prompt" {
+ record.Attributes().PutStr("prompt", "list the files")
+ }
+ return record
+}
+
+// codexTurnSpan is the per-turn usage span: it names its conversation as thread.id and carries no
+// originator.
+func codexTurnSpan(thread string) ptrace.Span {
+ span := ptrace.NewSpan()
+ span.SetName("session_task.turn")
+ span.Attributes().PutStr("thread.id", thread)
+ span.Attributes().PutStr("turn.id", "turn-1")
+ span.Attributes().PutInt("codex.turn.token_usage.input_tokens", 1200)
+ span.Attributes().PutInt("codex.turn.token_usage.output_tokens", 80)
+ return span
+}
+
+// codexUsageMetric is the legacy token metric. Codex exports it with no conversation id.
+func codexUsageMetric() pmetric.Metric {
+ metric := pmetric.NewMetric()
+ metric.SetName("codex.turn.token_usage")
+ dp := metric.SetEmptySum().DataPoints().AppendEmpty()
+ dp.SetDoubleValue(80)
+ dp.Attributes().PutStr("token_type", "output")
+ return metric
+}
+
+func appServer() map[string]interface{} {
+ return map[string]interface{}{"service.name": "codex-app-server"}
+}
+
+func TestCodexLogHarnessFollowsOriginator(t *testing.T) {
+ for name, tc := range map[string]struct {
+ resource map[string]interface{}
+ originator string
+ want string
+ }{
+ "CLI TUI on the app-server": {appServer(), "codex-tui", "codex_cli"},
+ "desktop app": {appServer(), "Codex_Desktop", "codex_desktop"},
+ "desktop, any spelling": {appServer(), "codex desktop", "codex_desktop"},
+ "desktop, upper case": {appServer(), "CODEX-DESKTOP", "codex_desktop"},
+ "codex exec on the app-server": {appServer(), "codex_exec", "codex_cli"},
+ "an originator Beacon has never seen": {appServer(), "some_new_surface", "codex_cli"},
+ "app-server record without one": {appServer(), "", "codex_cli"},
+ "codex exec": {map[string]interface{}{"service.name": "codex_exec"}, "codex_exec", "codex_cli"},
+ "older CLI": {map[string]interface{}{"service.name": "codex_cli_rs"}, "codex-tui", "codex_cli"},
+ "a desktop service name": {map[string]interface{}{"service.name": "codex_desktop"}, "", "codex_desktop"},
+ "a stated harness wins": {
+ map[string]interface{}{"service.name": "codex-app-server", "beacon.harness.name": "codex_desktop"}, "codex-tui", "codex_desktop",
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ converter := NewConverter(Options{CodexSurfaces: &CodexSurfaces{}})
+ event := converter.EventFromLog(tc.resource, codexLog("codex.user_prompt", "conv-1", tc.originator))
+ if event.Harness.Name != tc.want {
+ t.Fatalf("harness = %q, want %q", event.Harness.Name, tc.want)
+ }
+ })
+ }
+}
+
+// The bug this fixes: Codex CLI 0.158+ runs on the app-server, and every one of its sessions was
+// recorded as codex_desktop, the usage span included, on machines that never ran the desktop app.
+func TestCodexCLIOnTheAppServerIsNotRecordedAsDesktop(t *testing.T) {
+ converter := NewConverter(Options{CodexSurfaces: &CodexSurfaces{}})
+ conversation := "019a17e0-efe2-7ae3-b558-d333b8e7ce96"
+ events := []Event{
+ converter.EventFromLog(appServer(), codexLog("codex.conversation_starts", conversation, "codex-tui")),
+ converter.EventFromLog(appServer(), codexLog("codex.user_prompt", conversation, "codex-tui")),
+ converter.EventFromSpan(appServer(), codexTurnSpan(conversation)),
+ }
+ for _, event := range events {
+ if event.Harness.Name != "codex_cli" {
+ t.Fatalf("%s recorded as %q, want codex_cli", event.Event.Action, event.Harness.Name)
+ }
+ }
+}
+
+func TestCodexConversationKeepsItsSurfaceOnRecordsWithoutOriginator(t *testing.T) {
+ converter := NewConverter(Options{CodexSurfaces: &CodexSurfaces{}})
+
+ // Nothing has named this conversation yet: the usage span takes the default (and the exporter
+ // holds it for the conversation's logs; see TestCodexSurfacesHoldAConversationUntilItIsNamed).
+ if got := converter.EventFromSpan(appServer(), codexTurnSpan("early")).Harness.Name; got != "codex_cli" {
+ t.Fatalf("span before any log = %q, want codex_cli", got)
+ }
+
+ converter.EventFromLog(appServer(), codexLog("codex.conversation_starts", "desktop-conv", "Codex_Desktop"))
+ converter.EventFromLog(appServer(), codexLog("codex.conversation_starts", "cli-conv", "codex-tui"))
+
+ span := converter.EventFromSpan(appServer(), codexTurnSpan("desktop-conv"))
+ if span.Event.Action != "token.usage" || span.Harness.Name != "codex_desktop" {
+ t.Fatalf("desktop usage span = %s/%q, want token.usage/codex_desktop", span.Event.Action, span.Harness.Name)
+ }
+ if got := converter.EventFromSpan(appServer(), codexTurnSpan("cli-conv")).Harness.Name; got != "codex_cli" {
+ t.Fatalf("CLI usage span = %q, want codex_cli", got)
+ }
+ if got := converter.EventFromLog(appServer(), codexLog("codex.tool_result", "desktop-conv", "")).Harness.Name; got != "codex_desktop" {
+ t.Fatalf("desktop log without originator = %q, want codex_desktop", got)
+ }
+ // The legacy metric names no conversation, so nothing places it; the token report folds the
+ // two Codex names together where it matters (cli/beacon/internal/tokens usageHarnessKey).
+ for _, event := range converter.EventsFromMetric(appServer(), codexUsageMetric()) {
+ if event.Harness.Name != "codex_cli" {
+ t.Fatalf("usage metric without a conversation = %q, want codex_cli", event.Harness.Name)
+ }
+ }
+ if got := converter.EventFromSpan(appServer(), codexTurnSpan("unknown-conv")).Harness.Name; got != "codex_cli" {
+ t.Fatalf("span for an unnamed conversation = %q, want codex_cli", got)
+ }
+}
+
+func TestCodexSurfacesForgetTheLeastRecentlyUsedConversation(t *testing.T) {
+ surfaces := &CodexSurfaces{}
+ converter := NewConverter(Options{CodexSurfaces: surfaces})
+ converter.EventFromLog(appServer(), codexLog("codex.user_prompt", "oldest", "Codex_Desktop"))
+ converter.EventFromLog(appServer(), codexLog("codex.user_prompt", "active", "Codex_Desktop"))
+ // Two more than fit, so first-in-first-out would drop "active" too.
+ for i := 0; i < maxCodexConversations; i++ {
+ surfaces.remember(fmt.Sprintf("conv-%d", i), "codex_cli")
+ if i == maxCodexConversations/2 {
+ // A conversation still in use stays remembered however many start after it.
+ converter.EventFromSpan(appServer(), codexTurnSpan("active"))
+ }
+ }
+ if got := converter.EventFromSpan(appServer(), codexTurnSpan("oldest")).Harness.Name; got != "codex_cli" {
+ t.Fatalf("evicted conversation = %q, want the codex_cli default", got)
+ }
+ if got := converter.EventFromSpan(appServer(), codexTurnSpan("active")).Harness.Name; got != "codex_desktop" {
+ t.Fatalf("recently used conversation = %q, want codex_desktop", got)
+ }
+ surfaces.mu.Lock()
+ defer surfaces.mu.Unlock()
+ if surfaces.recent.Len() != maxCodexConversations || len(surfaces.byID) != maxCodexConversations {
+ t.Fatalf("remembered %d/%d conversations, want at most %d", surfaces.recent.Len(), len(surfaces.byID), maxCodexConversations)
+ }
+}
+
+// Without the shared memory each record is placed on its own: an originator still decides, and a
+// record without one takes the default.
+func TestCodexSurfaceWithoutMemory(t *testing.T) {
+ converter := Converter{}
+ if got := converter.EventFromLog(appServer(), codexLog("codex.user_prompt", "c", "Codex_Desktop")).Harness.Name; got != "codex_desktop" {
+ t.Fatalf("desktop log = %q, want codex_desktop", got)
+ }
+ if got := converter.EventFromSpan(appServer(), codexTurnSpan("c")).Harness.Name; got != "codex_cli" {
+ t.Fatalf("span = %q, want codex_cli", got)
+ }
+}
+
+// Logs, traces and metrics reach the exporter on separate pipelines.
+func TestCodexSurfacesAreSafeForConcurrentSignals(t *testing.T) {
+ converter := NewConverter(Options{CodexSurfaces: &CodexSurfaces{}})
+ var wg sync.WaitGroup
+ for i := 0; i < 8; i++ {
+ wg.Add(1)
+ go func(i int) {
+ defer wg.Done()
+ conversation := fmt.Sprintf("conv-%d", i%3)
+ for j := 0; j < 200; j++ {
+ converter.EventFromLog(appServer(), codexLog("codex.user_prompt", conversation, "Codex_Desktop"))
+ converter.EventFromSpan(appServer(), codexTurnSpan(conversation))
+ }
+ }(i)
+ }
+ wg.Wait()
+}
+
+// The collector builds the logs, traces and metrics exporters from one config separately; they
+// must hold one memory between them, and it goes when the last of them shuts down.
+func TestAcquireCodexSurfacesSharesOnePerConfig(t *testing.T) {
+ type config struct{ path string }
+ a, b := &config{"a"}, &config{"a"}
+ logs, releaseLogs := AcquireCodexSurfaces(a)
+ traces, releaseTraces := AcquireCodexSurfaces(a)
+ other, releaseOther := AcquireCodexSurfaces(b)
+ defer releaseOther()
+ if logs != traces {
+ t.Fatal("two exporters built from one config got separate memories")
+ }
+ if logs == other {
+ t.Fatal("exporters built from different configs share a memory")
+ }
+ logs.remember("desktop-conv", codexDesktopHarness)
+ if got := traces.recall("desktop-conv"); got != codexDesktopHarness {
+ t.Fatalf("traces exporter recalls %q, want codex_desktop", got)
+ }
+
+ releaseLogs()
+ releaseLogs() // a second release is a no-op
+ again, release := AcquireCodexSurfaces(a)
+ if again != traces {
+ t.Fatal("memory freed while an exporter still held it")
+ }
+ release()
+ releaseTraces()
+ fresh, release := AcquireCodexSurfaces(a)
+ defer release()
+ if fresh == traces {
+ t.Fatal("memory kept after every exporter released it")
+ }
+}
+
+// The logs and traces pipelines flush on their own timers, so a short Desktop turn's usage span can
+// arrive before the prompt log that names its conversation.
+func TestCodexSurfacesHoldAConversationUntilItIsNamed(t *testing.T) {
+ surfaces := &CodexSurfaces{}
+ converter := NewConverter(Options{CodexSurfaces: surfaces})
+ now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+
+ early := converter.EventFromSpan(appServer(), codexTurnSpan("desktop-conv"))
+ if ready := surfaces.Sort([]Event{early}, now); len(ready) != 0 {
+ t.Fatalf("span for an unnamed conversation written at once: %+v", ready)
+ }
+
+ prompt := converter.EventFromLog(appServer(), codexLog("codex.user_prompt", "desktop-conv", "Codex_Desktop"))
+ ready := surfaces.Sort([]Event{prompt}, now.Add(2*time.Second))
+ if len(ready) != 2 || ready[0].Event.Action != "prompt.submitted" || ready[1].Event.Action != "token.usage" {
+ t.Fatalf("ready = %+v, want the prompt then the held span", ready)
+ }
+ for _, event := range ready {
+ if event.Harness.Name != "codex_desktop" || event.codexConversation != "" {
+ t.Fatalf("%s = %q (held for %q), want codex_desktop", event.Event.Action, event.Harness.Name, event.codexConversation)
+ }
+ }
+
+ // Once named, a conversation's later spans go straight out.
+ later := converter.EventFromSpan(appServer(), codexTurnSpan("desktop-conv"))
+ if ready := surfaces.Sort([]Event{later}, now.Add(3*time.Second)); len(ready) != 1 || ready[0].Harness.Name != "codex_desktop" {
+ t.Fatalf("span for a named conversation = %+v, want it written as codex_desktop", ready)
+ }
+}
+
+func TestCodexSurfacesReleaseAnUnnamedConversationAfterTheWait(t *testing.T) {
+ surfaces := &CodexSurfaces{}
+ converter := NewConverter(Options{CodexSurfaces: surfaces})
+ now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+
+ surfaces.Sort([]Event{converter.EventFromSpan(appServer(), codexTurnSpan("logs-never-came"))}, now)
+ if ready := surfaces.Sort(nil, now.Add(codexHoldWindow-time.Millisecond)); len(ready) != 0 {
+ t.Fatalf("released before the wait ran out: %+v", ready)
+ }
+ ready := surfaces.Sort(nil, now.Add(codexHoldWindow))
+ if len(ready) != 1 || ready[0].Harness.Name != "codex_cli" {
+ t.Fatalf("after the wait = %+v, want the span as codex_cli", ready)
+ }
+
+ // A record with no conversation can never be named, so it is not held.
+ debug := converter.EventFromLog(appServer(), codexLog("codex.startup", "", ""))
+ if ready := surfaces.Sort([]Event{debug}, now); len(ready) != 1 {
+ t.Fatalf("record without a conversation held: %+v", ready)
+ }
+}
+
+func TestCodexSurfacesDrainOnShutdown(t *testing.T) {
+ surfaces := &CodexSurfaces{}
+ converter := NewConverter(Options{CodexSurfaces: surfaces})
+ now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+ surfaces.Sort([]Event{
+ converter.EventFromSpan(appServer(), codexTurnSpan("unnamed")),
+ converter.EventFromSpan(appServer(), codexTurnSpan("named-late")),
+ }, now)
+ surfaces.remember("named-late", codexDesktopHarness)
+
+ drained := surfaces.Drain()
+ if len(drained) != 2 || drained[0].Harness.Name != "codex_cli" || drained[1].Harness.Name != "codex_desktop" {
+ t.Fatalf("drained = %+v, want unnamed as codex_cli and named-late as codex_desktop", drained)
+ }
+ if again := surfaces.Drain(); len(again) != 0 {
+ t.Fatalf("second drain = %+v, want nothing", again)
+ }
+}
+
+func TestCodexSurfacesBoundWhatTheyHold(t *testing.T) {
+ surfaces := &CodexSurfaces{}
+ converter := NewConverter(Options{CodexSurfaces: surfaces})
+ now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+ var released []Event
+ for i := 0; i <= maxHeldCodexEvents; i++ {
+ released = append(released, surfaces.Sort([]Event{converter.EventFromSpan(appServer(), codexTurnSpan(fmt.Sprintf("conv-%d", i)))}, now)...)
+ }
+ if len(released) != 1 || released[0].Session.ID != "conv-0" {
+ t.Fatalf("released = %+v, want only the oldest", released)
+ }
+ surfaces.mu.Lock()
+ defer surfaces.mu.Unlock()
+ if len(surfaces.held) != maxHeldCodexEvents {
+ t.Fatalf("holding %d, want %d", len(surfaces.held), maxHeldCodexEvents)
+ }
+}
+
+func TestCodexSortWithoutMemoryPassesEverythingThrough(t *testing.T) {
+ var surfaces *CodexSurfaces
+ events := []Event{Converter{}.EventFromSpan(appServer(), codexTurnSpan("c"))}
+ if ready := surfaces.Sort(events, time.Now()); len(ready) != 1 {
+ t.Fatalf("nil memory held a record: %+v", ready)
+ }
+ if drained := surfaces.Drain(); drained != nil {
+ t.Fatalf("nil memory drained %+v", drained)
+ }
+}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index e040b066..b2c6db7f 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -92,6 +92,9 @@ type Options struct {
// CaptureModelContext keeps what Beacon records from Claude Code's API bodies. Off, every body
// event is dropped; see takeClaudeAPIBody.
CaptureModelContext bool
+ // CodexSurfaces remembers which Codex surface (CLI or desktop app) each conversation runs in,
+ // for records that don't say (see codex_surface.go). Nil places each record on its own.
+ CodexSurfaces *CodexSurfaces
}
type Converter struct {
@@ -368,6 +371,7 @@ func (c Converter) eventFromLog(resourceAttrs map[string]interface{}, record plo
// Last, so it sees the action and category the normalizers settled on rather
// than the ones InferAction guessed.
c.PromoteRetainedContent(&event, attrs, body)
+ c.opts.CodexSurfaces.settle(&event, attrs)
return event, !isAPIBody || kept.webFetch.text != "", c.claudeMCPToolListings(attrs, record, kept.mcpTools)
}
@@ -413,6 +417,7 @@ func (c Converter) EventFromSpan(resourceAttrs map[string]interface{}, span ptra
}
event.Raw = c.RawPayload(attrs, rawExtra)
c.PromoteRetainedContent(&event, attrs, span.Name())
+ c.opts.CodexSurfaces.settle(&event, attrs)
return event
}
@@ -899,6 +904,7 @@ func (c Converter) EventFromMetric(resourceAttrs map[string]interface{}, metric
"metric_description": metric.Description(),
"metric_unit": metric.Unit(),
})
+ c.opts.CodexSurfaces.settle(&event, attrs)
return event
}
@@ -1132,6 +1138,7 @@ func (c Converter) usageEventFromDataPoint(resourceAttrs map[string]interface{},
rawExtra[k] = v
}
event.Raw = c.RawPayload(attrs, rawExtra)
+ c.opts.CodexSurfaces.settle(&event, attrs)
return event
}
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
index a6ec020f..a3c5ab68 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/event.go
@@ -109,6 +109,10 @@ type Event struct {
Message string `json:"message,omitempty"`
Raw map[string]interface{} `json:"raw,omitempty"`
Truncated bool `json:"field_truncated,omitempty"`
+
+ // codexConversation is set on a Codex app-server record whose conversation no originator
+ // has named yet; CodexSurfaces.Sort holds it until one does. It is never written.
+ codexConversation string
}
func NewEvent(action, category, severity, harnessName string, ts time.Time) Event {
diff --git a/docs/runtimes/codex-cli.mdx b/docs/runtimes/codex-cli.mdx
index 4d55194f..bb340fd9 100644
--- a/docs/runtimes/codex-cli.mdx
+++ b/docs/runtimes/codex-cli.mdx
@@ -5,14 +5,14 @@ description: "Beacon support details for Codex CLI and Codex Desktop endpoint te
## Runtime overview
-Beacon supports Codex CLI runtime telemetry through local OTLP logs and one selective usage-bearing turn trace. Codex Desktop uses the same Codex OTLP configuration path through its app-server process, and Beacon records it as `codex_desktop` instead of merging it with `codex_cli`. A lightweight SessionStart hook records the local OS user for CLI token attribution, and a Stop hook records each turn's final assistant reply, which Codex's OTLP export does not carry.
+Beacon supports Codex CLI runtime telemetry through local OTLP logs and one selective usage-bearing turn trace. Codex Desktop uses the same Codex OTLP configuration, and Beacon records its sessions as `codex_desktop` and keeps them apart from `codex_cli`. A lightweight SessionStart hook records the local OS user for CLI token attribution, and a Stop hook records each turn's final assistant reply, which Codex's OTLP export does not carry.
## Prerequisites
Before enabling Codex telemetry, make sure:
- Codex CLI is installed and available as the `codex` executable for the user or managed endpoint.
-- Codex Desktop is installed if you want Desktop app-server telemetry.
+- Codex Desktop is installed if you want Desktop telemetry.
- Codex CLI 0.149.1 or newer is used for verified turn-trace token attribution.
- `beacon endpoint install` has run so the local collector, endpoint config, and runtime log path exist.
- The install includes the `codex` harness, either through the default harness list or an explicit `--harness codex` value.
@@ -20,10 +20,14 @@ Before enabling Codex telemetry, make sure:
## Collection path
-Codex CLI exports local OpenTelemetry logs and traces to Beacon's localhost collector. Codex Desktop exports the same Codex semantic telemetry from `codex-app-server` when user-level `~/.codex/config.toml` enables OTLP. Beacon uses Codex semantic logs for session, prompt, approval, and tool-result events. For tokens it keeps only the completed `session_task.turn` span carrying `thread.id`, `turn.id`, model, and usage; hundreds of transport and internal spans remain suppressed. The CLI SessionStart hook writes a metadata-only `session.context` event. The CLI Stop hook writes the turn's final reply from the payload's `last_assistant_message` as an `agent.message` event, and nothing for a turn that ended without one. Neither hook reads the transcript. Inventory is written by the scheduled inventory job, not by this hook.
+Codex CLI exports local OpenTelemetry logs and traces to Beacon's localhost collector. Codex Desktop exports the same Codex semantic telemetry when user-level `~/.codex/config.toml` enables OTLP. Beacon uses Codex semantic logs for session, prompt, approval, and tool-result events. For tokens it keeps only the completed `session_task.turn` span carrying `thread.id`, `turn.id`, model, and usage; hundreds of transport and internal spans remain suppressed. The CLI SessionStart hook writes a metadata-only `session.context` event. The CLI Stop hook writes the turn's final reply from the payload's `last_assistant_message` as an `agent.message` event, and nothing for a turn that ended without one. Neither hook reads the transcript. Inventory is written by the scheduled inventory job, not by this hook.
Use `--include-codex-spans` during install or repair only when you need every raw Codex span for troubleshooting. It is not required for token attribution.
+### Codex CLI or Desktop
+
+Codex CLI 0.158 and newer run on the same app-server as the desktop app, so both report the service name `codex-app-server`, and that name alone does not say which one a session ran in. Beacon goes by the `originator` attribute on Codex's log events instead: `Codex_Desktop` is recorded as `codex_desktop`, and `codex-tui` (the terminal), `codex_exec` (`codex exec`) and any other value as `codex_cli`. The usage span carries no originator, so it takes the surface its conversation's logs named; if it reaches the collector before those logs, Beacon waits up to ten seconds for them before writing it. A record that names neither, such as Codex's legacy token metric (which has no conversation id) or a usage span from a conversation whose logs never arrived, is recorded as `codex_cli`. Token reports still drop usage a Desktop session reports twice, through a turn span and a legacy metric or through live capture and `codex sync`. Events already in the log keep the name they were written with, so CLI 0.158+ sessions recorded before Beacon v1.3.48 still show as `codex_desktop`.
+
### Session-file recovery
Beacon can also recover Codex CLI activity from Codex's local rollout files with an explicit command:
@@ -85,7 +89,7 @@ Beacon can also capture Codex telemetry in CI with `beacon ci start` and `beacon
## Discovery and status
-Beacon detects Codex CLI through the `codex` executable and `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`). Codex Desktop shares the same user-level configuration file, so Desktop app-server events appear once the app emits OTLP to Beacon's local collector. Use `beacon endpoint discover` or `beacon endpoint status` to confirm that Codex configuration is present.
+Beacon detects Codex CLI through the `codex` executable and `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`). Codex Desktop shares the same user-level configuration file, so Desktop events appear once the app emits OTLP to Beacon's local collector. Use `beacon endpoint discover` or `beacon endpoint status` to confirm that Codex configuration is present.
## Install or configuration support
diff --git a/pkg/asymptoteobserve/harness.go b/pkg/asymptoteobserve/harness.go
index 2ec811d3..6005780c 100644
--- a/pkg/asymptoteobserve/harness.go
+++ b/pkg/asymptoteobserve/harness.go
@@ -46,12 +46,12 @@ func NormalizeHarnessName(name string) string {
return "openclaw_gateway"
case strings.Contains(lower, "antigravity") || strings.Contains(lower, "anti-gravity"):
return "antigravity_cli"
- // Codex Desktop runs the Codex app-server, which exports OTLP with
- // service.name=codex-app-server. Keep it separate from the terminal Codex CLI so dashboards
- // and SIEM queries do not merge two local surfaces under one harness.name.
- case lower == "codex_desktop" || lower == "codex-desktop" || lower == "codex desktop" ||
- lower == "codex_app_server" || lower == "codex-app-server" || lower == "codex app server" ||
- lower == "codex_appserver" || lower == "codex-appserver" || lower == "codex appserver":
+ // codex-app-server is not a Desktop name. The desktop app and, since about CLI 0.158, the terminal
+ // CLI both run Codex's app-server and export OTLP under that one service name, so it falls
+ // through to codex_cli here. The collector exporter tells the two apart by the `originator`
+ // Codex reports on each conversation (beaconevent.CodexSurfaces) and names Desktop sessions
+ // codex_desktop there.
+ case lower == "codex_desktop" || lower == "codex-desktop" || lower == "codex desktop":
return "codex_desktop"
case strings.Contains(lower, "codex"):
return "codex_cli"
diff --git a/pkg/asymptoteobserve/harness_test.go b/pkg/asymptoteobserve/harness_test.go
index 76f63f17..46839728 100644
--- a/pkg/asymptoteobserve/harness_test.go
+++ b/pkg/asymptoteobserve/harness_test.go
@@ -10,10 +10,12 @@ import "testing"
// produces; the closed-set cases list each member.
func TestHarnessSpellingsConvergeOnCanonicalNames(t *testing.T) {
for want, spellings := range map[string][]string{
- "claude_code": {"claude", "claude-code"},
- "claude_web": {"claude.ai", "claude_web"}, // ordered before the generic claude rule
- "codex_cli": {"codex", "codex-cli", "codex_exec", "codex_cli_rs"},
- "codex_desktop": {"codex-app-server", "codex_app_server", "Codex App Server", "codex-desktop", "Codex Desktop"},
+ "claude_code": {"claude", "claude-code"},
+ "claude_web": {"claude.ai", "claude_web"}, // ordered before the generic claude rule
+ // The app-server service name is shared by the CLI and the desktop app, so on its own it
+ // says codex_cli; the exporter names Desktop conversations by their originator.
+ "codex_cli": {"codex", "codex-cli", "codex_exec", "codex_cli_rs", "codex-app-server", "codex_app_server", "Codex App Server"},
+ "codex_desktop": {"codex-desktop", "Codex Desktop", "codex_desktop"},
"gemini_cli": {"gemini"},
"antigravity_cli": {"antigravity"},
// VS Code resolves before the generic copilot rule; "copilot" contains "pi", so Pi must not