# `DalaDev.Tracing`
[🔗](https://github.com/manhvu/dala_dev/blob/main/lib/dala_dev/tracing.ex#L1)

Distributed tracing for dala Elixir cluster nodes.

Provides tracing capabilities across connected dala nodes to debug
message flows, function calls, and GenServer lifecycle events.

## Examples

    # Start tracing on all connected nodes
    {:ok, trace_id} = DalaDev.Tracing.start_trace(:all_nodes, modules: [MyApp, Dala.Ui.Socket])

    # Trace specific node
    {:ok, trace_id} = DalaDev.Tracing.start_trace(:"dala_qa@192.168.1.5")

    # Get trace events
    events = DalaDev.Tracing.get_events(trace_id)

    # Export to Chrome Tracing format
    DalaDev.Tracing.export_chrome_trace(trace_id, "trace.json")

    # Stop tracing
    :ok = DalaDev.Tracing.stop_trace(trace_id)

# `trace_event`

```elixir
@type trace_event() :: %{
  ts: integer(),
  node: node(),
  event:
    :function_call
    | :message_send
    | :message_receive
    | :process_spawn
    | :process_exit,
  module: module() | nil,
  function: atom() | nil,
  arity: integer() | nil,
  pid: pid(),
  message: term() | nil,
  metadata: keyword()
}
```

# `trace_id`

```elixir
@type trace_id() :: reference()
```

# `trace_opts`

```elixir
@type trace_opts() :: keyword()
```

# `export_chrome_trace`

```elixir
@spec export_chrome_trace(trace_id(), Path.t()) :: :ok | {:error, term()}
```

Export trace events to Chrome Tracing format (JSON).

This format can be loaded in Chrome DevTools (chrome://tracing)
or the `perfetto` UI for visualization.

# `get_events`

```elixir
@spec get_events(trace_id()) :: [trace_event()]
```

Get collected trace events for a trace ID.

# `start_trace`

```elixir
@spec start_trace(node() | :all_nodes | [node()], trace_opts()) ::
  {:ok, trace_id()} | {:error, term()}
```

Start tracing on specified node(s).

Options:
- `:modules` - List of modules to trace (default: all)
- `:pids` - List of PIDs to trace (default: all)
- `:events` - Events to trace (default: [:function_call, :message_send, :message_receive])
- `:match_spec` - Match specification for :dbg (advanced)

Returns a trace ID that can be used to retrieve events.

# `stop_trace`

```elixir
@spec stop_trace(trace_id()) :: :ok | {:error, term()}
```

Stop tracing and collect final events.

# `trace_call`

```elixir
@spec trace_call(node(), module(), atom(), list(), keyword()) ::
  {:ok, term(), [trace_event()]} | {:error, term()}
```

Trace a specific function call on a remote node.

Returns the result and trace events during execution.

---

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