Troubleshooting & diagnostics

Start with Orek’s built-in diagnostics. For longer-term monitoring, you can also send traces and metrics to your own observability backend through OpenTelemetry (OTLP). Nothing is sent until you set observe.otlp_endpoint.

Common diagnostics

To inspect	Use
Setup, provider, index, and execution health	`/doctor` in Orek or `orek doctor` in your shell
Recent application logs and log file location	`/log` or `/log --path` in Orek, or `orek log` in your shell
Latest routing decision and failed tool output	`/routing` and `/detail`
Session token usage, cost estimates, and current context	`/usage` (`*` marks incomplete cost coverage; `--` means no saved cost; see Prompt-length pricing) and `/context`
What a model switch did with earlier reasoning	The routing line, `/context`, `/usage` by segment, and the session’s saved switch and request records
Saved conversations and tool activity	Manage sessions
Turn timing, provider and tool spans, and metrics over time	An OTLP backend (`observe.otlp_endpoint`)

Check health and logs

Run /doctor first when setup, a provider, the index, or execution is unhealthy. Use /log to inspect recent application events and /log --path when you need the file location. The equivalent shell commands are orek doctor and orek log.

For provider connection failures, run orek providers check in your shell. For an incompatible or unavailable index, follow Find and explore code. For configuration locations and precedence, see Configuration.

Inspect a turn

Use /routing to see the latest model-selection decision and /detail to open the latest tool result, including failed output. /context [show|raw|summary|breakdown] shows what reaches the model, and /usage shows token and cost estimates.

Collect support details

Use /support for the contact link and /feedback for an explicit local feedback preview. In your shell, orek bug-report previews metadata and any pending minimal crash envelope; --include-log adds a redacted log and --output report.json saves the same preview locally. Nothing is uploaded. Share it yourself at Contact support with the report ID, installation method, reproduction steps and expected result.

Complete inputs up to 1 MiB are redacted before their last 32 KiB is selected; oversized, unreadable and invalid UTF-8 inputs are omitted. Review the result for private project information. A panic writes only a local metadata envelope, with no networking or panic payload capture. The next launch offers a preview, and orek bug-report --clear-crash discards it. See Reporting issues.

Advanced: OpenTelemetry export

Send traces and metrics to your existing observability backend. Orek exports traces and metrics, not application logs.

Before you begin

You need a collector or backend that accepts OTLP over gRPC for traces and metrics. Obtain its endpoint and required authentication headers from your backend’s instructions.

Keep authentication in your secret manager or process environment. Do not put telemetry keys in project configuration or source control.

Configure OTLP export

Set the gRPC endpoint in your user configuration (observe.otlp_endpoint defaults to user scope):

In your shell

orek config set observe.otlp_endpoint "http://127.0.0.1:4317"

Or add it to your user config.toml:

Configuration

[observe]
otlp_endpoint = "http://127.0.0.1:4317"

Use the receiver’s gRPC endpoint, not an OTLP/HTTP /v1/traces path or HTTP port 4318. https:// and schemeless endpoints (such as collector.internal:4317) use TLS; write http:// explicitly for a plaintext collector.

Setting	Purpose
`observe.otlp_endpoint`	Enable export to this destination for `orek` (`orek chat`) and `orek run`; unset by default.
`OTEL_EXPORTER_OTLP_HEADERS`	Supply authentication using the SDK’s comma-separated `name=value` format.
`OTEL_EXPORTER_OTLP_INSECURE`	Set to `true` to connect to a schemeless endpoint without TLS (or set `OTEL_EXPORTER_OTLP_TRACES_INSECURE` / `OTEL_EXPORTER_OTLP_METRICS_INSECURE` per signal); defaults to `false`.
`OTEL_SERVICE_NAME`	Set the service name used in backend searches; defaults to `orek-cli`.
`OREK_DEPLOY_ENV`	Set the `deployment.environment` attribute on exported telemetry; defaults to `local`.

Optionally choose a recognizable service name. For example, in PowerShell:

In your shell

$env:OTEL_SERVICE_NAME = "orek-ai"
orek chat

Restart Orek after changing export configuration.

Choose your backend

You can use Honeycomb, Grafana, or another compatible destination. Configure Orek with the receiving endpoint and credentials; use the backend’s instructions for account setup and dashboards.

Honeycomb’s OpenTelemetry guidance describes its regional gRPC endpoints and authentication headers.
Grafana’s OTLP guidance describes its connection details. A local OpenTelemetry Collector or Grafana Alloy gRPC receiver can forward Orek’s telemetry to the stack.

If your destination accepts only OTLP/HTTP, send Orek telemetry to an OpenTelemetry Collector with a gRPC receiver. Configure the collector to forward traces and metrics using the destination’s protocol and credentials.

Verify a turn

Start Orek with the configured environment and complete a short turn.
In the backend, filter by service.name and a recent time window.
Find a turn span such as agent_turn, then inspect its provider and tool spans.
Check metric ingestion in your backend as well.

Subagent spans appear under the turn that started them. Use session_id to find turns from the same session.

Troubleshooting export

Symptom	What to check
No export starts	Inspect `orek config get observe.otlp_endpoint` and restart Orek.
Connection or protocol error	Confirm the receiver accepts gRPC at the configured host and port.
TLS handshake error on a local collector	Write the endpoint with `http://`; a schemeless endpoint uses HTTPS.
Authentication error	Check the receiver’s required headers in Orek’s process environment.
Traces arrive but metrics do not	Check metric ingestion and the collector’s metric pipeline separately.
Nothing appears in the backend	Check its service filter, time window, receiver, and outgoing pipeline.

Setting OTEL_EXPORTER_OTLP_ENDPOINT alone does not enable export; Orek reads observe.otlp_endpoint. Orek always exports over gRPC, so OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf does not switch it to HTTP.

A failed export retries briefly, for up to 2 seconds, then Orek reports the failure in the TUI or application log. Your turn continues either way.

What OTLP telemetry includes

Exported spans and metrics include provider and model names, tool outcomes, token counts, retrieval counts, and timing. They omit prompts, tool arguments and outputs, approval previews, raw file paths, and provider error text.

Saved session files can contain conversation and tool content; they stay on your machine and are never part of OTLP telemetry.

Model switches and provider requests

Each model switch starts a new segment: the run of requests to one model. Each provider request records what it did with earlier reasoning under the reasoning replay setting. Exported turn spans carry these events:

Event	When it appears
`model_segment_started`	A new model segment begins.
`provider_request_recorded`	The turn sends a request, including retries and fallbacks.
`signed_replay_retired`	Claude’s earlier thinking stops being resent. It names the cause, such as `tool_set_change` or `model_switch`, and the number of thinking blocks.

Check the actual decision lists the fields of the first two. They leave out error text and token usage; usage is on the provider call events. Requests that write a compaction summary send no events, so exported requests always report request.purpose as main_turn; only the saved session records summary requests, including the cause when one stops resending Claude’s earlier thinking.

The saved session keeps a record of each model switch and of each request in the main conversation, compaction summaries included: its usage, cost, latency, any error, and any earlier thinking that Anthropic reported skipping. The TUI, orek run, and editor sessions save these records, and orek session export includes them. A forked session keeps the switch records but starts with no request records or usage.

Disable remote export

Remove the endpoint from both project and user configuration, then check the value Orek uses:

In your shell

orek config unset observe.otlp_endpoint --scope project
orek config unset observe.otlp_endpoint --scope user
orek config get observe.otlp_endpoint

Confirm that no endpoint remains, then restart running Orek processes. Removing only a project value can expose a user-scope value.

See the Configuration reference for all [observe] settings and environment variables.