# Workflow Trace Tab Requirements

## Goal
Deliver end-to-end OpenTelemetry-based tracing for Orcheo workflow executions and surface the traces in a dedicated "Trace" tab alongside existing Canvas workflow tabs.

## Scope
- Instrument backend workflow execution engine to emit OpenTelemetry traces for each workflow run and its constituent node steps.
- Persist trace identifiers and metadata required to retrieve trace data for completed or in-progress runs.
- Expose backend APIs that return trace structures suitable for UI consumption.
- Extend Canvas application to add a "Trace" tab that visualizes the trace tree, token metrics, and downloadable artifacts for the selected execution.
- Provide documentation for configuration, including integration with external collectors and dashboards.

## Non-Goals
- Implement advanced analytics beyond trace visualization (e.g., anomaly detection, SLA alerting).
- Replace existing execution log views or remove current monitoring dashboards.
- Add vendor-specific tracing exporters beyond OpenTelemetry standard exporters/collectors.

## Functional Requirements
1. **Trace Generation**: Each workflow execution must produce a root trace span with child spans for each node execution, including status, duration, token usage, and emitted artifacts.
2. **Trace Persistence**: Trace identifiers and relevant metadata must be stored in the run history to support retrieval and UI navigation for current and historical runs.
3. **Trace Retrieval API**: Provide REST endpoints that accept an execution identifier and return the trace hierarchy, token metrics, artifacts metadata, and links to external dashboards where applicable.
4. **Canvas Trace Tab**: The Canvas UI must render a "Trace" tab adjacent to "Execution," showing a hierarchical trace view with per-step details and download links for artifacts.
5. **Real-Time Updates**: For in-progress runs, the Trace tab should update when new spans complete or metrics change, leveraging existing WebSocket or polling mechanisms.
6. **Configuration & Docs**: Document how to configure OpenTelemetry exporters, backends, and UI usage, including environment variables and deployment-specific considerations.

## Quality & Compliance Requirements
- Maintain existing CI checks (linting, tests) with coverage for new backend and frontend code.
- Ensure trace data respects existing security and privacy constraints (e.g., secret masking, PII handling).
- Provide automated tests for trace emission, persistence, API serialization, and UI rendering.
- Ensure UI remains accessible (keyboard navigation, ARIA attributes) and performant when displaying traces with many spans.

## Success Metrics
- 100% of workflow executions emit trace data accessible via the Trace tab.
- Trace tab loads within 2 seconds for workflows with ≤100 spans under standard test conditions.
- Users can download artifacts and inspect token usage per node without leaving the Trace tab.
