Rclex.GraphMonitor (Rclex (Experimental) v0.12.0)

Copy Markdown View Source

Optional GenServer that monitors the ROS 2 graph and emits :telemetry events when nodes, topics, services, or actions join or leave.

Telemetry events

All measurements are %{count: 1}.

EventMetadata keys
[:rclex, :graph, :node_joined]node_name, node_namespace
[:rclex, :graph, :node_left]node_name, node_namespace
[:rclex, :graph, :topic_joined]topic_name, topic_types
[:rclex, :graph, :topic_left]topic_name, topic_types
[:rclex, :graph, :service_joined]service_name, service_types
[:rclex, :graph, :service_left]service_name, service_types
[:rclex, :graph, :action_joined]action_name, action_types
[:rclex, :graph, :action_left]action_name, action_types

Enabling

Pass graph_monitor: true when starting a node:

Rclex.start_node("my_node", graph_monitor: true)

Requires the :telemetry library to be listed as a dependency in your project.

on_entity/4

Registers a zero-arity callback that fires when a ROS entity is visible in the graph. If the entity is already present when on_entity/4 is called, the callback is invoked before the function returns. Otherwise it fires once the first time the entity joins. The callback runs in the GraphMonitor process — keep it non-blocking.

Rclex.GraphMonitor.on_entity("my_node", {:node, "camera_node", "/sensors"}, fn ->
  IO.puts("camera_node is up")
end)

Summary

Types

entity_spec()

Identifies a ROS graph entity to watch.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_snapshot(node_name, opts \\ [])

Return the current graph snapshot maintained by the monitor.

name(name, namespace \\ "/")
on_entity(node_name, entity_spec, callback, opts \\ [])

Registers callback to be called when entity_spec is present in the ROS graph. If the entity is already visible, callback is invoked before this function returns. Otherwise it fires once the first time the entity appears.

start_link(args)

Types

entity_spec()

@type entity_spec() ::
  {:node, node_name :: String.t(), node_namespace :: String.t()}
  | {:topic, topic_name :: String.t()}
  | {:service, service_name :: String.t()}
  | {:action, action_name :: String.t()}

Identifies a ROS graph entity to watch.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_snapshot(node_name, opts \\ [])

@spec get_snapshot(
  monitor_node_name :: String.t(),
  opts :: [{:namespace, String.t()}]
) :: map()

Return the current graph snapshot maintained by the monitor.

The snapshot is a map with keys :nodes, :topics, :services, and :actions, each being a MapSet of the currently known graph entities.

opts

  • :namespace — namespace of the monitor node. Defaults to "/".

name(name, namespace \\ "/")

on_entity(node_name, entity_spec, callback, opts \\ [])

@spec on_entity(
  monitor_node_name :: String.t(),
  entity_spec :: entity_spec(),
  callback :: (-> any()),
  opts :: [{:namespace, String.t()}]
) :: :ok

Registers callback to be called when entity_spec is present in the ROS graph. If the entity is already visible, callback is invoked before this function returns. Otherwise it fires once the first time the entity appears.

entity_spec can be:

  • {:node, node_name, node_namespace} — a ROS node
  • {:topic, topic_name} — a topic (any publisher or subscriber)
  • {:service, service_name} — a service server
  • {:action, action_name} — an action server

opts

  • :namespace — namespace of the monitor node. Defaults to "/".

start_link(args)