Skip to content
Skills Library
DevOps & cloud · Tool integration

export-trace

/export-trace

Use for "get this trace", "show every request in this trace", "export these trace IDs", or "download this workload's captures for a day". Resolves explicit traces or a bounded workload window through customer APIs, exports captures privately, and hands local files to the trace viewer or ingest-traces.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use for "get this trace", "show every request in this trace", "export these trace IDs", or "download this workload's captures for a day". Resolves explicit traces or a bounded workload window through customer APIs, exports captures privately, and hands local files to the trace viewer or ingest-traces.

Triggers from the description

get this traceshow every request in this traceexport these trace IDsdownload this workload
Original author description

Use for "get this trace", "show every request in this trace", "export these trace IDs", or "download this workload's captures for a day". Resolves explicit traces or a bounded workload window through customer APIs, exports captures privately, and hands local files to the trace viewer or ingest-traces.

How it works

  1. Safety Gates
  2. Resolve CLI
  3. Explicit trace flow
  4. Workload day flow
  5. Failure Handling
  6. Output Standard
Original SKILL.md headings · 119 lines, 604 words
SKILL.md preview
---
name: export-trace
description: Use for "get this trace", "show every request in this trace", "export these trace IDs", or "download this workload's captures for a day". Resolves explicit traces or a bounded workload window through customer APIs, exports captures privately, and hands local files to the trace viewer or ingest-traces.
metadata:
  understudy:
    mode: interactive
    safety: auth-gated
    cli_required: true
---

# Export Trace

Retrieve one explicit hosted trace without scanning the capture catalog. Resolve
its request IDs through the customer trace lookup endpoint, then reuse the
bounded request capture exporter.

For a named workload day rather than explicit trace IDs, use the workload
flow below. For a before/after task comparison, use
[`../ramp-and-verify/references/review-rollout.md`](../ramp-and-verify/references/review-rollout.md).

## Safety Gates

- Treat a bare `trace_id` as authorization for a redacted local summary export,
  not for raw prompts or completions.
- Use `--include-payload --yes` only when the developer explicitly asks for the
  full, raw, or complete trace/captures. Announce that the files may contain
  prompts, completions, and tool payloads before running it.
- Keep outputs under `.understudy/`; never print, paste, commit, or upload trace
  bodies.
- Never ask for API keys in chat. Use existing Understudy credentials and report
  only auth presence or errors.
- Never replace the trace lookup with project-wide capture pagination. If the
  lookup endpoint is unavailable, stop and report the backend dependency.

## Resolve CLI

Prefer the installed `orchestra` binary. In this repository checkout:

```sh
npm run build
node dist/bin.js status --json
```

Use `node dist/bin.js` in place of `understudy` below when necessary.

## Explicit trace flow

1. Resolve the project from repo config or an explicit `--project` /
   `--project-id`. Resolve `--workload` only when the developer supplied or
   requested that narrower scope.
2. For redacted metadata, run:

   ```sh
   orchestra traces export <trace-id> \
     --project <project> \
     --out .understudy/traces/<trace-id>
   ```

3. For an explicitly requested full trace, run:

   ```sh
   orchestra traces export <trace-id> \
     --project <project> \
     --out .understudy/traces/<trace-id> \
     --include-payload --yes
   ```

   For several explicit IDs, put one per line in a private local file and use
   `--trace-ids-file <path>`. Do not use or recreate an unbounded `--all`
   operation.
4. Inspect only metadata artifacts:

   - `trace.json` — `trace_id`, ordered `request_ids`, and export counts;
   - `failed-request-ids.txt` — request captures to retry;
   - `failed-trace-ids.txt` — trace lookups or trace exports to retry;
   - `*.summary.json` or `*.payload.json` — private per-request files.

   Do not print payload file contents. Rerun the same command to resume; completed
   request files are skipped.
5. When the developer asks to inspect the conversation locally, build the
   private viewer:

   ```sh
   orchestra traces build-viewer \
     --source .understudy/traces/<trace-id> \
     --trace-id <trace-id> \
     --output .understudy/trace-viewer/<trace-id>
   ```

6. When the developer wants an eval, cost profile, or benchmark from the local
   files, hand off to [`../ingest-traces/SKILL.md`](../ingest-traces/SKILL.md).

## Workload day flow

Resolve one exact organization/project/workload. With authorization for full
payloads, export a completed UTC calendar day:

```sh
orchestra traces export --org <org-id> --project-id <project-id> \
  --workload <name-or-id> --date <YYYY-MM-DD> \
  --out .understudy/traces/<run> --include-payload --yes
```

`--last 1d` instead selects the last 24 hours. Inspect `source/summary.json`
and `source/skipped.jsonl`: any skipped capture means some indexed captures
were not materialized. Local hashes prove the saved bytes, not uncaptured
traffic coverage. Never silently present a skipped export as complete.
For arbitrary paired windows and verified request accounting, use the rollout
review flow linked above rather than hand-merging independent day exports.

## Failure Handling

- `404` for one trace: report that the trace is absent from the authorized
  project/workload or that the platform trace lookup has not deployed. Do not
  scan capture history as a fallback.
- `401`/`403`: stop and route auth/project readiness to
  [`../use-understudy-gateway/SKILL.md`](../use-understudy-gateway/SKILL.md).
- A non-empty `failed-request-ids.txt`: report a partial export and rerun the
  same command; do not claim the trace is complete.
- A response with no request IDs or a mismatched `trace_id`: fail closed and
  report the contract violation.

## Output Standard

End with the trace ID, project/workload scope, redacted or full mode, request
count, complete/partial status, private output directory, and one next action:
open the local viewer, retry failures, or route to `ingest-traces`.
Files in this package (2)
  • SKILL.md 5 KB
  • agents/openai.yaml 1 KB

Versions

The database has no other skills named export-trace.

Database snapshot: 13.11.2026 · package version b1b3454ae1bc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100arize-traces
    Retrieve and debug trace data from the Arize ML observability platform. Use when users want to list recent traces, look up a specific trace by trace ID, get all spans within a trace, analyze trace performance (latency, tokens, cost), or export trace data. Triggers on "list…
  • 90linking-errors-to-traces
    Links a PostHog error occurrence or session's errors to OpenTelemetry traces, logs with the same trace ID, and Session Replay. Use when the user asks for trace or span IDs on an error, same-trace logs, or backend traces for errors in a session. Starts from an occurrence UUID,…
  • 100arize-trace
    Downloads, exports, and inspects existing Arize traces and spans to understand what an LLM app is doing or debug runtime issues. Covers exporting traces by ID, spans by ID, sessions by ID, and root-cause investigation using the ax CLI. Use when the user wants to look at existing…
  • 100ingest-traces
    Use when a developer already has production LLM traces — a bucket of captures, provider log exports, or gateway capture files — and wants them visualized, turned into local redacted eval sets, or profiled for cost. "Visualize this trace", "ingest my traces", "turn these logs…
  • 90trace-review
    Build or adapt a project-owned UI app for reviewing agent traces, with full interactions, keyboard navigation, search, filters and persistent human feedback ("build a trace viewer", "let me label traces by hand", "a review app for these runs"). Use when the user wants a trace…
  • 100trace-review-app
    Design and build a custom trace review app for one AI product: a single-page tool where the team reads traces, writes notes, labels pass or fail, tags trace codes and exports the results for other skills. Built around that product's own trace shape, rubric and failure modes, and…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.