Fast DDS Spy 配置指南

最新推荐文章于 2025-09-26 18:16:15 发布

原创最新推荐文章于 2025-09-26 18:16:15 发布 · 905 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#FastDDS #FastDDS Spy

FastDDS Debug Tool 专栏收录该内容

3 篇文章

订阅专栏

Fast DDS Spy 配置指南

Fast DDS Spy 实例可通过 YAML 配置文件进行配置。若要为 Fast DDS Spy 指定配置文件，需使用配置文件参数。

一、DDS 配置

YAML 配置支持可选的 dds 标签，该标签包含特定的 DDS 配置。可配置的参数如下：

（一）主题过滤

Fast DDS Spy 会自动检测 DDS 网络中正在使用的主题，并为每个主题创建内部 DDS 读取器（Reader）以处理发布的数据。Fast DDS Spy 允许对 DDS 主题进行过滤，即用户可配置需要处理的 DDS 主题。这些数据过滤规则可在 allowlist（允许列表）和 blocklist（阻止列表）标签下配置，具体规则如下：

若未配置 allowlist 和 blocklist，Fast DDS Spy 将处理其发现的所有主题上发布的数据。
若同时配置了 allowlist 和 blocklist，且某个主题同时出现在两个列表中，则 blocklist 具有优先级，该主题会被阻止。

主题由 name（必填）和 type（类型）两个标签确定，两者均支持通配符。

注意：在 YAML 文件中，值周围的引号通常是可选的，但包含通配符的值必须使用单引号或双引号括起来。

以下为示例：

allowlist:
  - name: AllowedTopic1
    type: Allowed
  - name: AllowedTopic2
    type: "*"
  - name: HelloWorldTopic
    type: HelloWorld

blocklist:
  - name: "*"
    type: HelloWorld

在该示例中：

主题名为 AllowedTopic1、类型为 Allowed 的数据，以及主题名为 AllowedTopic2、类型为任意值的数据，将由 Fast DDS Spy 处理。
主题名为 HelloWorldTopic、类型为 HelloWorld 的数据会被阻止，因为 blocklist 阻止了所有名称任意、类型为 HelloWorld 的主题。

（二）主题服务质量（QoS）

以下是可针对主题配置的服务质量（QoS）集合。有关主题的更多信息，请参阅 Fast DDS 主题部分。

服务质量（Quality of Service）	YAML 标签	数据类型	默认值	QoS 配置选项
可靠性（Reliability）	`reliability`	布尔值（bool）	`false`	`RELIABLE`（可靠）/ `BEST_EFFORT`（尽力而为）
持久性（Durability）	`durability`	布尔值（bool）	`false`	`TRANSIENT_LOCAL`（本地暂存）/ `VOLATILE`（易失）
所有权（Ownership）	`ownership`	布尔值（bool）	`false`	`EXCLUSIVE_OWNERSHIP_QOS`（独占所有权）/ `SHARED_OWNERSHIP_QOS`（共享所有权）
分区（Partitions）	`partitions`	布尔值（bool）	`false`	带分区的主题 / 不带分区的主题
关键字（Key）	`keyed`	布尔值（bool）	`false`	带关键字的主题 / 不带关键字的主题
历史深度（History Depth）	`history-depth`	无符号整数	`5000`	历史深度值
最大接收速率（Max Reception Rate）	`max-rx-rate`	浮点数（float）	`0`（无限制）	最大接收速率（单位：Hz）
降采样（Downsampling）	`downsampling`	无符号整数	`1`	降采样系数

警告：手动配置 TRANSIENT_LOCAL 持久性时，若发现的可靠性为 BEST_EFFORT（尽力而为），可能会导致兼容性问题。因此，配置持久性时，请务必同时配置可靠性，以避免该问题。

1. 历史深度

history-depth 标签用于配置 Fast DDS 内部实体的历史深度。默认情况下，每个 RTPS 历史实例的深度为 5000。当样本大小和/或创建的端点数量（随主题数量增加而增加）大到可能导致内存耗尽时，应减小该值。

2. 最大接收速率

max-rx-rate 标签通过丢弃“自上次处理消息以来，未超过 1/max-rx-rate 秒就接收到的消息”，来限制样本的处理频率（单位：Hz）。该标签仅接受非负值，默认值为 0，表示以无限制的接收速率处理样本。

