MCAP文件格式规范

MCAP文件格式规范

概述

MCAP是一种模块化的容器文件格式,用于记录带时间戳的发布/订阅消息,支持任意序列化格式

文件结构

有效的MCAP格式如下,其中摘要区(Summary)和摘要偏移区(Summary Offset)是可选的

<Magic><Header><Data section>[<Summary section>][<Summary Offset section>]<Footer><Magic>

Data section、Summary、Summary Offset section均由records组成

[<record type><record content length><record><record type><record content length><record>]

不符合这种结构的文件被视为格式错误

Magic

MCAP 文件必须以下列魔数字节开头和结尾

0x89, M, C, A, P, 0x30, \r, \n

紧接在 "MCAP" 后面的字节表示主版本号。0x30 是 ASCII 字符 0。

Header

Magic之后的第一条记录是Header记录

<0x01><record content length><record>

Footer

结尾Magic之前的最后一条记录的是Footer记录

<0x02><record content length><record>

Data section

数据区包含message data,attachements,和辅助records

  • Schema
  • Channel
  • Message
  • Attachment
  • Chunk
  • Message Index
  • Metadata
  • Data end
    数据区的最后一条记录必须是Data end
使用Chunk records

MCAP 文件可以将 Schema、Channel 和 Message 记录直接写入数据区,也可以将它们写入 Chunk 记录,以便建立索引和进行压缩。
对于Summary section包含 Chunk Index 记录的 MCAP 文件,所有 Message 记录都应写入 Chunk 记录。

为什么? Sumamry section存在 Chunk Index 记录,意味着读取器可以认为该 MCAP 文件已建立索引,并使用这些记录按记录时间或topic查找消息。但是,Chunk 之外的 Message 记录无法建立索引,使用索引的读取器可能无法找到这些消息。

Summary Section

可选的Summary section包含用于快速查找文件信息或其他数据区的records。
以下的records可以出现在summary section中:

  • Schema
  • Channel
  • Chunk Index
  • Attachment Index
  • Metadata Index
  • Statistics

所有在summary section中的records都必须通过opcode分组

为什么? 按opcode对summary记录分组,可以让Summary Offset section更高效地对Summary secton建立索引。

在summary中出现的Channel records是Data section中 Channel的副本
在summary中出现的Schema records是Data section中的Schema的副本

Summary Offset Section

可选的Summary Offset section包含了Summary offset的记录,用于快速查找summary section中的records
Summary offset section有助于随即访问读取summary

Records

MCAP 文件可以包含多种record,每种record由一个单字节操作码标识。

  • 0x01-0x7F:保留供MCAP格式使用,包括未来扩展
  • 0x80-0xFF:保留给私有记录
  • 0x00:不是有效的操作码
    私有记录由具体应用定义,不属于 MCAP 规范的定义范围。

所有record均按以下形式序列化

<record type><record content length><record content>

Record type是单字节的opcode,record content length是uint64类型
records可以从一个从存在的fields中添加fields来扩展,读取器要忽略任何未知字段

Message, DataEnd和Footer records不能被扩展,因为它们的格式不支持保持向后兼容的大小变更

下文每种record定义均包含“类型”列。各类型的序列化方式参见“序列化”一节。

Header(op=0x01)

Bytes Name Type Description
4+N profile String 用于指明文件中各字段的约束,例如 encoding、user_data 等。如果取值匹配某个公认的 profile,文件应遵循该 profile。此字段也可以为空,或填写一个不属于已知 profile 的框架名称
4+N library String 自由格式字符串,供写入器指定名称、版本或其他调试信息

Footer(op=0x02)

Footer 记录包含文件结束信息,必须是文件中的最后一条记录。使用索引读取文件的读取器会先读取Footer和结尾Magic

Bytes Name Type Description
8 summary_start uint64 从文件起始位置到summary setion第一条记录的字节偏移量。如果summary section 没有记录,则应为 0
8 summary_offset_start uint64 从文件起始位置到summary offset第一条record的字节偏移量。如果没有Summary Offset record,则应为0
4 summary_crc uint32 从summary 起始位置开始,直到Footer中前一个字段(summary_offset_start) 结束为止,所有字节的CRC32校验值,取值为0表示未提供CRC32

Schema(op=0x03)

