Prometheus源码学习(9) scrape-target

主要作用

scrape.Target 是一次抓取的具体对象，包含了抓取和抓取后存储所需要的全部信息。从 targetGroup.Group 到 scrape.Target 的转换过程如下：

1. targetsFromGroup函数遍历每个targetGroup.Group中的Target，合并targetGroup.Group的公共标签集（记为A）和这个Target本身的标签集（记为B）为标签集C。
2. populateLabels函数从C和*config.ScrapeConfig中创建Target。

以下是具体代码

target 定义

target 是 scrapePool 抓取的最终目标，描述一个 HTTP 或 HTTPS 端点。target 结构体内嵌了 MetricMetadataStore 接口类型的字段 metadata。

// TargetHealth describes the health state of a target.
type TargetHealth string

// The possible health states of a target based on the last performed scrape.
// 目标的三种健康状态值，基于最后一次抓取来设置。
const (
	HealthUnknown TargetHealth = "unknown"
	HealthGood    TargetHealth = "up"
	HealthBad     TargetHealth = "down"
)

// Target refers to a singular HTTP or HTTPS endpoint.
type Target struct {
	// Labels before any processing.
	// 未经处理的抓取到的原始标签集。
	discoveredLabels labels.Labels
	// Any labels that are added to this target and its metrics.
	// 经过 relabel 处理后的标签集，会记录进 TSDB。
	labels labels.Labels
	// Additional URL parameters that are part of the target URL.
	// 目标 URL 的额外参数。
	params url.Values

	// 读写锁保护下面的变量。
	mtx                sync.RWMutex
	// 最后一次抓取的错误值。
	lastError          error
	// 最后一次抓取的时间。
	lastScrape         time.Time
	// 最后一次抓取的耗时。
	lastScrapeDuration time.Duration
	// 目标的健康状态。
	health             TargetHealth
	// 标签的元数据。
	metadata           MetricMetadataStore
}

构造函数

// NewTarget creates a reasonably configured target for querying.
func NewTarget(labels, discoveredLabels labels.Labels, params url.Values) *Target {
	return &Target{
		labels:           labels,
		discoveredLabels: discoveredLabels,
		params:           params,
		health:           HealthUnknown,
	}
}

元数据及其存储

定义

// MetricMetadataStore represents a storage for metadata.
// MetricMetadataStore 接口代表元数据的存储。
type MetricMetadataStore interface {
	ListMetadata() []MetricMetadata
	GetMetadata(metric string) (MetricMetadata, bool)
	SizeMetadata() int
	LengthMetadata() int
}

// MetricMetadata is a piece of metadata for a metric.
// MetricMetadata 是一个指标的元数据。
// 包括指标名、指标类型、帮助信息（这三项在用客户端写观测指标时都要写）
// 和指标单位。
type MetricMetadata struct {
	Metric string
	Type   textparse.MetricType
	Help   string
	Unit   string
}

获取元数据

target 有 MetadataList()、MetadataSize()、MetadataLength() 和 Metadata() 方法，获取元数据的一些信息，这些方法内部就是加读锁调用 metadata 字段的相对应的方法。

设置元数据

参数是个接口类型，也就是实现了接口方法的结构体。

func (t *Target) SetMetadataStore(s MetricMetadataStore) {
	t.mtx.Lock()
	defer t.mtx.Unlock()
	t.metadata = s
}

hash 方法

用于得到一个目标的唯一标识。FVN-1a 是一个简单的非加密哈希算法，性能较高，碰撞率较低。该方法用目标的标签集的哈希值和目标的端点 URL 作为参数计算哈希值，其中标签集的哈希值使用 xxHash 算法。

// hash returns an identifying hash for the target.
func (t *Target) hash() uint64 {
	h := fnv.New64a()
	//nolint: errcheck
	h.Write([]byte(fmt.Sprintf("%016d", t.labels.Hash())))
	//nolint: errcheck
	h.Write([]byte(t.URL().String()))

	return h.Sum64()
}

offset 方法

得到距离目标开始下一次抓取循环的时间。参数中包含一个随机数，用于打散抓取开始时间，均匀化 Prometheus 的负载。

获取/设置标签集的方法

Labels()、DiscoveredLabels()、SetDiscoveredLabels(l labels.Labels) 分别用于获取目标的非元信息（不以“————”开头）标签集、relabel 前的原始标签集和设置 relabel 前的原始标签集。需要注意的是 Labels() 方法没有加锁。

