Prometheus TSDB文件格式-index

Prometheus TSDB文件格式-index

存储目录

如下所示为Prometheus/TSDB存储目录结构：

drwxrwxr-x 3 service service 4096 Nov  9 12:08 01EPNJJA12FXV9YDYM3MBNE3HP
drwxrwxr-x 3 service service 4096 Nov 10 10:10 01EPQY3Z6AJ700B9DVFWSG0FSD
drwxrwxr-x 3 service service 4096 Nov 11 05:26 01EPSZZJ29EQZ9EQ1Z15EGGRJM
drwxrwxr-x 3 service service 4096 Nov 11 15:30 01EPV3C56BA53YZ4H28PQHBWQV
drwxrwxr-x 3 service service 4096 Nov 11 16:30 01EPV6T1RWCFQ6T4RVGAN2G7BG
drwxrwxr-x 3 service service 4096 Nov 11 17:11 01EPV8V50SMAJ617XQKWZ344HD
drwxrwxr-x 3 service service 4096 Nov 11 17:30 01EPVA7WJ5DXTV6FR06VJ0CT40
-rw------- 1 service service    7 Dec 13  2019 lock
-rw-rw-r-- 1 service service  200 Sep 26  2019 schema
drwxrwxr-x 2 service service 4096 Nov 11 17:42 wal

其中类似'01EPVA7WJ5DXTV6FR06VJ0CT40'的目录为其中一个block。如下所示为block的目录结构：

drwxrwxr-x 2 service service      4096 Nov 11 17:30 chunks
-rw-rw-r-- 1 service service 104684896 Nov 11 17:30 index
-rw-rw-r-- 1 service service       302 Nov 11 17:30 meta.json
-rw-rw-r-- 1 service service         9 Nov 11 17:30 tombstones

其中meta.json文件描述概要信息，一看就懂，不必多言：

{
	"ulid": "01EPVA7WJ5DXTV6FR06VJ0CT40",
	"minTime": 1605081600,
	"maxTime": 1605085200,
	"stats": {
		"numSamples": 1359295562,
		"numSeries": 441979,
		"numChunks": 11207472
	},
	"compaction": {
		"level": 1,
		"sources": [
			"01EPVA7WJ5DXTV6FR06VJ0CT40"
		]
	},
	"version": 2,
	"numChunkFile": 3
}

其中index文件用于定位和查询指标数据，它是本文的主角。

index磁盘格式

首先，声明一下index磁盘格式不等于index到内存里的格式，当然也差不太多。
如下所示为每个block目录下面必有的index文件磁盘格式，index以TOC（table of contents）目录表作为结尾。
TOC也作为index文件的入口：总是从文件尾部倒数N个字节读取TOC开始干活。

┌────────────────────────────┬─────────────────────┐
│ magic(0xBAAAD700) <4b>     │ version(1) <1 byte> │
├────────────────────────────┴─────────────────────┤
│ ┌──────────────────────────────────────────────┐ │
│ │                 Symbol Table                 │ │
│ ├──────────────────────────────────────────────┤ │
│ │                    Series                    │ │
│ ├──────────────────────────────────────────────┤ │
│ │                 Label Index 1                │ │
│ ├──────────────────────────────────────────────┤ │
│ │                      ...                     │ │
│ ├──────────────────────────────────────────────┤ │
│ │                 Label Index N                │ │
│ ├──────────────────────────────────────────────┤ │
│ │                   Postings 1                 │ │
│ ├──────────────────────────────────────────────┤ │
│ │                      ...                     │ │
│ ├──────────────────────────────────────────────┤ │
│ │                   Postings N                 │ │
│ ├──────────────────────────────────────────────┤ │
│ │               Label Offset Table             │ │
│ ├──────────────────────────────────────────────┤ │
│ │             Postings Offset Table            │ │
│ ├──────────────────────────────────────────────┤ │
│ │                      TOC                     │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

上述主要部分（section）之间，在写入index时会追加一些padding字节用于对齐，在读取时，需要跳过那些不在len里的值为0的padding字节。
大部分section都以len字段开始，len指定了该section有效的字节数，在这些有效数据之后，追加了一个checksum，它基于len的有效数据进行CRC32计算。

Symbol Table 字符串符号表

Symbol Table保存了所有sereis的label用到的字符串，并做了排序和去重。在后续的section中，将通过引用字符串的序号，达到降低index空间的目的。
Symbol Table包含一个序列的字符串条目，每个条目包括一个字符串原始字节的长度（len)和字符串实际字节两个部分。字符串的格式是UTF-8，并且按字典序升序排序，通过条目序列的索引号对其进行引用。

