Findings Quickstart

Prerequisites#

• A Provon project and API key. See Install Provon or the hosted Workbench.
• A GitHub OAuth app or personal token for repair handoff.

1. Capture A Trace#

Choose one path:

Path A: Provon Gateway#

export PROVON_API_KEY="..."
export PROVON_GATEWAY_URL="https://gateway.provon.dev/v1"

curl "$PROVON_GATEWAY_URL/chat/completions" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-otel-gen-ai-conversation-id: quickstart-conversation-1" \
  -H "x-otel-gen-ai-agent-id: quickstart-agent" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      {"role": "user", "content": "Find the failed deployment and fix it."}
    ]
  }'

Path B: OpenTelemetry#

export PROVON_API_KEY="..."
export PROVON_OTEL_URL="https://otel.provon.dev/v1"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="$PROVON_OTEL_URL/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Run your instrumented agent once. See OpenTelemetry setup for SDK examples.

For the first Finding, it helps if the run includes a tool failure, skipped verification, or unsupported claim. Healthy conversations often produce no Findings.

2. Verify The Trace#

Open Traces in the Workbench and select the new trace. Confirm that:

• gen_ai.conversation.id is stable;
• the root span states the user goal;
• model, tool, and final-answer spans are in causal order;
• a failure or terminal state is visible if you expected one.

See Diagnosis-ready tracing if any of these are missing.

3. Enable Diagnosis#

Open Findings:

1. Open Diagnostic rules and confirm at least one Rule is enabled.
2. Turn on Auto-diagnose.
3. If you already have historical traces, run an enabled Rule against the last 24 hours.

Automatic Runs are queued after a conversation has been inactive for 10 minutes. The UI updates when a Finding is published.

4. Review The Finding#

Expand the new Finding and check:

• Severity matches the impact.
• Diagnostic confidence is high enough to act on.
• Cause assessment points to a failure mechanism, not just a symptom.
• Evidence links to the trace/span that supports the claim.
• Remediation hint gives a narrow repair direction.

If the Finding is not actionable, dismiss it. If it is actionable, confirm it.

5. Hand Off To GitHub#

1. Open Connectors and expand GitHub.
2. Connect with OAuth or paste a token.
3. Set Default owner and Default repo, then enable the connector.
4. Return to Findings, expand the Finding, and select Confirm & create in GitHub.

Provon creates a GitHub Issue with:

• a focused repair goal;
• the Finding summary and cause assessment;
• trace and span evidence links;
• a remediation hint;
• the provon-repair label and hidden correlation metadata.

The Finding becomes Confirmed and tracks the external work item.

6. Verify The Outcome#

After the fix is deployed:

1. Run the same agent task again.
2. If the failure is gone, no new occurrence is published.
3. If a new occurrence appears, the resolved Finding becomes Regressed.

For GitHub, a merged pull request linked to the issue is recorded automatically. For other providers, mark the Finding verified after you confirm the fix.