VictorialMetrics存储原理之索引

curl -d "GOOG,1.23,4.56,NYSE" 'http://127.0.0.1:8480/insert/0/prometheus/api/v1/import/csv?format=2:metric:ask,3:metric:bid,1:label:ticker,4:label:market'

// lib/storage/tsid.go
// TSID 是一个时间序列的唯一 ID，实际上就是唯一标识一个时间序列的结构体。
//
// 时间序列会根据 TSID 进行排序。
//
// 除了 MetricID 之外其他属性都是可选的。 它们的存在仅仅是为了更好地对相关指标进行分组。
// 如果它们的含义与它们的命名不同，那也没关系。
type TSID struct {
    AccountID uint32
    ProjectID uint32 // 下面分析的时候可以暂时忽略这两个属性，用于多租户标识的属性

    // MetricGroupID（指标组ID）对于指定的(AccountID, ProjectID)必须是唯一的。
    //
    // Metric Group 包含具有相同名称的指标，例如 “memory_usage”、“http_requests”，但具有不同的标签。
    // 例如，下面的这些指标属于 memory_usage 这个指标组:
    //
    //   memory_usage{datacenter="foo1", job="bar1", instance="baz1:1234"}
    //   memory_usage{datacenter="foo1", job="bar1", instance="baz2:1234"}
    //   memory_usage{datacenter="foo1", job="bar2", instance="baz1:1234"}
    //   memory_usage{datacenter="foo2", job="bar1", instance="baz2:1234"}
    MetricGroupID uint64
  // JobID 是给定项目的单个作业（又名服务）的 ID。
    //
    // JobID 对于指定的(AccountID, ProjectID)必须是唯一的。
    //
    // 一个 Job 任务可能由多个实例组成。
    // See https://prometheus.io/docs/concepts/jobs_instances/ for details.
    JobID uint32
    // InstanceID 是实例（进程）ID，对于特定的(AccountID, ProjectID)必须是唯一的。
    InstanceID uint32
    // MetricID 是指标（时间序列）的唯一ID。
    //
    // 其他所有的 TSID 字段都可以通过 MetricID 获取。
    MetricID uint64
}

// lib/storage/raw_row.go
// rawRow 表示一个原始的时间序列行
type rawRow struct {  
   TSID TSID  // 时间序列ID 
   Timestamp int64  // 时间戳 
   Value float64  // 给定时间戳的时间序列值
   // PrecisionBits是要存储的值中的有效位数，可能值为 [1..64]
   // 1 表示最大. 50% error, 2 - 25%, 3 - 12.5%, 64 没有错误, i.e.   
   // 存储的值不会丢失精度
   PrecisionBits uint8  
}
// libe/storage/storage.go
// MetricRow 插入到存储中的指标
type MetricRow struct {  
   // MetricNameRaw 包含原始的指标名称，必须使用 metricne.UnmarshalRaw 对其进行解码。 
   MetricNameRaw []byte  
   Timestamp int64  
   Value     float64  
}

// app/vmstorage/transport/server.go
func (s *Server) processVMInsertConn(bc *handshake.BufferedConn) error {  
   return clusternative.ParseStream(bc, func(rows []storage.MetricRow) error {  
      vminsertMetricsRead.Add(len(rows))  
      return s.storage.AddRows(rows, uint8(*precisionBits))  
   }, s.storage.IsReadOnly)  
}

