@spec call_flow(String.t() | atom(), String.t(), String.t() | nil) :: map()

Traces the call flow for a given service/request_type from the gateway node to its target node(s).

Returns a map describing every step a request goes through:

• :config — the resolved %FunConfig{} (or nil if not found)
• :local? — whether execution is local (:local) or remote
• :nodes — the list of target nodes after node selection
• :steps — an ordered list of execution phases with descriptions
• :rate_limit — which rate limiter scopes apply
• :permission — the permission check strategy
• :hooks — before/after hook configurations
• :retry — retry configuration (if any)
• :cluster — which of the target nodes are currently reachable

Examples

iex> PhoenixGenApi.Diagnostics.call_flow("user_service", "get_user")
%{
  config: %FunConfig{request_type: "get_user", ...},
  local?: false,
  nodes: [:"service@host"],
  steps: [
    %{phase: :channel, desc: "WebSocket handle_in receives payload"},
    %{phase: :decode, desc: "Payload decoded into %Request{}"},
    %{phase: :config_lookup, desc: "ConfigDb.get(service, type, version)"},
    %{phase: :hooks_before, desc: "before_execute hooks (none configured)"},
    %{phase: :permission, desc: "Permission.check_permission!/2"},
    %{phase: :rate_limit, desc: "RateLimiter.check_rate_limit/1"},
    %{phase: :argument_validation, desc: "ArgumentHandler.convert_args!/2"},
    %{phase: :node_selection, desc: "NodeSelector picks :random from [node@host]"},
    %{phase: :execution, desc: "RPC to service@host"},
    %{phase: :hooks_after, desc: "after_execute hooks (none configured)"},
    %{phase: :response, desc: "Result pushed back to client via WebSocket"}
  ],
  ...
}

@spec cluster_view() :: map()

Returns a cluster topology view from the perspective of this node.

Shows connected nodes, registered processes, and which PhoenixGenApi services are reachable.

@spec debug_report(keyword()) :: map()

Returns a debug-oriented snapshot for local runtime inspection.

Options:

• :process_limit — Maximum number of processes to include, sorted by memory usage. Defaults to 20.
• :include_current_stacktrace — Includes each process stacktrace when true. Defaults to false.

The returned process summaries intentionally avoid full message queues and dictionaries by default.

@spec health_check(keyword()) :: health_report()

Returns a runtime health report for the VM, Erlang distribution, and PhoenixGenApi processes.

Options:

• :max_memory_bytes — if set and total memory exceeds it, the vm check is marked :degraded.

The report is structured and non-destructive. It does not mutate the system.

@spec inspect_request(map() | PhoenixGenApi.Structs.Request.t()) :: map()

Inspects a %Request{} struct and returns a detailed execution plan showing exactly what will happen when the request is executed.

This is useful for debugging why a request succeeds, fails, or routes to a particular node.

@spec list_call_flows(keyword()) :: [map()]

Returns a summary of all registered call flows across all services.

Each entry shows the service, request_type, version, target nodes, and execution mode (local vs remote).

@spec statistics(keyword()) :: map()

Returns VM and PhoenixGenApi runtime statistics.

The VM section contains process, memory, scheduler, reductions, runtime, and garbage collection counters. The PhoenixGenApi section contains status for the config cache, puller, receiver, rate limiter, worker pools, relay server, and telemetry event coverage.

@spec stop_trace(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Disables legacy Erlang tracing for processes or ports.

This operation requires the :disable_tracing admin action.

@spec stop_trace_functions(term()) :: {:ok, map()} | {:error, term()}

Disables call tracing for specific MFAs.

Passing :all disables all call trace patterns.

@spec trace_functions(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Enables call tracing for specific MFAs.

This operation requires the :enable_tracing admin action.

MFAs can be {Module, Function}, {Module, Function, Arity}, or :all. Arity may be a non-negative integer or :_ for all arities.

Options:

• :flags — Process trace flags. Defaults to [:call, :return_to, :procs].
• :match_spec — Match specification passed to :erlang.trace_pattern/3. Defaults to true.
• :tracer — PID that receives trace messages. Defaults to self().

@spec trace_processes(
  term(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Enables legacy Erlang tracing for processes or ports.

This operation requires the :enable_tracing admin action.

Supported targets:

• :all
• :processes
• :ports
• :existing
• :existing_processes
• :existing_ports
• :new
• :new_processes
• :new_ports
• a PID or port
• a list of the above

Options:

• :flags — Trace flags. Defaults to [:call, :return_to, :procs].
• :tracer — PID that receives trace messages. Defaults to self().

@spec trace_status() :: map()

Returns a small trace status snapshot.