Schema record定义一个单独的schema。
schema records在文件内通过schema id作为唯一标识。在任何channel引用某个schema id之前,schema record 在文件中必须至少出现一次。具有相同id的任意两条schema record必须完全一致

Bytes Name Type Description
2 id uint16 此 Schema 在文件内的唯一标识符,不得为 0
4+N name String 此 Schema 的名称标识
4+N encoding String Schema 的格式。优先使用公认的 Schema 编码。空字符串表示没有可用的 Schem
4+N data uint32 length-prefixed Bytes 带 uint32 长度前缀的 Bytes 必须符合指定的 Schema 编码。如果 encoding 为空字符串,则 data 的长度应为 0

Schema record 可以在summary section中重复出现。id为0的schema record无效,读取器应忽略它

Channel(op=0x04)

channel record 定义某个topic上的编码消息流
channel record 在文件内通过channel id作为唯一标识。在任何message引用某个channel id之前,对应的channel record必须在文件中至少出现一次。具有相同id的任意两条channel record必须完全一致

Bytes Name Type Description
2 id uint16 唯一标识
2 schema_id uint16 此通道消息使用的 Schema。schema_id 为 0 表示此通道没有 Schema
4+N topic String topic
4+N message_encoding String 编码
4+N metadata Map<string,string> channel的元信息

Channel record可以在summary section 中重复出现

Message(op=0x05)

Message 记录channel上的一条带时间戳的消息
消息的encoding和schema必须与其channel id对应的channel记录一致

Bytes Name Type Description
2 channel_id uint16 channel_id
4 sequence uint32 用于检测消息缺失的可选消息计数器。如果中间件发布端提供序列号,可以直接使用;也可以由录制器分配序列号。如果工作流程不需要此功能,则设置为0
8 log_time Timestamp 消息被记录的时间
8 publish_time Timestamp 消息反而不的时间。如何不可用,必须设置为log_time
N data Bytes 消息数据,应根据所属channel的schema的encoding 解码

Chunk(op=0x06)

Chunk 包含一批记录。读取器应能够处理 Chunk 中的 Schema、Channel 和 Message 记录;未来的规范变更可能允许其他记录。Chunk 中也可以包含私有记录。
Chunk 中的这批记录可以压缩,也可以不压缩。
Chunk 中的所有消息,都必须引用文件中此前已经记录的channel。对应的通道记录可以位于:

  • 更早的Chunk中;
  • 当前Chunk中更早的位置;
  • 数据区中更早的位置;
Bytes Name Type Description
8 message_start_time Timestamp Chunk 中最早的消息log_time,没有则为0
8 message_end_time Timestamp Chunk中最晚的消息log_time,没有消息则为0
8 uncompressed_size uint64 records 未压缩的大小
4 uncompressed_crc uint32 未压缩的records的crc32校验值。0表示不校验
4+N compression String 压缩算法 如zstd、ls4、"" 空表示不压缩
8+N records uint64 length-prefixed Bytes 重复的序列 <record type><record content length><record content>. 使用compression中的压缩算法压缩

Message Index(op=0x07)

Message Index 记录允许读取器根据时间戳,定位 Chunk 内的单条消息记录。
每个 Chunk 后面紧接着一组 Message Index 记录。对于 Chunk 内出现过消息的每一个channel,这组记录中必须恰好有一条对应的 Message Index 记录。

Bytes Name Type Description
2 channel_id uint16 channel id
4+N Array<Tuple<Timestamp,uint64>> 数组,每个元素包含一条消息记录的 log_time 和偏移量。偏移量相对于未压缩的 Chunk 数据起始位置

Chunk 之外的消息无法建立索引

Chunk Index(op=0x08)

Chunk Index 记录包含某条 Chunk 记录及其关联的 Message Index 记录的位置。
文件中的每个 Chunk 都有一条对应的 Chunk Index 记录。

Bytes Name Type Description
8 message_start_time Timestamp Chunk中最早的消息的log_time,没有则为0
8 message_end_time Timestamp Chunk中最晚的消息的log_time,没有则为0
8 chunk_start_offset uint64 从文件起始位置到Chunk记录的偏移量
8 chunk_lenght uint64 Chunk record的字节长度,包含opcode和长度前缀
4+N message_index_offsets Map<uint16,uint64> 从 Channel ID 到对应 Message Index 记录偏移量的映射。这些消息索引记录位于 Chunk 之后,偏移量相对于文件起始位置。空映射表示没有可用的消息索引
8 message_index_length uint64 Chunk 后后面所有Message Index记录的总长度
4+N compression String Chunk 内使用的压缩格式,参考公认的压缩格式,此字段应与对应的Chunk记录中的值一致
8 compressed_size uint64 Chunk的records字段的大小
8 uncompressed_size uint64 Chunk的records字段未压缩的大小。此字段应与对应Chunk记录中的值一致