┌────────────────────┬─────────────────────┐
│ len <4b>           │ #symbols <4b>       │
├────────────────────┴─────────────────────┤
│ ┌──────────────────────┬───────────────┐ │
│ │ len(str_1) <uvarint> │ str_1 <bytes> │ │
│ ├──────────────────────┴───────────────┤ │
│ │                . . .                 │ │
│ ├──────────────────────┬───────────────┤ │
│ │ len(str_n) <uvarint> │ str_n <bytes> │ │
│ └──────────────────────┴───────────────┘ │
├──────────────────────────────────────────┤
│ CRC32 <4b>                               │
└──────────────────────────────────────────┘

Series 时序数据索引表

该section包含了所有的series时序数据，包括sereis的label sets和其block内的chunks信息，series按label sets的字典序排序。
每个series按16字节对齐，series的ID=offset/16，后面section通过ID对该series进行引用。因此series的ID列表和sereis按字典序排序后的列表一一对应。

┌───────────────────────────────────────┐
│ ┌───────────────────────────────────┐ │
│ │   series_1                        │ │
│ ├───────────────────────────────────┤ │
│ │                 . . .             │ │
│ ├───────────────────────────────────┤ │
│ │   series_n                        │ │
│ └───────────────────────────────────┘ │
└───────────────────────────────────────┘

每个sereis section以len开始，以CRC32结尾。数据区首先是一个8字节数值标识labels的个数，然后是所有的labels，每个label包括name和value的ID号（对Symbol Table的引用）。该series的labels对按字典序排序。
紧随label表格之后是对chunk的索引表，首先是一个8字节数值标识chunk的个数，然后是所有的chunks，每个chunk条目包括：chunk的最小时间mint和最大时间maxt，以及一个8字节数值指向chunk文件的位置position。mint即该series在该chunk里第一个sample的时间戳，maxt即该series在该chunk里最后一个sample的时间戳。
只有第一个mint保存的是原始时间戳值，后续的maxt以及后续chunk条目里的mint和maxt都是通过与前一个计算的差值进行保存。同样的差值编码也用于chunk条目的positon数值存储。

┌──────────────────────────────────────────────────────────────────────────┐
│ len <uvarint>                                                            │
├──────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │                     labels count <uvarint64>                         │ │
│ ├──────────────────────────────────────────────────────────────────────┤ │
│ │              ┌────────────────────────────────────────────┐          │ │
│ │              │ ref(l_i.name) <uvarint32>                  │          │ │
│ │              ├────────────────────────────────────────────┤          │ │
│ │              │ ref(l_i.value) <uvarint32>                 │          │ │
│ │              └────────────────────────────────────────────┘          │ │
│ │                             ...                                      │ │
│ ├──────────────────────────────────────────────────────────────────────┤ │
│ │                     chunks count <uvarint64>                         │ │
│ ├──────────────────────────────────────────────────────────────────────┤ │
│ │              ┌────────────────────────────────────────────┐          │ │
│ │              │ c_0.mint <varint64>                        │          │ │
│ │              ├────────────────────────────────────────────┤          │ │
│ │              │ c_0.maxt - c_0.mint <uvarint64>            │          │ │
│ │              ├────────────────────────────────────────────┤          │ │
│ │              │ ref(c_0.data) <uvarint64>                  │          │ │
│ │              └────────────────────────────────────────────┘          │ │
│ │              ┌────────────────────────────────────────────┐          │ │
│ │              │ c_i.mint - c_i-1.maxt <uvarint64>          │          │ │
│ │              ├────────────────────────────────────────────┤          │ │
│ │              │ c_i.maxt - c_i.mint <uvarint64>            │          │ │
│ │              ├────────────────────────────────────────────┤          │ │
│ │              │ ref(c_i.data) - ref(c_i-1.data) <varint64> │          │ │
│ │              └────────────────────────────────────────────┘          │ │
│ │                             ...                                      │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ CRC32 <4b>                                                               │
└──────────────────────────────────────────────────────────────────────────┘

注：每个block里会有多个chunk，每个series条目针对每个chunk都有且只有一个位置索引，由此也可以知道单个series在同一个chunk里的数据是连续存储的。

Label index 标签索引表

Label索引表保存了每个label name对应的values列表，可用于/api/v1/label/{name}/values接口快速查询。
每个Label索引section同样以len开始，以CRC32结束。数据区首先是字段name标识label name，然后是字段entries标识label下面的value个数，他们都是4字节大小。
随后是所有的label value，每个value都是4字节，和name一样，都是对Symbol Table的字符串的引用ID。value列表按字典序升序排序。

