Record data and view it in Foxglove
Record the outputs of Holoscan operators to an MCAP file and inspect them in Foxglove, either from the finished file or live while the app runs. To feed a recording back into a graph, see Replay a recording into a graph.
✨ Agent prompt: Record data and view it in Foxglove
Before you start
- You have a C++ Holoscan graph, with the
isaac::common::mcap_loggerlibrary available to your build. Inside the Isaac OS repository, Build and run covers this. From your own project, see Integrate in your project. - Foxglove on a machine that can show a window. It need not be the machine that runs the app.
The steps below are taken from the runnable MCAP logger reference.
Record a graph’s outputs to a file
Create the logger
output_path is a directory. The logger names the file mcap_log_<local-timestamp>.mcap
inside it, so a second run does not overwrite the first:
Attach outputs to topics
Give your graph a reference to the logger:
In compose(), declare a default clock, which compile() requires, then call attach<T>()
once per output you want recorded. The string is the topic name in the file, and each name can
be attached once:
Compile, start the logger, then run
Compile the graph, start the logger with the plan’s endpoint catalog, then run the graph:
Stop the graph, then finalize the file
Call shutdown() explicitly if you need the file complete before the logger goes out of scope.
Check the recording
Run your app. The file is in the directory you passed as output_path, named
mcap_log_<local-timestamp>.mcap.
Try it with the reference app
Record five seconds of data with the reference app:
On exit, the app logs the absolute container path. The default directory, mcap_logger_output/,
is bind-mounted under the host repository root:
For persistent custom output, set --output-path to a bind-mounted container directory.
View a recording in Foxglove
- Open Foxglove and choose Open local file, then select the
.mcapfile. - Add a Raw Messages panel and pick a topic to inspect its fields. Add a Plot panel
and use a message path to chart a value, in the form
/<topic>.<field>[<index>].
The topic list shows the names you passed to attach<T>(). The reference app’s recording has
sine_joint_state, so there you can plot /sine_joint_state.position[0]. Those topics exist
only in a recording made with the reference app; use a topic from your own recording otherwise.
Every topic the logger writes opens this way with no setup. Native panels, such as a pose arrow in a 3D panel or an Image panel on a raw image topic, need the converter extension in the next section.
Install the converter extension for native panels
Install the extension if you want native panels for poses, twists, transforms, camera
calibration or raw images. From a checkout of the Isaac OS repository, build the .foxe
package:
npm run package writes nvidia.isaac-to-foxglove-converter-<version>.foxe in that
directory. Load it into Foxglove: open the Extensions panel, choose Install extension from
file, and select the package, or drag it onto the Foxglove window.
The extension’s README lists the exact conversions it supports.
Stream live while the app runs
In your Holoscan application, pass .enable_stream = true on the HsdkMcapLogger to send every
attached topic to Foxglove while the app runs. Add .enable_write_file = false to stream without
writing a file. At least one of the two must be on:
The Isaac OS process hosts a WebSocket server, and Foxglove connects to it as a client. The
server listens on 127.0.0.1:8765 unless you set websocket_host and websocket_port in
HsdkMcapLoggerOptions. The reference app exposes streaming as --stream, skips the file with
--no-file, and sets the address with --websocket-host and --websocket-port:
The reference app’s container shares the host network, so the server is on the host’s loopback.
If Foxglove runs on another machine, forward the port, then connect Foxglove to
ws://localhost:8765:
The server authenticates no client and encrypts nothing. Keep the default loopback address
unless you have read the Foxglove live streaming section of SECURITY.md; binding
websocket_host to 0.0.0.0 lets anyone who can reach the port read every topic.
The last few seconds of a run may not reach a connected Foxglove client. Rely on the file if you need every sample.
Record camera images
Image topics use the tensor-schema attach<T>() overload, which takes a contract bounding
the frame size. ImageTensorFieldContract computes the bound from the frame dimensions:
A raw image topic is recorded as a generic flatbuffer, so Foxglove needs the converter extension to show it in an Image panel.
To record the topic as GPU-encoded video instead of raw frames, set encode in TopicLogOptions
and pass it to attach<T>(). cuda_device in VideoEncodeOptions selects the GPU and defaults
to 0. Without encode, the topic is recorded as raw frames:
- Foxglove shows an encoded topic in an Image panel without the converter extension.
- An encoded topic writes two channels: the video and a
<topic>/metadatasidecar. - Raw and encoded recordings differ in size and fidelity. The MCAP logger reference compares them.
If the selected GPU has no NVENC encoder, start() throws an exception naming the topic and
device, and does not record raw frames in its place. To record raw frames, attach without encode.
If your app should encode when it can and record raw frames otherwise, check
FrameEncoder::hardware_available(cuda_device, codec) first, as the reference app does.
Adjust file compression
Large data topics can dominate the recording size and affect throughput.
-
Encode images as video. Set
encodeon the image topic, as above. -
Choose the file’s compression. Set
compressionon the logger:Lz4, the default, makes the file smaller at little CPU cost.Nonewrites fastest and makes the largest file, so use it when the disk’s speed and space allow.Zstdmakes the smallest file, but compresses large topics slowly and may lead to topics being dropped.
If the recording is not what you expect
⚠️ A topic is missing from the file
The logger records only outputs you attached with attach<T>(), and attach throws if the same
topic name is used twice.
⚠️ The file is empty or unreadable
The logger was not shut down. Call logger.shutdown() after the graph stops, or let the logger
go out of scope.
⚠️ A topic drops samples
Its poll thread could not keep up and its queue filled, so the oldest samples were dropped. The
logger logs a warning naming the topic. Raising queue_depth in that topic’s TopicLogOptions or
changing file compression may help; see “Adjust file compression”.
Related
-
Library README: every option, error behavior and the on-disk format.
-
MCAP logger reference: the runnable app, its topics and a Foxglove panel layout.