URL() 方法组装 net/url.URL

// URL returns a copy of the target's URL.
func (t *Target) URL() *url.URL {
	params := url.Values{}

	for k, v := range t.params {
		params[k] = make([]string, len(v))
		copy(params[k], v)
	}
	// 将 url 参数相关的标签添加到参数中
	for _, l := range t.labels {
		if !strings.HasPrefix(l.Name, model.ParamLabelPrefix) {
			continue
		}
		ks := l.Name[len(model.ParamLabelPrefix):]

		if len(params[ks]) > 0 {
			params[ks][0] = l.Value
		} else {
			params[ks] = []string{l.Value}
		}
	}

	return &url.URL{
		Scheme:   t.labels.Get(model.SchemeLabel),
		Host:     t.labels.Get(model.AddressLabel),
		Path:     t.labels.Get(model.MetricsPathLabel),
		RawQuery: params.Encode(),
	}
}

Report() 设置最后一次抓取的结构体字段值

// Report sets target data about the last scrape.
func (t *Target) Report(start time.Time, dur time.Duration, err error) {
	t.mtx.Lock()
	defer t.mtx.Unlock()

	if err == nil {
		t.health = HealthGood
	} else {
		t.health = HealthBad
	}

	t.lastError = err
	t.lastScrape = start
	t.lastScrapeDuration = dur
}

LastError()、LastScrape()、LastScrapeDuration()、Health() 方法加读锁获取结构体最后一次抓取的错误、最后一次抓取的时间、最后一次抓取的耗时和最后一次抓取目标的状态字段。

Targets

是一个实现了 sort 接口的 Taget 指针切片，排序依据是 URL 字符串。

// Targets is a sortable list of targets.
type Targets []*Target

func (ts Targets) Len() int           { return len(ts) }
func (ts Targets) Less(i, j int) bool { return ts[i].URL().String() < ts[j].URL().String() }
func (ts Targets) Swap(i, j int)      { ts[i], ts[j] = ts[j], ts[i] }

limitAppender 结构体限制一次批量追加的样本数。

// limitAppender limits the number of total appended samples in a batch.
type limitAppender struct {
	storage.Appender

	limit int
	i     int
}

*limitAppender 的 Add 和 AddFast 方法向存储追加时间序列样本，超过限制数量将返回错误。后面读到存储部分再具体分析。

timeLimitAppender 结构体是限制插入时间的，如果要追加的样本时间戳超过限制就返回错误。

populateLabels 函数从给定的标签集和抓取配置中构造一个标签集。返回的第二个值是 relabel 之前的标签集。如果目标在 rebalel 期间被丢弃，就返回 relabel 之前的原始标签集。

