The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
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.goindex 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 int64cumulative boolmetricName 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.goindex 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 coversdiff --git a/collector-builder/exporter/beaconjsonexporter/codex_surface_e2e_test.go b/collector-builder/exporter/beaconjsonexporter/codex_surface_e2e_test.gonew file mode 100644index 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.goindex 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.Tracesreturn firstErr}-func (e *beaconExporter) consumeMetrics(ctx context.Context, metrics pmetric.Metrics) error {+func (e *beaconExporter) consumeLogs(ctx context.Context, logs plog.Logs) error {_ = ctxvar 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.goindex 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 componenif 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 componif 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 compoif 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.goindex 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.Loggerconverter beaconevent.Converterlistings *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 componenreturn 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 componreturn 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 comporeturn 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 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.mdxindex 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.## PrerequisitesBefore 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 recoveryBeacon 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 supportdiff --git a/pkg/asymptoteobserve/harness.go b/pkg/asymptoteobserve/harness.goindex 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.goindex 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