github.com/grafana/synthetic-monitoring-agent@v0.64.2/pkg/collector/collector.go

// Package collector exposes the agent's normal single-execution telemetry
// pipeline to callers that supply a prober. It contains no scheduling,
// persistence, virtual-time execution, or scenario semantics. The context
// deadline remains a real wall-clock deadline; callers generating logical
// history are responsible for resolving their simulated outcome before
// collection.
package collector

import (
	"context"
	"io"
	"time"

	logproto "github.com/grafana/loki/pkg/push"
	"github.com/grafana/synthetic-monitoring-agent/internal/model"
	internalprober "github.com/grafana/synthetic-monitoring-agent/internal/prober"
	internallogger "github.com/grafana/synthetic-monitoring-agent/internal/prober/logger"
	"github.com/grafana/synthetic-monitoring-agent/internal/pusher"
	"github.com/grafana/synthetic-monitoring-agent/internal/scraper"
	"github.com/grafana/synthetic-monitoring-agent/internal/telemetry"
	sm "github.com/grafana/synthetic-monitoring-agent/pkg/pb/synthetic_monitoring"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/prometheus/prompb"
	"github.com/rs/zerolog"
)

type TimeSeries = []prompb.TimeSeries
type Streams = []logproto.Stream

// Logger is the logging surface available to an injected Probe.
type Logger interface {
	Log(keyvals ...any) error
}

// Probe performs one check execution and registers its metrics and logs.
// It matches the agent's prober contract without exposing internal packages.
type Probe interface {
	Name() string
	Probe(ctx context.Context, target string, registry *prometheus.Registry, logger Logger) (bool, float64)
}

// Option configures a Collector.
type Option func(*options)

type options struct {
	labelMode sm.LabelMode
}

// WithLabelMode configures how user-defined check and probe labels are shaped.
// Collectors default to LABEL_MODE_PREFIXED, matching the protobuf default used
// by the agent.
func WithLabelMode(mode sm.LabelMode) Option {
	return func(opts *options) {
		opts.labelMode = mode
	}
}

// Collector runs an injected Probe through the same metric and log
// transformation pipeline used by the agent scraper, without publishing.
type Collector struct {
	scraper *scraper.Scraper
	cancel  context.CancelFunc
}

// New builds a Collector for one API-level check and probe.
func New(ctx context.Context, check sm.Check, probe sm.Probe, supplied Probe, collectorOptions ...Option) (*Collector, error) {
	var modelCheck model.Check
	if err := modelCheck.FromSM(check); err != nil {
		return nil, err
	}

	opts := options{labelMode: sm.LabelMode_LABEL_MODE_PREFIXED}
	for _, option := range collectorOptions {
		option(&opts)
	}

	collectorCtx, cancel := context.WithCancel(ctx)

	s, err := scraper.NewWithOpts(collectorCtx, modelCheck, scraper.ScraperOpts{
		Probe:                 probe,
		Publisher:             noopPublisher{},
		Logger:                zerolog.New(io.Discard),
		Metrics:               noopMetrics{},
		ProbeFactory:          probeFactory{probe: supplied},
		LabelsLimiter:         noopLabelsLimiter{},
		Telemeter:             noopTelemeter{},
		CostAttributionLabels: noopTenantCals{},
		LabellingMode:         staticLabellingMode{mode: opts.labelMode},
	})
	if err != nil {
		cancel()
		return nil, err
	}

	return &Collector{scraper: s, cancel: cancel}, nil
}

// Close releases the resources associated with the Collector. It is safe to
// call Close more than once.
func (c *Collector) Close() {
	c.cancel()
}

// Collect runs one execution whose metrics and logs are stamped at logical
// event time t. It does not make the supplied Probe consume logical elapsed
// time. A failed probe returns its telemetry alongside a non-nil error; a fatal
// collection error returns no telemetry.
func (c *Collector) Collect(ctx context.Context, t time.Time) (TimeSeries, Streams, error) {
	ts, streams, _, _, err := c.scraper.CollectData(ctx, t.UTC())
	return ts, streams, err
}

type probeAdapter struct {
	probe Probe
}

func (p probeAdapter) Name() string { return p.probe.Name() }

// Probe adapts the internal prober contract to the public Probe. The internal
// logger is passed straight through: internallogger.Logger satisfies the public
// collector.Logger (both expose Log(...any) error), and the internal execution
// ID is dropped because the public Probe does not surface it.
func (p probeAdapter) Probe(ctx context.Context, target string, registry *prometheus.Registry, logger internallogger.Logger, _ string) (bool, float64) {
	return p.probe.Probe(ctx, target, registry, logger)
}

type probeFactory struct {
	probe Probe
}

func (f probeFactory) New(_ context.Context, _ zerolog.Logger, check model.Check) (internalprober.Prober, string, error) {
	// probeFactory and probeAdapter share the same shape; staticcheck (S1016)
	// prefers the direct conversion over a field-by-field struct literal.
	return probeAdapter(f), check.Target, nil
}

type noopPublisher struct{}

func (noopPublisher) Publish(pusher.Payload) {}

type noopMetrics struct{}

func (noopMetrics) AddScrape()         {}
func (noopMetrics) AddCheckError()     {}
func (noopMetrics) AddCollectorError() {}

type noopLabelsLimiter struct{}

// The unscheduled collector does not enforce tenant label budgets; 128 is a
// permissive constant chosen to clear the scraper's guard, not a real limit.

func (noopLabelsLimiter) MetricLabels(context.Context, model.GlobalID) (int, error) {
	return 128, nil
}

func (noopLabelsLimiter) LogLabels(context.Context, model.GlobalID) (int, error) {
	return 128, nil
}

type noopTelemeter struct{}

func (noopTelemeter) AddExecution(telemetry.Execution) {}

type noopTenantCals struct{}

func (noopTenantCals) CostAttributionLabels(context.Context, model.GlobalID) ([]string, error) {
	return nil, nil
}

type staticLabellingMode struct {
	mode sm.LabelMode
}

func (m staticLabellingMode) ForTenant(context.Context, model.GlobalID) (sm.LabelMode, error) {
	return m.mode, nil
}