// populateLabels builds a label set from the given label set and scrape configuration.
// It returns a label set before relabeling was applied as the second return value.
// Returns the original discovered label set found before relabelling was applied if the target is dropped during relabeling.
func populateLabels(lset labels.Labels, cfg *config.ScrapeConfig) (res, orig labels.Labels, err error) {
	// Copy labels into the labelset for the target if they are not set already.
	scrapeLabels := []labels.Label{
		{Name: model.JobLabel, Value: cfg.JobName},
		{Name: model.MetricsPathLabel, Value: cfg.MetricsPath},
		{Name: model.SchemeLabel, Value: cfg.Scheme},
	}
	lb := labels.NewBuilder(lset)

	// 如果参数标签集 lset 中不含有 job、metricPath 和 scheme 标签就把它们添加进去。
	for _, l := range scrapeLabels {
		if lv := lset.Get(l.Name); lv == "" {
			lb.Set(l.Name, l.Value)
		}
	}
	// Encode scrape query parameters as labels.
	// 添加 url 参数标签。
	for k, v := range cfg.Params {
		if len(v) > 0 {
			lb.Set(model.ParamLabelPrefix+k, v[0])
		}
	}

	// relabel 之前的标签集。
	preRelabelLabels := lb.Labels()
	// 应用 relabel。
	lset = relabel.Process(preRelabelLabels, cfg.RelabelConfigs...)

	// Check if the target was dropped.
	// 如果 relabel 把这个标签集丢弃了就返回 relabel 之前的标签集
	if lset == nil {
		return nil, preRelabelLabels, nil
	}
	// 如果 relabel 后 __address__ 标签没有了就返回错误。
	if v := lset.Get(model.AddressLabel); v == "" {
		return nil, nil, errors.New("no address")
	}

	lb = labels.NewBuilder(lset)

	// addPort checks whether we should add a default port to the address.
	// If the address is not valid, we don't append a port either.
	// addPort 检查是否需要为地址添加默认端口。如果地址不合法，也不添加端口。
	addPort := func(s string) bool {
		// If we can split, a port exists and we don't have to add one.
		// 有端口就不用添加了。
		if _, _, err := net.SplitHostPort(s); err == nil {
			return false
		}
		// If adding a port makes it valid, the previous error
		// was not due to an invalid address and we can append a port.
		// 如果添加以后不合法就可以添加。
		_, _, err := net.SplitHostPort(s + ":1234")
		return err == nil
	}
	addr := lset.Get(model.AddressLabel)
	// If it's an address with no trailing port, infer it based on the used scheme.
	// __address__ 标签如果没有端口就根据 http 或 https 推断一个默认值。
	if addPort(addr) {
		// Addresses reaching this point are already wrapped in [] if necessary.
		switch lset.Get(model.SchemeLabel) {
		case "http", "":
			addr = addr + ":80"
		case "https":
			addr = addr + ":443"
		default:
			return nil, nil, errors.Errorf("invalid scheme: %q", cfg.Scheme)
		}
		lb.Set(model.AddressLabel, addr)
	}

	// 检查地址标签的值是否是合法地址。
	if err := config.CheckTargetAddress(model.LabelValue(addr)); err != nil {
		return nil, nil, err
	}

	// Meta labels are deleted after relabelling. Other internal labels propagate to
	// the target which decides whether they will be part of their label set.
	// relabel 以后删除 __meta_ 开头的标签。其他的内部标签保留。
	for _, l := range lset {
		if strings.HasPrefix(l.Name, model.MetaLabelPrefix) {
			lb.Del(l.Name)
		}
	}

	// Default the instance label to the target address.
	// instance 标签为空就设置为地址。
	if v := lset.Get(model.InstanceLabel); v == "" {
		lb.Set(model.InstanceLabel, addr)
	}

	// 最终标签集
	res = lb.Labels()
	// 最后检查一遍，标签值必须都是合法的 UTF8 字符。
	for _, l := range res {
		// Check label values are valid, drop the target if not.
		if !model.LabelValue(l.Value).IsValid() {
			return nil, nil, errors.Errorf("invalid label value for %q: %q", l.Name, l.Value)
		}
	}
	return res, preRelabelLabels, nil
}

targetGroup.Group 到 Target 的转换

targetGroup.Group 在 prometheus/discovery/targetgroup/targetgroup.go 中，Target 在 prometheus/scrape/target.go 中。这是从服务发现到抓取目标的转换。

// targetsFromGroup builds targets based on the given TargetGroup and config.
func targetsFromGroup(tg *targetgroup.Group, cfg *config.ScrapeConfig) ([]*Target, error) {
	targets := make([]*Target, 0, len(tg.Targets))

	for i, tlset := range tg.Targets {
		// tlset 是这个目标独有的标签，tg.Labels 是这个 group 公共的标签。
		lbls := make([]labels.Label, 0, len(tlset)+len(tg.Labels))

		for ln, lv := range tlset {
			lbls = append(lbls, labels.Label{Name: string(ln), Value: string(lv)})
		}
		for ln, lv := range tg.Labels {
			if _, ok := tlset[ln]; !ok {
				lbls = append(lbls, labels.Label{Name: string(ln), Value: string(lv)})
			}
		}

		lset := labels.New(lbls...)

		lbls, origLabels, err := populateLabels(lset, cfg)
		if err != nil {
			return nil, errors.Wrapf(err, "instance %d in group %s", i, tg)
		}
		if lbls != nil || origLabels != nil {
			targets = append(targets, NewTarget(lbls, origLabels, cfg.Params))
		}
	}
	return targets, nil
}

习得

1. FVN-1a 是一个简单的非加密哈希算法，性能好，哈希碰撞概率极低。
2. nolint:errCheck 用于提示 IDE 忽略错误检查。
3. 应该利用 instance 标签，为其设置有意义的值，例如主机名，这样可以降低标签基数。