// lib/storage/storage.go
// AddRows 添加 mrs 集合到存储 s
func (s *Storage) AddRows(mrs []MetricRow, precisionBits uint8) error {  
   if len(mrs) == 0 {  
      return nil  
   }   
   // 限制可能向存储添加行的并发 goroutine 数量  
   // 当太多的 goroutine 调用 AddRows 时，这应该可以防止内存不足错误和 CPU 抖动。  
   select {  
   // 如果写入 channel 成功，说明并发小于 CPU 最大核数，然后就可以走插入逻辑  
   // 如果没写入成功（也就是满了），则执行default case  
   case addRowsConcurrencyCh <- struct{}{}:  
   default: // 如果插入 channel 失败，说明某个 insert 操作的协程被阻塞，这时需要通知 select 协程去让出。  
      atomic.AddUint64(&s.addRowsConcurrencyLimitReached, 1)  
      t := timerpool.Get(addRowsTimeout) // 获取一个30s超时的timer  
  
      // 数据摄取优先级高于并发搜索  
  
      // pacelimiter（步长限制器）中有个原子累加的变量，表示有多少个 insert 操作在等待  
      // 走到这里证明有一个 insert 操作被阻塞了，调用 Inc，表示需要（Search操作）等待  
      storagepacelimiter.Search.Inc()  
  
      select { // 写入不成功或者还未超时就会阻塞在这里了  
      // 在超时的30s时间内，尝试去写入 channel 队列  
      case addRowsConcurrencyCh <- struct{}{}:  
         timerpool.Put(t) // 把 timer 放回对象池，减少 GC         
         // 可以成功写入 channel 了，那么可以执行 insert 操作了，则执行限制器的 Dec 操作，减一  
         storagepacelimiter.Search.Dec()  
         // 当限制器的等待数量为0的时候，会调用 cond.Broadcast() 去通知 select 协程开始工作。  
      case <-t.C: // 到30s超时时间了  
         // 把 timer 放回对象池，减少 GC         timerpool.Put(t)  
         // 超时了那么当前的 insert 就报错了，等待的数量就可以减一了  
         storagepacelimiter.Search.Dec()  
         atomic.AddUint64(&s.addRowsConcurrencyLimitTimeout, 1)               // 记录下超时次数  
         atomic.AddUint64(&s.addRowsConcurrencyDroppedRows, uint64(len(mrs))) // 记录没有被插入成功的 mr 数量  
         // 等待了30秒仍然没有CPU资源，只能报错  
         return fmt.Errorf("cannot add %d rows to storage in %s, since it is overloaded with %d concurrent writers; add more CPUs or reduce load",  
            len(mrs), addRowsTimeout, cap(addRowsConcurrencyCh))  
      }  
   }  
  
   // 下面是插入逻辑  
   // 一次插入不要太大  
   var firstErr error  
   ic := getMetricRowsInsertCtx()  
   maxBlockLen := len(ic.rrs)  
   for len(mrs) > 0 {  
      mrsBlock := mrs  
      // 如果要插入的 mrs 超过了最大长度  
      if len(mrs) > maxBlockLen {  
         // 则先插入最大长度的 mrs         mrsBlock = mrs[:maxBlockLen]  
         // 剩下的 mrs 下次循环去处理  
         mrs = mrs[maxBlockLen:]  
      } else {  
         mrs = nil  
      }  
      // 执行真正的 add 操作  
      if err := s.add(ic.rrs, ic.tmpMrs, mrsBlock, precisionBits); err != nil {  
         if firstErr == nil {  
            firstErr = err  
         }  
         continue  
      }  
      // 记录下插入成功的 mrs 数量  
      atomic.AddUint64(&rowsAddedTotal, uint64(len(mrsBlock)))  
   }  
   // 放回对象池  
   putMetricRowsInsertCtx(ic)  
  
   <-addRowsConcurrencyCh // insert 逻辑执行完成后，出队  
  
   return firstErr  
}

