`cxas trace`¶

cxas trace is the observability and debugging surface for past conversations. It composes the Conversational Agents API, Cloud Logging, GCS, and Gemini into a single, scriptable workflow so you can debug a flaky live conversation, audit an eval failure, replay a conversation against the current agent, or flag a platform bug — all from your terminal.

All cxas trace subcommands share a few flags:

Flag	Required	Description
`--app-name`	yes	Full CXAS App ID (`projects/.../locations/.../apps/...`).
`--app-dir`	no	Path to the pulled app directory. Defaults to `.`. Used to read `app.json` (audio bucket, Cloud Logging enablement, model version) and `environment.json`.
`--env-file`	no	Explicit path to an `environment.json` file (mirrors the existing `cxas push --env-file` flag).
`--environment`	no	Named environment, resolved to `<app-dir>/environment.<name>.json`.
`--config`	no	Path to a trace config YAML. Defaults to `./.cxas/trace.yaml`, then `~/.cxas/trace.yaml`, then built-in defaults.

Subcommands¶

Subcommand	Purpose
`cxas trace list`	List conversations filtered by time / source / channel.
`cxas trace get <id>`	Fetch a conversation and render a trace report (JSON / Markdown / text / HTML).
`cxas trace logs <id>`	Fetch Cloud Logging entries correlated to a conversation.
`cxas trace audio download <id>`	Download the GCS audio recording.
`cxas trace audio analyze <id>`	Run configured Gemini audio metrics over the recording.
`cxas trace triage <id>`	Run text-only Gemini triage prompts over the transcript.
`cxas trace replay <id>`	Replay user inputs against the current agent and diff.
`cxas trace stats`	Aggregate stats over recent conversations.
`cxas trace bundle <id>`	Zip transcript + logs + audio + report into a single archive.
`cxas trace bug-report <id>`	Flag a conversation as a platform bug; uploads bundle to a configured GCS bucket.
`cxas trace open <id>`	Print (and on macOS, open) the CES Console deep link.

Examples¶

List the 10 most recent audio conversations from the last day:

cxas trace list \
  --app-name projects/p/locations/l/apps/a \
  --time-filter 24h --channel AUDIO --limit 10

Build a Markdown trace report with merged Cloud Logs, downloaded audio, and Gemini audio + transcript analysis — written to a file:

cxas trace get conv-id-1 \
  --app-name projects/p/locations/l/apps/a \
  --format md --with-logs --with-audio --with-analysis --with-triage \
  --out trace.md

Compare a deployed conversation against the current agent:

cxas trace replay conv-id-1 --app-name projects/p/locations/l/apps/a --diff

Generate a 7-day stats report grouped by source, written as Markdown:

cxas trace stats --time-filter 7d --source LIVE \
  --app-name projects/p/locations/l/apps/a --out stats.md

Flag a conversation as a platform bug with reason and severity:

cxas trace bug-report conv-id-1 \
  --app-name projects/p/locations/l/apps/a \
  --reason "agent hallucinated the refund amount" --severity high

Configuration: `./.cxas/trace.yaml`¶

cxas trace is fully configurable. Drop a trace.yaml next to your agent in ./.cxas/trace.yaml (or globally at ~/.cxas/trace.yaml) to override prompts, log filters, audio behavior, and the bug-report destination. Every field has a sensible default, so the file is optional.

audio:
  bucket_override: null            # leave null to use app.json's gcsBucket
  uri_pattern: "{bucket}/{conversation_id}.wav"
  download_dir: ./.cxas/audio
  mime_type: audio/wav

cloud_logging:
  default_level: WARNING
  time_padding_seconds: 30
  filter_template: |
    severity >= "{level}"
    AND timestamp >= "{start_time}" AND timestamp <= "{end_time}"
    AND (jsonPayload.conversation_id="{conversation_id}"
         OR labels.conversation_id="{conversation_id}")

gemini:
  model: gemini-2.5-flash
  # Audio analyses come from `cxas_scrapi.utils.audio_analysis.ANALYSIS_REGISTRY`
  # (5 built-ins: agent_voice_consistency, no_long_pauses,
  # agent_having_trouble, agent_looping, agent_cutoff). Each declares which
  # files it needs (e.g. `agent-turn-*.wav` vs `full-session.wav`) and a
  # default prompt. Override a prompt per-project by listing the metric here:
  audio_metrics: {}
  # Example override:
  #   agent_cutoff:
  #     prompt: "Custom cutoff prompt for our agent..."
  triage_metrics:
    hallucination:        { prompt: "..." }
    off_topic:            { prompt: "..." }
    failed_understanding: { prompt: "..." }

ui:
  ces_console_base: https://ces.cloud.google.com
  ccai_insights_base: https://ccai.cloud.google.com/insights

bug_report:
  bucket: gs://cxas-platform-bugs
  path_template: "{model_version}/{date}/{user}/{severity}/{conversation_id}/"
  include: [transcript, logs, audio, gemini_analysis, environment]

App-side discovery¶

cxas trace reads the same app.json and environment.json files that cxas pull writes — no extra setup required. From app.loggingSettings:

audioRecordingConfig.gcsBucket → audio download source
cloudLoggingSettings.enableCloudLogging → gates --with-logs
bigqueryExportSettings → surfaced in metadata (informational)

$env_var placeholders are resolved against the chosen environment.json — the same convention used by cxas push.

cxas trace¶

Subcommands¶

Examples¶

Configuration: ./.cxas/trace.yaml¶

App-side discovery¶

`cxas trace`¶

Configuration: `./.cxas/trace.yaml`¶