diff --git a/README.md b/README.md index bf8de16..3b98974 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,11 @@ Supports the following ROS versions: ## modality-ros-hook -An `LD_PRELOAD` integration for the rmw (ROS middleware abstraction) interface layer that provides topic -publisher and subscriber tracing. +An `LD_PRELOAD` integration for the rmw (ROS middleware abstraction) interface layer that provides +- Precise topic publisher and subscriber tracing, including exact receive points. +- Precise service (RPC) tracing, on the client and server -### Getting Started +## Getting Started 1. Get the plugin shared library * Build from source @@ -45,7 +46,7 @@ publisher and subscriber tracing. implementation in `LD_PRELOAD` here, the dispatch library isn't loaded at all, which allows our `LD_PRELOAD` hooks to work. -### Configuration +## Configuration These environment variables configure the behavior of the ROS LD_PRELOAD library: @@ -87,3 +88,124 @@ These environment variables configure the behavior of the ROS LD_PRELOAD library This library uses the same connection and configuration infrastructure as reflector plugins; see the [`modality-reflector` Configuration File documentation](https://docs.auxon.io/modality/ingest/modality-reflector-configuration-file.html) for more information. + +## Adapter Concept Mapping + +The following describes the default mapping between ROS concepts and +Modality's concepts. + +* A timeline is created for each ROS node. The timeline's name is + created by combining the node's namespace and name with a `/` + character. Any preceiding `/` in the node's namespace is + removed. For example, a node with the namespace `/nav` and the name + `gps` will create a timeline named `nav/gps`. + +* When a message is published by a ROS node, an event is created on that node's timeline. + + * The event name is the name of the topic on which the message was + published, with any preceding '/' character removed. For example, + a message published on the '/orientation' topic will be logged + in modality as an event named 'orientation'. + + * The payload data on the message is converted to event attributes. + * The attribute name is the name of the payload field. For + example, the `depth` payload field would be converted to the + `depth` attribute. + + * Nested structures are flattened, with their names connected by + the `.` character. For example, if a payload contains a + `velocity` structure, which in turn contain `x` and `y` field, + the event will contain the attributes `velocity.x` and + `velocity.y`. + + * Arrays are flattened as well; the array index is used as a + numeric value, again separated by `.` charcters. For example, + if a playload contains an array named `position` with three + elements, the event will contain the attributes `position.0`, + `position.1`, and `position.2`. + + * The probe intentionally limits the size of arrays which are + converted. By default, arrays up to length 12 will be + converted; anything longer will be ignored. This threshold + may be customized using the `MODALITY_ROS_MAX_ARRAY_LEN` + environment variable. + + * Payload values are converted to attribute values directly: + * String, WString, Char, and WChar are converted to Modality strings + + * Floats and Doubles are converted to Modality floats (64 bit) + + * Booleans are converted to Modality booleans + + * All integer numeric types are converted to Modality integers + (stored as signed 64 bit). Large UInt64 values may be promoted + to a Modality BigInt (128 bit). + + * The '/rosout' topic is special cased: the textual content of the + message is used as the event name. + +* When a service interaction is made by a ROS node, an event is created on that node's timeline. + + * One event is created for each step in the service RPC lifecycle: + send request, take (receive) request, send response, and take + (receive) response. The request events are logged on the client + node's timeline, while the response events are logged on the + servce node's timeline. + + * These events are named using the name of the service. Any + preceding slashes are removed, and any intermediate slashes are + replaced with `.` characters. For example, calls to the service + `/waypoint/create` would be logge as events named + `waypoint.create`. The exact service name is also available as + the `event.ros.service.name` attribute. + + * The different events in the service lifecycle may be distinguished + using the `event.ros.service.event` attribute. + +* The following timeline attributes are added: + * `timeline.ros.node.namespace`: (string) The exact namespace of the ROS node. + + * `timeline.ros.node.name`: (string) The exact name of the ROS node. + + * `timeline.ros.node`: (string) The exact namespace and name of the ROS node, combined with a `/` character. + + * `timeline.ros.publisher_gid.`: (boolean) This attribute is set to true for + a node that publishes messages using the graph id ``. It is used + for connecting pubsub-related interactions. + + * `timeline.ros.service.client_guid.`: (boolean) This attribute is set to + true for a node which a service client that is identified by ``. It is used + for connecting service-related interactions. + +* The following attributes are added to pubsub-related events: + * `event.ros.topic`: (string) The exact name of the topic on which + message was published (or received). + + * `event.ros.publish`: (bool) This is present, and set to true, for + events logged when a message is published on a topic. + + * `event.ros.received`: (bool) This is present, and set to true, for + events logged when a message received on a node that subscribed to a topic. + + * `event.ros.schema.namespace`: (string) The exact namespace of the + schema for the pubsub message's payload. + + * `event.ros.schema.name`: (string) The exact namespace of the + schema for the pubsub message's payload. + +* The following event attributes are added to service-related events: + * `event.ros.service.name`: (string) For service-related events, + this is set to the exact name of the service involved. + + * `event.ros.service.event`: (string) For service-related events, + this indicates what part of the service transaction is being + represented. The value is one of `send_request`, `recv_request`, + `send_response`, or `recv_response`. + +* The following additional special events are logged, representing + operations that occur at the RMW (ROS Middlware) layer: + * `rmw.create_node` / `rmw.destroy_node` + * `rmw.create_publisher` / `rmw.destroy_publisher` + * `rmw.create_subscription` / `rmw.destroy_subscription` + * `rmw.create_service` / `rmw.destroy_service` + * `rmw.create_client` / `rmw.destroy_client`