// lib/storage/storage.go
func (s *Storage) add(rows []rawRow, dstMrs []*MetricRow, mrs []MetricRow, precisionBits uint8) error {  
   // 当前使用的索引
   idb := s.idb()  
   j := 0  
   var (  
      // 这些变量用于加速同一 metricName 的多个相邻行的批量导入。
      prevTSID          TSID  
      prevMetricNameRaw []byte  
   )  
   var pmrs *pendingMetricRows  
   // 获取该数据块的最小时间和最大时间
   minTimestamp, maxTimestamp := s.tb.getMinMaxTimestamps()  

   // 带有第几代索引信息的 TSID 对象
   var genTSID generationTSID  
  
   // 只返回第一个错误，因为它返回所有错误没有意义
   var firstWarn error  
   // 循环数据行，其实就是填充 rawRow 中的 TSID 数据
   for i := range mrs {  
      mr := &mrs[i]  
      if math.IsNaN(mr.Value) {  // 值为 NaN
         if !decimal.IsStaleNaN(mr.Value) {  
            // 跳过 Prometheus staleness 标记以外的 NaN
            // 因为底层编码不知道如何使用它们。
            continue  
         }  
      }  
      // 如果指标的时间戳小于最小的时间戳
      // 则跳过保留期外时间戳过小的行
      if mr.Timestamp < minTimestamp {  
         ......
         continue  
      }  
      // 同样跳过超过最大时间戳的数据
      if mr.Timestamp > maxTimestamp {  
         ...... 
         continue  
      }  
      dstMrs[j] = mr  
      r := &rows[j]  
      j++  
      r.Timestamp = mr.Timestamp  
      r.Value = mr.Value  
      r.PrecisionBits = precisionBits  
      // 快速路径 - 当前 mr 包含与前一 mr 相同的指标名称，因此它包含相同的 TSID。
      if string(mr.MetricNameRaw) == string(prevMetricNameRaw) {  
         // 当许多行包含相同的 MetricNameRaw 时，应在批量导入时触发此路径。   
         r.TSID = prevTSID  
         continue  
      }  
      // 判断 TSID 是否在缓存中（命中缓存）
      if s.getTSIDFromCache(&genTSID, mr.MetricNameRaw) {  
         r.TSID = genTSID.TSID  
         // 跳过该行，因为已超出唯一序列数的限制。
         if s.isSeriesCardinalityExceeded(r.TSID.MetricID, mr.MetricNameRaw) {  
            j--  
            continue  
         }  
         // 快速路径 - 给定 MetricNameRaw 的 TSID 已在缓存中找到，并且未删除。
         // 不需要检查 r.TSID.MetricID 是否已删除，因为 tsidCache 不包含已删除时间序列的 MetricName -> TSID 条目，可以查看 Storage.DeleteMetrics 的代码       
         prevTSID = r.TSID  // 设置前一个 TSID 的值
         prevMetricNameRaw = mr.MetricNameRaw  // 设置前一个 MetricNameRaw 的值

         // 找到的TSID不是当前代的索引（来自上一代缓存下来的索引）
         if genTSID.generation != idb.generation {  
            // 索引需要尝试使用该 TSID 重新填充当前代的索引数据
            // https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1401            
            created, err := idb.maybeCreateIndexes(&genTSID.TSID, mr.MetricNameRaw)  
            if err != nil {  
               return fmt.Errorf("cannot create indexes in the current indexdb: %w", err)  
            }  
            if created {  
               // 如果填充成功，则将当前的 TSID 设置为当前代索引
               genTSID.generation = idb.generation  
               // 重新将该 TSID -> MetricNameRaw 数据放回缓存，方便后面的序列处理
               s.putTSIDToCache(&genTSID, mr.MetricNameRaw)  
            }  
         }  
         continue  
      }  

      // 慢速路径 - 缓存中缺少TSID
      // 在下面的循环中推迟搜索
      j--  
      if pmrs == nil {  
         // 初始化 pendingMetricRows
         pmrs = getPendingMetricRows()  
      }  
      // 将 mr 数据添加到 pendingMetricRows 中去待处理
      if err := pmrs.addRow(mr); err != nil { 
         // 错误时不要停止添加数据 - 只需跳过无效行即可。 
         // 这保证了无效行不会阻止将有效行添加到存储中去。    
         if firstWarn == nil {  
            firstWarn = err  
         }  
         continue  
      }  
   }  
   // 有指标的 TSID 没有在缓存中（上面的慢速路径）
   if pmrs != nil {   
      // 按指标名称对 pendingMetricRows 进行排序，以便通过下面循环中的 “is” 加快搜索速度。
      pendingMetricRows := pmrs.pmrs  
      sort.Slice(pendingMetricRows, func(i, j int) bool {  
         return string(pendingMetricRows[i].MetricName) < string(pendingMetricRows[j].MetricName)  
      })  
      // 
      is := idb.getIndexSearch(0, 0, noDeadline)  
      prevMetricNameRaw = nil  // 接收前一个 MetricNameRaw
      var slowInsertsCount uint64  
      for i := range pendingMetricRows {  
         pmr := &pendingMetricRows[i]  
         mr := pmr.mr  // MetricRaw 
         dstMrs[j] = mr  
         r := &rows[j]  
         j++  
         r.Timestamp = mr.Timestamp  
         r.Value = mr.Value  
         r.PrecisionBits = precisionBits  
         // 快速路径 - 当前 mr 包含与前一个 mr 相同的指标名称，因此它包含相同的 TSID。
         if string(mr.MetricNameRaw) == string(prevMetricNameRaw) {  
            // 当许多行包含相同的 MetricNameRaw 时，在批量导入时会触发该路径。           
            r.TSID = prevTSID  
            if s.isSeriesCardinalityExceeded(r.TSID.MetricID, mr.MetricNameRaw) {  
               // 跳过该行，因为已超出唯一序列数的限制
               j--  
               continue  
            }  
            continue  
         }  
         // 慢速路径
         slowInsertsCount++  // 记录慢插入次数
         // 通过 MetricName 去获取（没有就创建）TSID 数据
         if err := is.GetOrCreateTSIDByName(&r.TSID, pmr.MetricName); err != nil {
            if firstWarn == nil {  
               firstWarn = fmt.Errorf("cannot obtain or create TSID for MetricName %q: %w", pmr.MetricName, err)  
            }  
            j--  
            continue  
         }  
         // 设置 genTSID 为当前生成的 TSID
         genTSID.generation = idb.generation  
         genTSID.TSID = r.TSID  
         // 返回缓存
         s.putTSIDToCache(&genTSID, mr.MetricNameRaw) 
         // 缓存当前的 TSID 和 MetricNameRaw，方便下一条序列快速处理
         prevTSID = r.TSID  
         prevMetricNameRaw = mr.MetricNameRaw  
         if s.isSeriesCardinalityExceeded(r.TSID.MetricID, mr.MetricNameRaw) {  
            // 跳过该行，因为已超出唯一序列数的限制
            j--  
            continue  
         }  
      }  
      // 回收对象
      idb.putIndexSearch(is)  
      putPendingMetricRows(pmrs)  
      atomic.AddUint64(&s.slowRowInserts, slowInsertsCount)  
   } 
   // 提示错误信息 
   if firstWarn != nil {  
      logger.WithThrottler("storageAddRows", 5*time.Second).Warnf("warn occurred during rows addition: %s", firstWarn)  
   }  
   dstMrs = dstMrs[:j]  
   rows = rows[:j]  

   // TSID 填充完成，可以插入数据了
   var firstError error  
   if err := s.tb.AddRows(rows); err != nil {  
      firstError = fmt.Errorf("cannot add rows to table: %w", err)  
   }  
   if err := s.updatePerDateData(rows, dstMrs); err != nil && firstError == nil {  
      firstError = fmt.Errorf("cannot update per-date data: %w", err)  
   }  
   if firstError != nil {  
      return fmt.Errorf("error occurred during rows addition: %w", firstError)  
   }  
   return nil  
}