3. 降采样

downsampling 标签用于降低接收数据的采样率，具体方式为：每接收到 n 个样本（per 主题），仅保留其中 1 个样本，其中 n 为 downsampling 标签下指定的值。若同时设置了 max-rx-rate 标签，则降采样仅适用于通过 max-rx-rate 过滤后的消息。该标签仅接受正整数，默认值为 1，表示接收所有消息。

（三）手动配置主题

可在 topics 标签下为特定主题手动配置部分主题服务质量（QoS）。topics 标签包含以下子标签：

必选的 name 标签：支持通配符。
可选的 type 标签：支持通配符。
可选的 qos 标签：用于配置用户希望手动设置的主题服务质量（QoS）。若未手动配置 qos，则其值将通过发现机制获取。

示例如下：

topics:
  - name: "temperature/*"
    type: "temperature/types/*"
    qos:
      max-tx-rate: 15
      downsampling: 2

注意：手动配置主题中设置的主题服务质量（QoS），优先级高于规格配置（Specs）中的主题服务质量（QoS）。

（四）DDS 域 ID（Domain Id）

若要在非默认域 ID（默认域 ID 为 0）的环境中运行 Fast DDS Spy 实例，可使用 domain 标签进行配置。

（五）忽略参与者标志（Ignore Participant Flags）

可定义一组发现流量过滤器，以增加一层隔离。该配置项可通过 ignore-participant-flags 标签设置，可选值如下：

ignore-participant-flags: no_filter                          # 不过滤（默认值）
# 或
ignore-participant-flags: filter_different_host              # 丢弃来自其他主机的发现流量
# 或
ignore-participant-flags: filter_different_process           # 丢弃来自同一主机上其他进程的发现流量
# 或
ignore-participant-flags: filter_same_process                # 丢弃来自自身进程的发现流量
# 或
ignore-participant-flags: filter_different_and_same_process  # 丢弃来自自身主机的发现流量

有关更多信息，请参阅“忽略参与者标志”（Ignore Participant Flags）部分。

（六）自定义传输描述符（Custom Transport Descriptors）

默认情况下，Fast DDS Spy 内部参与者会启用 UDP（用户数据报协议）和共享内存（Shared Memory）传输描述符来创建。具体使用哪种传输方式进行通信，取决于具体场景；当两种方式均适用时，系统会自动选择效率更高的共享内存传输（Shared Memory Transport）。不过，用户也可强制使用其中一种传输方式，只需通过 transport 配置标签进行设置，可选值如下：

transport: builtin    # 同时使用 UDP 和共享内存（默认值）
# 或
transport: udp        # 仅使用 UDP
# 或
transport: shm        # 仅使用共享内存

警告：当配置为 transport: shm（仅使用共享内存）时，Fast DDS Spy 仅能与“仅使用共享内存传输（已禁用 UDP 传输）”的应用程序通信。

（七）接口允许列表（Interface Whitelist）

可选标签 whitelist-interfaces 可用于限制 UDP 和 TCP（传输控制协议）传输所使用的网络接口。这在仅允许主机内部通信的场景中可能有用（注：使用“忽略参与者标志”也可实现相同效果）。示例如下：

whitelist-interfaces:
  - "127.0.0.1"    # 仅允许本地主机（localhost）

有关更多信息，请参阅“接口允许列表”（Interface Whitelist）部分。

（八）主题类型格式（Topic Type Format）

可选标签 ros2-types 用于指定模式（schema）的显示格式：

当设置为 true 时，模式以 ROS 2 消息格式（.msg）显示。
当设置为 false 时，模式以 OMG IDL 格式（.idl）显示。

二、规格配置（Specs Configurations）

YAML 配置支持可选的 specs 标签，该标签包含与应用程序整体配置相关的特定选项。可配置的参数如下：

（一）线程数量（Number of Threads）

specs 支持可选的 threads 参数，用户可通过该参数设置内部“线程池”（ThreadPool）的最大线程数。线程池可限制应用程序生成的线程数量，从而提升参与者之间数据传输的性能。

该值需用户根据自身系统特性进行设置，默认值为 12。

（二）发现时间（Discovery Time）

