Operations and troubleshooting

Start with Sources. It shows the effective endpoint, receiver state, queue utilization, rejected spans, journal/projection lag, lifecycle counts, and analysis pending state.

Open Settings → Collection, enable OTLP, save, and restart Perseval when prompted. Installation never opens a listener by default.

Perseval keeps the GUI open and selects an available loopback port. Copy the effective endpoint from Sources or the status bar. Do not keep a hardcoded 4318 URL in the agent when the UI shows another port.

1. Confirm the receiver says Listening.
2. Confirm the exporter uses OTLP/HTTP, not gRPC.
3. Confirm the path is /v1/traces exactly once.
4. Confirm perseval.project.id matches the selected project.
5. Check rejected-span count and producer response.
6. Clear Runs filters and verify project/environment/build/session scope.

An Error span is not automatically actionable. Open the run in Full Trace, select the error span, and read the Finding inspector. It lists missing behavioral facts. Inspect Attributes, add the telemetry contract, and emit a new run.

Optional failures and verified recovery can correctly produce zero findings.

Emit gen_ai.conversation.id on the resource or root span. Emit gen_ai.agent.id and agent.role on each agent span. Confirm values are bounded scalars and reached the exported OTLP payload.

A revision becomes Quiescent after 30 seconds without committed activity and Finalized after another 5 seconds. Continued or late export resets the idle window. Zero queue lag does not mean analysis is ready.

Inspect the OTLP response. Split requests that exceed size, span-count, or attribute-count limits. Fix malformed trace/span IDs or unsupported content types rather than retrying unchanged permanent input.

Honor Retry-After for 429 and use bounded exponential backoff. Retry the identical batch; canonical deduplication makes successful redelivery a no-op.

The subscriber detected a sequence gap and is taking a bounded snapshot. Keep working unless the state persists. The UI preserves stable selection, invalidates affected pages, and resumes. Restart only after checking Sources and allowing the resync to finish.

Settings displays active environment overrides. PERSEVAL_WORKSPACE_DIR, PERSEVAL_CONFIG, PERSEVAL_OTLP_ENABLED, and PERSEVAL_OTLP_BIND are authoritative over saved values. Quit the app, remove or correct the launch variable, and reopen it.

Perseval does not automatically load a repository .env file.

Use the bundled executable, restart the MCP client, and make its explicit PERSEVAL_WORKSPACE_DIR match the GUI. If the GUI uses the default workspace, remove an old custom override from the MCP configuration.

Check the master opt-in, feature dependencies, and OPENAI_API_KEY in the launch environment. Provider failure never disables deterministic groups. Provider jobs are not yet a durable retry ledger.