对于由Chunk Index记录建立索引的Chunk,其中所有消息所需的Scheme和Channel记录都必须存在于Summary section中
为什么? 使用索引的文件读取器,通常需要快速随机访问指定时间戳的消息。解码 Message 记录的数据之前,必须先取得 Channel 记录。如果没有便于访问的 Channel 记录副本,读取器就必须从文件开头搜索 Channel 记录,从而降低随机访问读取性能。
Chunk Index中记录了Chunk的offset和Message Index offset, 从Chunk的offset可以按顺序读取Chunk及其中的Message, 从Message Index可以按时间戳读取需要的Message

Attachment(op=0x09)

Attachment 记录包含辅助资料,例如文本、核心转储、标定数据或其他任意数据。
Attachment 记录不得出现在 Chunk 内部。

Bytes Name Type Description
8 log_time Timestamp 附件被记录的时间
8 create_time Timestamp 创建时间,如何不可用,必须设置为0
4+N name String 名称
4+N media_type String 媒体类型,如 "text/plain"
8+N data 带uint64长度前缀的Bytes 附件数据
4 crc uint32 此记录中前面各字段的CRC32校验值,为0表示不应进行CRC校验

Metadata(op=0x0C)

Metadata记录以键值对形式包含任意用户数据

Bytes Name Type Description
4+N name String
4+N metadata Map<string,string>

Data End 数据结束区标识(op=0x0F)

为什么? 从头到尾读取文件时,由于某些记录(例如 Channel)可能作为摘要数据重复出现,因此难以明确区分数据区何时结束、摘要区何时开始。Data End 记录提供了明确的边界,表示数据区已经结束。

Bytes Name Type Description
4 data_section_crc uint32 从文件开头到 DataEnd 记录之前的所有字节的 CRC32 校验值,为0表示未提供CRC32

Attachment Index 附件索引(op=0x0A)

Attachement Index 记录包含附件在文件中的位置
文件中的每条Attachment记录都有一条对应的Attachment Index记录

Bytes Name Type Description
8 offset uint64 从文件起始文职到Attachment记录的字节偏移量
8 length uint64 Attachment 记录的字节长度,包含操作吗和长度前缀
8 log_time Timestamp 附件被记录的时间
8 create_time Timestamp 附件创建的时间,如果不可用,必须设置为0
8 data_size uint64
4+N name String
4+N media_type String 附件的媒体类型,如 "text/plain"

Metadata Index(op=ox0D)

Metadata Index记录包含某条Metadata记录在文件中的位置

Bytes Name Type Description
8 offset uint64 从文件起始位置到Metadata记录的字节偏移量
8 lenght uint64 该记录的总字节长度,包含opcode和长度前缀
4+N name String Metadata的名称

Statistics 统计信息(op=0x0B)

Statistics记录包含已记录数据的汇总信息
Statistics记录是可选的,但文件中应最多包含一条

Bytes Name Type Description
8 message_count uint64
2 schema_count uint64 文件中不同Schema ID的数量,不包括0
4 channel_count uint32 不同Channel ID的数量
4 attachment_count uint32
4 metadata_count uint32
4 chunk_count uint32
8 message_start_time Timestamp 文件中最早的消息log_time,没有消息则为0
8 message_end_time Timestamp 文件中最晚的消息log_time,没有消息则为0
4+N channel_message_counts Map<uint16,uint64> 从Channel ID到该通道消息总数的映射,空映射表示未提供此统计信息

当 Statistics 记录的 channel_message_counts 非空时,Summary section必须包含所有 Channel 记录的副本,并且这些 Channel 记录必须出现在 Statistics 记录之前。
为什么? 工具的典型用途是列出文件中存储的消息类型和数量。如果没有便于访问的 Channel 记录副本,工具就必须线性扫描文件以查找 Channel 记录,才能显示文件中有哪些消息类型。

Summary Offset(op=0x0E)

Summary Offset 记录包含Summary section内记录的位置
每条Summary Offset记录对应一组具有相同opcode的Summary records