specs 支持可选的 discovery-time 参数，用于设置“一次性应用”（One-shot application）获取输出并关闭前的等待时间（单位：毫秒）。在大型网络中，该参数非常有用——因为 Fast DDS Spy 可能无法快速发现整个网络，导致无法返回完整信息。该参数默认值为 1000（即 1 秒）。

（三）服务质量（QoS）

specs 支持可选的 qos 标签，用于配置主题服务质量（QoS）的默认值。

注意：specs 中配置的主题服务质量（QoS），可被“手动配置主题”（Manual Topics）中的配置覆盖。

（四）日志记录（Logging）

specs 支持可选的 logging 标签，用于配置 Fast DDS Spy 的日志。在 logging 标签下，用户可配置要显示的日志类型，并根据日志内容和类别对日志进行过滤，具体规则如下：

当将详细级别（verbosity）配置为 info 时，将显示所有类型的日志，包括信息性消息、警告和错误。
当将详细级别配置为 warning 时，仅显示警告和错误。
当将详细级别配置为 error 时，仅显示错误。

默认情况下，过滤器允许显示所有错误，并选择性地允许显示来自 FASTDDSSPY 类别的警告和信息性消息。

注意：通过命令行配置日志的方式仍然有效；当同时使用命令行和 YAML 两种方式配置日志时，命令行配置的优先级更高。

日志配置项（Logging）	YAML 标签	描述	数据类型	默认值	可能值
详细级别（Verbosity）	`verbosity`	显示优先级大于或等于该级别的消息	枚举（enum）	`error`	`info` / `warning` / `error`
过滤器（Filter）	`filter`	用于过滤日志类别或日志消息的正则表达式	字符串（string）	info：`FASTDDSSPY`；warning：`FASTDDSSPY`；error：`""`（空字符串）	正则表达式字符串

注意：要使日志正常工作，编译时需添加 -DLOG_INFO=ON 编译标志。

Fast DDS Spy 默认会打印日志：警告和错误日志输出到标准错误流（stderr），信息性日志输出到标准输出流（stdout）。此外，Fast DDS Spy 也可将日志发布到 DDS 主题中。若要发布日志，需在 publish 标签下进行如下配置：

设置 enable: true（启用日志发布）。
指定 domain（域 ID）和 topic-name（主题名）。

发布的日志类型定义如下（对应 LogEntry.idl 文件）：

const long UNDEFINED = 0x10000000;
const long SAMPLE_LOST = 0x10000001;
const long TOPIC_MISMATCH_TYPE = 0x10000002;
const long TOPIC_MISMATCH_QOS = 0x10000003;

enum Kind {
  Info,
  Warning,
  Error
};

struct LogEntry {
  @key long event;
  Kind kind;
  string category;
  string message;
  string timestamp;
};

日志配置示例如下：

logging:
  verbosity: info
  filter:
    error: "DDSPIPE|FASTDDSSPY"
    warning: "DDSPIPE|FASTDDSSPY"
    info: "FASTDDSSPY"
  publish:
    enable: true
    domain: 84
    topic-name: "FastDdsSpyLogs"
  stdout: true

三、通用示例（General Example）

以下是包含本文所述所有配置项的完整示例。

警告：该示例仅可作为快速参考，由于存在兼容性问题或互斥属性，其配置可能并不完全正确，请勿将其视为可直接运行的示例。

dds:
  domain: 0
  allowlist:
    - name: "topic_name"
      type: "topic_type"
  blocklist:
    - name: "topic_name"
      type: "topic_type"
  topics:
    - name: "temperature/*"
      type: "temperature/types/*"
      qos:
        max-rx-rate: 5
        downsampling: 1
  ignore-participant-flags: no_filter
  transport: builtin
  whitelist-interfaces:
    - "127.0.0.1"
  ros2-types: false

specs:
  threads: 12
  discovery-time: 1000
  qos:
    history-depth: 5000
    max-rx-rate: 10
    downsampling: 2
  logging:
    verbosity: warning
    filter:
      error: ""
      warning: "FASTDDSSPY"
      info: "FASTDDSSPY"
    publish:
      enable: true
      domain: 0
      topic-name: "FastDdsSpyLogs"
    stdout: true