Skip to content

The only tool you need to know what is happening and how to fix it.

7.2 KB
Raw Blame

name: traceway description: 'Operate a Traceway observability instance through the traceway CLI: log in, query exceptions, logs, endpoints, and metrics, and debug production issues down to root cause. Use when the user invokes /traceway with a subcommand, e.g. "/traceway login", "/traceway debug issue <hash|url|title>", "/traceway what''s broken in prod", or whenever they want to investigate errors, crashes, slowness, or logs from an app monitored by Traceway.'

Traceway

Drive a Traceway instance from the terminal with the traceway CLI. The first word of the argument decides the flow:

Invocation Flow
/traceway login Login: install the CLI if missing, authenticate, select a project
/traceway debug <issue ref or bug description> Debug: resolve the issue and investigate to root cause
/traceway perf <endpoint or symptom> Performance: diagnose latency/slowness to root cause against a checklist of common bottlenecks
/traceway <anything else> Query: answer the observability question with CLI reads
/traceway (no argument) Ask what they want: log in, debug an issue, or run a query

The CLI is under active development. If a flag documented here does not appear in traceway <command> --help, trust the binary. If a traceway MCP server is connected, prefer its tools over shelling out to the CLI: they wrap the same API with the same semantics, and this skill's knowledge is available as its resources. The server is this same binary (traceway mcp). This skill only reads. To change anything (archive issues, acknowledge or resolve pages, snooze alerts, run monitors, write post-mortems), the user installs the separate traceway-write CLI and the traceway-write skill. When the user asks how a part of Traceway works (schedules, escalation, status pages, alert rules, impact score and the rest), use the traceway-learn skill. It is the full product guide.

{{include "ground-rules.md"}}

{{include "url-resolution.md"}}

{{include "timestamps.md"}}

{{include "notifications.md"}}

Flow: Login

1. Check for an existing install

traceway version

If it prints a version, skip to authentication.

2. Install if missing

On POSIX systems (Linux, macOS), use the install script:

curl -fsSL https://cli.tracewayapp.com/install.sh | sh

If the script cannot be used, install manually: prebuilt binaries are on the tracewayapp/traceway releases page under cli/vX.Y.Z tags (the latest release may be a Backend release, so filter for CLI tags):

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); [ "$ARCH" = "aarch64" ] && ARCH=arm64
URL=$(curl -s "https://api.github.com/repos/tracewayapp/traceway/releases?per_page=20" \
  | grep -o "https://[^\"]*traceway_[^\"]*_${OS}_${ARCH}\.tar\.gz" | head -1)
TMP=$(mktemp -d)
curl -sL "$URL" | tar -xz -C "$TMP"
install -m 755 "$TMP/traceway" ~/.local/bin/traceway && rm -rf "$TMP"

Make sure ~/.local/bin is on PATH (or install to /usr/local/bin). Fallback, build from source (requires Go):

git clone https://github.com/tracewayapp/traceway && cd traceway/cli
go build -o bin/traceway ./cmd/traceway && install -m 755 bin/traceway ~/.local/bin/traceway

Verify with traceway version.

3. Authenticate

Login prompts for the password interactively, so ask the user to run it themselves (in Claude Code, suggest typing ! traceway login --url https://<instance> so the output lands in the session):

traceway login --url https://<traceway-instance>

Non-interactive alternative when the password is in a secret store (never echo a password into the command line or shell history):

printf '%s' "$TRACEWAY_PASSWORD" | traceway login --url https://<instance> --username [email protected] --password-stdin

Multiple instances or accounts coexist via profiles: traceway login --url ... --profile work, then traceway profiles list / traceway profiles use work.

4. Select a project and smoke-check

traceway projects list
traceway projects use <project-id>
traceway exceptions list --since 24h

The selected project is used implicitly by all subsequent commands.

{{include "debug-flow.md"}}

{{include "performance-flow.md"}}

Flow: Query

For free-form requests ("what's broken in prod?", "is /api/checkout slow?", "show errors for service X"), use the read commands directly. A request specifically about latency or slowness routes to the Performance flow above.

Command reference

Command Purpose
traceway projects {list,use} List or select the active project
traceway exceptions list Grouped exceptions; --search, --search-type text|regex, --order-by lastSeen|firstSeen|count, --include-archived
traceway exceptions show <hash> One group: full stack trace + occurrences
traceway exceptions occurrence <id> --recorded-at <t> One occurrence by id (fast): full detail + sessionId + recording
traceway logs query Logs; --search (--search-type body|attribute), --service, --min-severity <n>, --trace-id
traceway endpoints list Per-endpoint p50/p95/p99 and counts; --search, --order-by impact|count|p95|lastSeen
traceway endpoints chart Latency over time for the top endpoints; --metric-type total_time|p50|p95|p99, --interval-minutes. Use to find when latency changed
traceway endpoints slow <endpoint> Whether an operator marked this endpoint slow: {offsetMs, reason}. offsetMs 0 = not marked. The offset is the accepted-latency baseline
traceway endpoints show <id> --recorded-at <t> One request by id: span waterfall + linked errors
traceway tasks show <id> --recorded-at <t> One background task run by id
traceway ai-traces show <id> --recorded-at <t> One AI trace by id + its conversation
traceway sessions show <id> --started-at <t> One session by id + the exceptions that fired in it
traceway traces show <id> --recorded-at <t> Distributed trace: every service node sharing the id
traceway metrics query --name <metric> Time series; --aggregation, --tag, --group-by, --interval-minutes
traceway pages list / pages show <id> On-call pages; --status active|open|acknowledged|resolved
traceway alerts list Alert rules: type, enabled, snoozed until
traceway monitors list / monitors show <id> Uptime monitors, their status and incidents
traceway post-mortems list / post-mortems show <id> Post-mortem documents; --search, --tag
traceway profiles {list,use}, login, logout, version Profile and session management

The by-id show/occurrence commands take their id from a dashboard URL, a notification, or an exceptions show occurrence — and require the record's timestamp (--recorded-at / --started-at); see "Fast by-id lookups" above.

Not implemented yet (do not fabricate flags; point the user at the web UI): list verbs for tasks / sessions / ai-traces / traces (only by-id show exists for those), and metrics list/discover.

{{include "query-recipes.md"}}