An Error Message Is Not a Diagnosis: Writing a Useful Robot Service Intake

When a mobile manipulator stops mid-task and prints a red line to the screen, that line is a message, not a verdict. In ROS 2 Jazzy, log records carry a severity level such as ERROR or WARN, and each node has a logger whose name reflects the node name and namespace, or a remapped name if routing changed it, according to the ROS 2 Jazzy documentation. A useful intake form therefore separates what the operator saw, what the machine recorded, and what nobody has proven yet.

Why an Error String Is Not a Root Cause

An operator reads [ERROR] [nav_node]: timeout waiting for transform and writes “the robot is broken.” The intake should instead record the exact severity string, the logger name, and the surrounding messages at lower thresholds. Because log severity levels ascend from DEBUG through INFO, WARN, ERROR to FATAL, and a logger filters out anything below its configured level, a single ERROR line may hide the INFO or DEBUG context that explains it. The source also states that ROS 2 can deliver messages to the console, to disk files, and to the /rosout topic, and that all targets are individually enabled or disabled per node. A good intake asks which targets were active, since a missing disk file or a disabled external logger changes what can be reconstructed later.

Recording Observed Symptom, Event, and Hypothesis

Three columns prevent confusion. The first holds the observed symptom: what a person witnessed, such as a halted arm or a stalled base, with wall-clock time. The second holds the recorded event: the unchanged log excerpt, the logger name, the severity label, and the formatting fields shown in the console, because the output format itself can include severity, name, message, time, function name, file name and line number per the same logging source. The third holds any untested hypothesis, clearly labelled as a guess, such as suspecting a transform delay. No repair instruction belongs in this form; its role is to preserve observations and records for later service review, not to diagnose the fault.

Hypothetical Intermittent Issue Example

Consider a hypothetical warehouse robot running Jazzy nodes that, on about one run in twelve, pauses for two seconds near a doorway and then resumes without human action. The intake records the observed symptom as “paused near door B4 at 14:03:11 for 2.0 s.” The recorded event is a WARN-level line from a perception logger and the preceding DEBUG lines that were written because the node ran with a lowered level. The hypothesis column says “possibly a delayed transform or a late scan,” and marks it untested. Because logger names form a hierarchy, and a child logger defers to its parent unless explicitly set, the form also records whether any logger level was changed only for one node or for a hierarchy such as a namespace prefix. This hypothetical example shows why metadata about the setting matters as much as the message text.

Requesting Unchanged Logs Rather Than Summaries

The intake should request the raw log file, not a retyped summary. Since the log directory can be controlled by ROS_LOG_DIR, or constructed from ROS_HOME as $ROS_HOME/.log, the form should ask where the file came from and whether it was copied verbatim. The console output format can be customized with environment variables, so the time field may be seconds since epoch, ISO date-time with milliseconds, or nanoseconds depending on configuration; the intake must preserve whichever form was used rather than converting it. Unchanged logs let later reviewers compare timestamps across nodes without the distortion of a human paraphrase.

Parameter Metadata That Shapes the Record

Parameters are node-level configuration values whose lifetime is tied to the node, addressed by node name, namespace, parameter name and optional parameter namespace, as described in the ROS 2 Jazzy documentation. Each parameter has a key, a value of a predefined type such as bool, int64, float64 or string, and a descriptor that may hold ranges or constraints. The intake should capture the parameter values and their descriptors at the moment of the incident, because a timeout, a rate limit or a frame name stored as a parameter changes how the same log line should be read. Recommended documentation practice is to log parameter names together with their types and any declared ranges, rather than only the numeric value.

A Practical Intake Checklist for Robot Service Notes

A short checklist keeps the distinction intact. Record the node name and namespace exactly as remapping may alter the logger name. Record the severity level of each quoted line and the format fields actually present. State whether console, disk and /rosout targets were enabled, since disabling the external library removes disk files entirely. Attach the parameter snapshot with node name, parameter name, value and type. Mark every interpretation as hypothesis. Do not write repair steps; instead write what was observed and what was recorded. This recommended documentation practice helps a service reviewer start from evidence instead of assumption, using the log and parameter facts established in the linked Jazzy documentation.

For further equipment reading, browse related industry updates and technical reference articles alongside this practical note.