┌───────────────┬────────────────┬────────────────┐
│ len <4b>      │ #names <4b>    │ #entries <4b>  │
├───────────────┴────────────────┴────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ ref(value_0) <4b>                           │ │
│ ├─────────────────────────────────────────────┤ │
│ │ ...                                         │ │
│ ├─────────────────────────────────────────────┤ │
│ │ ref(value_n) <4b>                           │ │
│ └─────────────────────────────────────────────┘ │
│                      . . .                      │
├─────────────────────────────────────────────────┤
│ CRC32 <4b>                                      │
└─────────────────────────────────────────────────┘

如下例所示，为一个简单的label name对应4个value：

┌────┬───┬───┬──────────────┬──────────────┬──────────────┬──────────────┬───────┐
│ 24 │ 1 │ 4 │ ref(value_0) | ref(value_1) | ref(value_2) | ref(value_3) | CRC32 |
└────┴───┴───┴──────────────┴──────────────┴──────────────┴──────────────┴───────┘

Label索引表每个name的长度不同，无法根据name快速定位到values在索引表的位置。该工作由Label offset table标签偏移表完成，该表包含了每个label name对应在Label索引表中的位置。

Postings 倒排索引表

Postings表保存了每个label pair对应的series列表，这些series里都包含改label pair。series列表按ID递增排序。
每个Postings section包含字段len，entries，series列表和CRC32。

┌────────────────────┬────────────────────┐
│ len <4b>           │ #entries <4b>      │
├────────────────────┴────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ ref(series_1) <4b>                  │ │
│ ├─────────────────────────────────────┤ │
│ │ ...                                 │ │
│ ├─────────────────────────────────────┤ │
│ │ ref(series_n) <4b>                  │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ CRC32 <4b>                              │
└─────────────────────────────────────────┘

同样，通过label pair快速索引到倒排索引表中位置的工作由Postings offset table倒排索引偏移表完成。

Label offset table 标签偏移表

该表保存了一系列label偏移条目，每个条目包含label name和指向Label索引表的位置信息。

┌─────────────────────┬──────────────────────┐
│ len <4b>            │ #entries <4b>        │
├─────────────────────┴──────────────────────┤
│ ┌────────────────────────────────────────┐ │
│ │  n = 1 <1b>                            │ │
│ ├──────────────────────┬─────────────────┤ │
│ │ len(name) <uvarint>  │ name <bytes>    │ │
│ ├──────────────────────┴─────────────────┤ │
│ │  offset <uvarint64>                    │ │
│ └────────────────────────────────────────┘ │
│                    . . .                   │
├────────────────────────────────────────────┤
│  CRC32 <4b>                                │
└────────────────────────────────────────────┘

注：该表里的label name是直接保存了原始字符串，而不是对Symbol table的引用。

Postings offset table 倒排索引偏移表

该表保存了一系列label pair条目，每个条目包含label name/value pair和指向Postings表的位置信息。该表在index读取时会部分导入到内存中。

┌─────────────────────┬──────────────────────┐
│ len <4b>            │ #entries <4b>        │
├─────────────────────┴──────────────────────┤
│ ┌────────────────────────────────────────┐ │
│ │  n = 2 <1b>                            │ │
│ ├──────────────────────┬─────────────────┤ │
│ │ len(name) <uvarint>  │ name <bytes>    │ │
│ ├──────────────────────┼─────────────────┤ │
│ │ len(value) <uvarint> │ value <bytes>   │ │
│ ├──────────────────────┴─────────────────┤ │
│ │  offset <uvarint64>                    │ │
│ └────────────────────────────────────────┘ │
│                    . . .                   │
├────────────────────────────────────────────┤
│  CRC32 <4b>                                │
└────────────────────────────────────────────┘

注：该表里的label name/value也是直接存储了原始字符串，而不是对Symbol table的引用。

TOC 目录表

TOC(table of contents)目录表保存了指向各个表的位置信息，如果值为0，则表示对应的表不存在，对应的数据查询返回为空。

┌─────────────────────────────────────────┐
│ ref(symbols) <8b>                       │
├─────────────────────────────────────────┤
│ ref(series) <8b>                        │
├─────────────────────────────────────────┤
│ ref(label indices start) <8b>           │
├─────────────────────────────────────────┤
│ ref(label offset table) <8b>            │
├─────────────────────────────────────────┤
│ ref(postings start) <8b>                │
├─────────────────────────────────────────┤
│ ref(postings offset table) <8b>         │
├─────────────────────────────────────────┤
│ CRC32 <4b>                              │
└─────────────────────────────────────────┘

参考

https://github.com/prometheus/prometheus/blob/master/tsdb/docs/format/index.md