# `Nous.Workflow.Trace`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/workflow/trace.ex#L1)

Records execution traces for workflow debugging and observability.

A trace is an ordered list of node executions with timing, status,
and output summaries. Traces are accumulated in-memory during execution
and returned as part of the workflow state metadata.

## Example

    {:ok, state} = Nous.Workflow.run(graph, %{}, trace: true)
    trace = state.metadata.trace

    for entry <- trace.entries do
      IO.puts "#{entry.node_id} (#{entry.node_type}): #{entry.status} in #{entry.duration_ms}ms"
    end

# `entry`

```elixir
@type entry() :: %{
  node_id: String.t(),
  node_type: atom(),
  started_at: DateTime.t(),
  completed_at: DateTime.t() | nil,
  status: :completed | :failed | :skipped | :suspended,
  duration_ms: non_neg_integer(),
  error: term() | nil
}
```

# `t`

```elixir
@type t() :: %Nous.Workflow.Trace{
  entries: [entry()],
  run_id: String.t(),
  started_at: DateTime.t()
}
```

# `new`

```elixir
@spec new() :: t()
```

Create a new empty trace.

# `node_count`

```elixir
@spec node_count(t()) :: non_neg_integer()
```

Returns the number of nodes executed.

# `record`

```elixir
@spec record(
  t(),
  String.t(),
  atom(),
  non_neg_integer(),
  :completed | :failed | :skipped | :suspended,
  term()
) :: t()
```

Record a completed node execution.

# `total_duration_ms`

```elixir
@spec total_duration_ms(t()) :: non_neg_integer()
```

Returns the total execution time in milliseconds.

---

*Consult [api-reference.md](api-reference.md) for complete listing*