A Repair Request Needs a Reproduction Boundary, Not a Guessed Root Cause

A useful repair request does not begin with a guessed component failure. It begins with a reproduction boundary: a precise account of what software behavior was captured, what execution context accompanied that capture, and which physical or environmental conditions remain unknown. For a ROS 2 system, bag recordings and logs can strengthen that account, but they answer different questions. A bag preserves selected communications for later examination; logs record messages emitted through configured logging targets. Neither establishes that a motor, sensor, connector, or firmware fault has been reproduced. The practical objective is narrower and more valuable: give the next technician an evidence set whose scope and blind spots are explicit.

Define the Boundary Before Naming a Cause

We recommend dividing the intake statement into four fields: observed behavior, replayable artifacts, capture context, and unobserved conditions. “Observed behavior” should describe what a person or monitoring process actually saw, with a time window and operating mode where available. “Replayable artifacts” should identify files and their contents rather than simply saying that a recording exists. “Capture context” should cover the software configuration needed to interpret those files. “Unobserved conditions” should prevent later readers from silently filling gaps with assumptions.

Consider a hypothetical mobile base that stops reacting to velocity commands while its navigation process remains active. “The motor driver failed” is a diagnosis, not an intake observation. A better initial statement is that command messages were or were not seen during a specified interval, that particular topics were recorded, and that actuator current, wheel motion, power state, and driver temperature were not measured. This wording does not favor a software explanation over a hardware one. It simply keeps each hypothesis separate from the evidence currently available.

The boundary should also distinguish an unsuccessful replay from an unreplayable incident. A recorded exchange may be playable even when the original machine behavior cannot be recreated. Conversely, an intermittent physical event may leave too little useful data for a meaningful replay. Recording that distinction early helps avoid treating a failed software demonstration as proof that a hardware component is innocent.

Scope Bag Recordings by Their Actual Contents

In ROS 2 Jazzy, ros2 bag is documented as a command-line tool for recording data published on topics and services, accumulating it in a database, and allowing it to be replayed and examined later. Service recording requires the relevant service introspection to be enabled, and the tutorial records a service through its service-event topic (ROS 2 Jazzy recording and playback documentation). That is the narrow capability on which an intake workflow can rely. It does not imply that every node input, internal state, network exchange, or device interaction has been captured.

For each bag, we recommend attaching the exact recording command, start and stop circumstances, output path, and the output of ros2 bag info. The topic list should be read as an inclusion list, not as a description of the whole system. If only /cmd_vel was requested, the absence of camera, diagnostic, or actuator-status data is expected. If a topic appears in the metadata with zero messages, that fact should be reported separately from a topic that was never selected; the two situations support different next steps.

Message counts also need careful interpretation. A sparse command stream and a dense periodically published stream can coexist in the same recording without either being abnormal. Counts describe what was stored during the capture, not whether the publishing rate was correct for the application. Where timing matters, retain the bag’s timestamps and note any separate clock or synchronization observations; do not replace them with a narrative such as “the delay was about two seconds” unless that interval was actually measured.

Service events deserve the same restraint. In a hypothetical gripper request that appears to time out, a service-event recording may help establish which requests and responses were visible to the recording path. It does not, by itself, reveal whether a mechanism moved, whether a controller accepted a command internally, or whether an independent electrical fault occurred. A useful boundary entry would therefore name the captured service, the introspection configuration, and the physical observations that were not collected.

Treat Playback as an Experiment, Not a Verdict

Playback changes the experimental setup even when the recorded messages are unchanged. The Jazzy tutorial’s turtlesim demonstration says that the turtle follows the recorded path, though not exactly, because turtlesim is sensitive to small changes in system timing (the same ROS 2 Jazzy bag tutorial). This is a specific playback caveat, not a universal quantitative model of replay error. It is enough to justify a conservative intake rule: do not promise bit-for-bit behavior, identical timing, or reproduction of a physical fault.

Before playback, we recommend writing down the intended question. For example, the question might be whether a consumer node emits the same diagnostic message when given the recorded inputs, or whether a visualization shows a gap already present in the capture. It should not be “prove the robot is safe” or “confirm the driver is defective.” Also record which nodes are running during playback, whether live publishers have been stopped or isolated, and whether recorded outputs could command real equipment. A bench configuration that cannot reach actuators may be appropriate for software inspection, but that isolation must be stated because it changes what the test can demonstrate.

After playback, compare results against the stated question and preserve both matches and mismatches. A different outcome can arise from configuration, timing, node state, subscriptions, or unrecorded inputs; it does not automatically identify the original cause. A matching outcome is likewise limited to the tested path. These are recommendations for designing a disciplined diagnostic experiment, not claims that playback supplies a general reproduction guarantee.

Record Logging Configuration as Part of the Evidence

Logs need their own boundary because a missing message may reflect configuration rather than system behavior. ROS 2 Jazzy documents five severity levels in ascending order—DEBUG, INFO, WARN, ERROR, and FATAL—and states that a logger processes messages at or above its selected level. It also documents console, disk, and /rosout as logging targets that can be individually enabled or disabled per node (ROS 2 Jazzy logging documentation). Consequently, “no error was logged” is incomplete unless the reader knows which targets were enabled and what severity threshold applied.

We recommend capturing the effective logger levels where practical, the node launch arguments, and the destination of each retained log file. Record whether console output was copied from a terminal, collected by a process supervisor, or reconstructed later from memory; only the first two are direct artifacts. If /rosout was recorded in a bag, identify it as another recorded topic rather than assuming it contains every message produced by every node. If disk logging was disabled or its directory changed, note that explicitly instead of allowing an empty expected directory to look like evidence of clean operation.

Environment settings are process-wide in the cited logging configuration, whereas several node options are per-node. That distinction matters when multiple nodes share a process. The intake record should avoid assigning one global severity or output setting to the entire machine unless that scope was verified. It should also preserve the original log format and timezone context where available, so timestamps can be compared with bag metadata without silently mixing clock domains.

Use a Handoff Checklist That Preserves Uncertainty

A compact handoff can use the following recommended fields:

• Incident description: observed behavior, relevant operating mode, capture interval, and who or what observed it.
• Artifact inventory: bag paths, log paths, configuration snapshots, and any separate measurements, with clear labels for originals and derived copies.
• Recording scope: exact topic and service selections, introspection state for recorded services, and the ros2 bag info summary.
• Logging scope: applicable logger levels, enabled targets, launch overrides, and known changes to log output locations or formats.
• Replay plan: the question being tested, required nodes and configuration, isolation from live publishers or equipment, and the result actually observed.
• Missing conditions: unrecorded topics, unavailable internal states, mechanical and electrical observations not made, and periods outside the capture window.
• Open hypotheses: possible explanations kept separate from confirmed facts, each paired with a measurement that could narrow it.

This structure makes absence legible. Silence in an unrecorded stream is missing evidence; silence below a logger’s threshold may be filtered evidence; a physical response outside the software capture is an untested condition. Keeping those cases distinct gives technicians a better starting point than a confident but unsupported root-cause label. Readers building a broader documentation workflow can use our technical guides for related practical material and industry updates for a different reading track. The intake recommendation itself remains simple: submit a bounded observation set, state what replay can and cannot test, and leave the next diagnostic step visibly open.