mirror of
https://github.com/katanemo/plano.git
synced 2026-04-25 00:36:34 +02:00
743d074184
Some checks are pending
CI / pre-commit (push) Waiting to run
CI / plano-tools-tests (push) Waiting to run
CI / native-smoke-test (push) Waiting to run
CI / docker-build (push) Waiting to run
CI / validate-config (push) Waiting to run
CI / security-scan (push) Blocked by required conditions
CI / test-prompt-gateway (push) Blocked by required conditions
CI / test-model-alias-routing (push) Blocked by required conditions
CI / test-responses-api-with-state (push) Blocked by required conditions
CI / e2e-plano-tests (3.10) (push) Blocked by required conditions
CI / e2e-plano-tests (3.11) (push) Blocked by required conditions
CI / e2e-plano-tests (3.12) (push) Blocked by required conditions
CI / e2e-plano-tests (3.13) (push) Blocked by required conditions
CI / e2e-plano-tests (3.14) (push) Blocked by required conditions
CI / e2e-demo-preference (push) Blocked by required conditions
CI / e2e-demo-currency (push) Blocked by required conditions
Publish docker image (latest) / build-arm64 (push) Waiting to run
Publish docker image (latest) / build-amd64 (push) Waiting to run
Publish docker image (latest) / create-manifest (push) Blocked by required conditions
Build and Deploy Documentation / build (push) Waiting to run
* feat: add initial documentation for Plano Agent Skills * feat: readme with examples * feat: add detailed skills documentation and examples for Plano --------- Co-authored-by: Adil Hafeez <adil.hafeez@gmail.com>
85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
---
|
|
title: Use `planoai trace` to Inspect Routing Decisions
|
|
impact: MEDIUM-HIGH
|
|
impactDescription: The trace CLI lets you verify which model was selected, why, and how long each step took — without setting up a full OTEL backend
|
|
tags: observability, tracing, cli, debugging, routing
|
|
---
|
|
|
|
## Use `planoai trace` to Inspect Routing Decisions
|
|
|
|
`planoai trace` provides a built-in trace viewer backed by an in-memory OTEL collector. Use it to inspect routing decisions, verify preference matching, measure filter latency, and debug failed requests — all from the CLI without configuring Jaeger, Zipkin, or another backend.
|
|
|
|
**Workflow: start collector, run requests, then inspect traces:**
|
|
|
|
```bash
|
|
# 1. Start Plano with the built-in trace collector (recommended)
|
|
planoai up config.yaml --with-tracing
|
|
|
|
# 2. Send test requests through Plano
|
|
curl http://localhost:12000/v1/chat/completions \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"model": "plano.v1", "messages": [{"role": "user", "content": "Write a Python function to sort a list"}]}'
|
|
|
|
# 3. Show the latest trace
|
|
planoai trace
|
|
```
|
|
|
|
You can also run the trace listener directly:
|
|
|
|
```bash
|
|
planoai trace listen # available on a process ID running OTEL collector
|
|
```
|
|
|
|
Stop the background trace listener:
|
|
|
|
```bash
|
|
planoai trace down
|
|
```
|
|
|
|
**Useful trace viewer patterns:**
|
|
|
|
```bash
|
|
# Show latest trace (default target is "last")
|
|
planoai trace
|
|
|
|
# List available trace IDs
|
|
planoai trace --list
|
|
|
|
# Show all traces
|
|
planoai trace any
|
|
|
|
# Show a specific trace (short 8-char or full 32-char ID)
|
|
planoai trace 7f4e9a1c
|
|
planoai trace 7f4e9a1c0d9d4a0bb9bf5a8a7d13f62a
|
|
|
|
# Filter by specific span attributes (AND semantics for repeated --where)
|
|
planoai trace any --where llm.model=gpt-4o-mini
|
|
|
|
# Filter by user ID (if header prefix is x-katanemo-, x-katanemo-user-id maps to user.id)
|
|
planoai trace any --where user.id=user_123
|
|
|
|
# Limit results for a quick sanity check
|
|
planoai trace any --limit 5
|
|
|
|
# Time window filter
|
|
planoai trace any --since 30m
|
|
|
|
# Filter displayed attributes by key pattern
|
|
planoai trace any --filter "http.*"
|
|
|
|
# Output machine-readable JSON
|
|
planoai trace any --json
|
|
```
|
|
|
|
**What to look for in traces:**
|
|
|
|
|
|
| Span name | What it tells you |
|
|
| ------------------- | ------------------------------------------------------------- |
|
|
| `plano.routing` | Which routing preference matched and which model was selected |
|
|
| `plano.filter.<id>` | How long each filter in the chain took |
|
|
| `plano.llm.request` | Time to first token and full response time |
|
|
| `plano.agent.route` | Which agent description matched for agent listeners |
|
|
|
|
|
|
Reference: [https://github.com/katanemo/archgw](https://github.com/katanemo/archgw)
|