Bytes Name Type Description
1 group_opcode uint8 此组中所有记录的操作码
8 group_start uint64 从文件起始位置到此组第一条记录的字节偏移量
8 group_length uint64 此组所有记录的总字节长度

序列化(Serialization)

固定宽度类型

多字节整数uint16、uint32、uint64使用小端字节序序列化

String:字符串

字符串序列化为一个uint32字节长度,后跟字符串数据。字符串数据必须是有效的UTF-8

<字节长度><UTF-8字节>

Bytes:字节序列

Bytes是一段字节序列,没有其他额外要求

<字节>

tuple<first_type,second_type> 二元组

Tupel 表示一对值

  • 第一个值的类型是first_type
  • 第二个值的类型是second_type
    序列化时,先序列化第一个值,再序列化第二个值
<第一个值><第二个值>

如 Tuple<uint8,uint32>

<uint8><uint32>

如 Tuple<uint16, string>

<uint16><string>
展开后为:
<uint16><uint32><UFT-8字节>

Array<arra_type>数组

数组序列化为一个uint32字节长度,后跟序列化后的数组元素

<字节长度><序列化元素><序列化元素>...

uint64数组表示为Array<uint64>,其序列化形式为:

<字节长度><uint64><uint64>...

由于数组使用uint32类型的字节长度前缀,序列化后所有数组元素的总大小不能超过4,294,967,295 字节

Timestamp:时间戳

使用uint64表示从用户约定的时间起点开始经过的纳秒数,例如Unix纪元起点、机器人启动时间等

Map<key_time,value_type>

序列化为一个uint32字节长度,后跟序列化的键值条目。键和值分别按照key_type和value_type规则序列化

<字节长度><键><值><键><值>

Map<string,string>的序列化形式

<字节长度><uint32 键长度><UTF-8键字节><uint32值长度><UTF-8值字节>...

包含重复键的序列化数据可能导致不确定的解码结果

示例(Diagrams)

以下示意图展示了各种 MCAP 文件结构。

空文件

最小的有效MCAP文件,没有数据

[Header]
[Footer]

单个消息

[Header]
[Schema A]
[Channel 1(A)]
[Message on Channel 1]
[Footer]

单个附件

[Header]
[Attachment]
[Footer]

多条消息

[Header]
[Schema A]
[Channel 1(A)]
[Channel 1(B)]
[Message on 1]
[Message on 1]
[Message on 2]
[Schema B]
[Channel 3(B)]
[Attachment]
[Message on 3]
[Message on 1]
[Footer]

包含chunks的消息

写入器可以选择将消息放入 Chunk,以便压缩记录数据。此 MCAP 文件不使用任何索引记录。

[Header]
[Chunk]
    [Schema A]
    [Channel 1(A)]
    [Channel 2(A)]
    [Message on 1]
    [Message on 1]
    [Message on 2]
[Attachment]
[Chunk]
    [Schema B]
    [Channel 3(B)]
    [Message on 3]
    [Message on 1]
[Footer]

多条消息包含Summary Data

[Header]
[Schema A]
[Channel 1(A)]
[Channel 2(A)]
[Message on 1]
[Message on 1]
[Message on 2]
[Schema B]
[Channel 3(B)]
[Attachment]
[Message on 3]
[Message on 1]
[Data End]
[Statistics]
[Schema A]
[Schema B]
[Channel 1]
[Channel 2]
[Channel 3]
[Summary Offset 0x01]
[Footer]

包含Chunk 索引的多条消息

[Header]
[Chunk A]
    [Schema A]
    [Channel 1(A)]
    [Channel 2(B)]
    [Message on 1]
    [Message on 1]
    [Message on 2]
[Message Index 1]
[Message Index 2]
[Attachment 1]
[Chunk B]
    [Schema B]
    [Channel 3(B)]
    [Message on 3]
    [Message on 1]
[Message Index 3]
[Messge Index 1]
[Data End]
[Schema A]
[Schema B]
[Channel 1]
[Channel 2]
[Channel 3]
[Chunk Index A]
[Chunk Index B]
[Attachment Index 1]
[Statistics]
[Summary Offset 0x01]
[Summary Offset 0x05]
[Summary Offset 0x07]
[Summary Offset 0x08]
[Footer]
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

相关阅读更多精彩内容

友情链接更多精彩内容