feat: add sparrow_instance_info metric for ownership metadata (#354)

[ayoub3bidi]

Motivation

Operators need to identify which team owns each Sparrow instance and route alerts accordingly. This PR exposes optional ownership and platform metadata as a single Prometheus info metric (sparrow_instance_info) so multi-team deployments can correlate metrics and route by team/platform without changing existing check metrics.

Changes

• Config: New optional metadata block under startup config: metadata.team.name, metadata.team.email, metadata.platform. All fields optional; omitted values appear as empty labels.
• CLI: Flags --metadataTeamName, --metadataTeamEmail, --metadataPlatform; env vars SPARROW_METADATA_TEAM_NAME, etc.
• Metric: Single gauge sparrow_instance_info{team_name, team_email, platform, instance_name} with value 1, registered once at startup in sparrow.New(). Registration failure is logged and non-fatal.
• Helm: chart/values.yaml documents optional metadata under sparrowConfig; backward compatible when omitted.
• Docs: README (config table, instance info metric, PromQL examples), docs/sparrow_run.md (flags), design doc in docs/ownership-metadata-design.md.

For additional information look at the commits.

Tests done

• Unit tests in pkg/sparrow/metrics/instance_info_test.go: full metadata, empty metadata, partial metadata, double registration (AlreadyRegisteredError). Existing pkg/sparrow and pkg/config tests pass. Helm template validated with default and metadata values.

• Unit tests succeeded

• E2E tests succeeded

TODO

• I've assigned this PR to myself
• I've labeled this PR correctly

[ayoub3bidi]

Hi @lvlcn-t, sorry for the late response. I’ve applied the requested changes: switched metadata to a generic key/value map, removed the CLI flags, and updated the README/Helm/docs accordingly (including the header level fix). Thanks for the review.

[niklastreml]

please add this header to the table of contents above

[niklastreml]

This heading seems out of place as there is no option 2 here, so please change it so the document can be read in isolation :D

[niklastreml]

please remove the regex here. you can use the validation functions from prometheus directly:

import "github.com/prometheus/common/model"

func isValidLabelName(name string) bool {
    return model.UTF8Validation.IsValidLabelName(name)
}

then theres probably no need to have the wrapper function either

[niklastreml]

Thank you for the contributions, once the comments are addressed I think this can be merged @lvlcn-t

[lvlcn-t]

@ayoub3bidi Thanks for fixing my main concern about the metadata object.

I think after you've addressed @niklastreml's and my minor review improvements comments, this will be ready to be merged.

@niklastreml We should probably open an issue for splitting up the README into smaller documentation files in the docs/ dir since it grew quite large now.

[lvlcn-t]

Consider rephrasing it like this:

Suggested change

	`metadata` is a map of arbitrary key-value pairs. Keys must be valid Prometheus label names (e.g. `team_name`, `platform`, `region`, `environment`). The key `instance_name` is reserved and set automatically from the Sparrow DNS name.
	`metadata` is a map of arbitrary key-value pairs. Keys must be valid Prometheus label names (e.g. `team_name`, `platform`, `region`, `environment`). The key `instance_name` is reserved and automatically set to the sparrow's name.

[lvlcn-t]

You can simplify this a lot by flattening for loops:

	found := false
	for _, mf := range metrics {
		if mf.GetName() != instanceInfoMetricName {
			continue
		}
		found = true
		
		if len(mf.GetMetric()) != 1 {
			t.Errorf("expected 1 metric, got %d", len(mf.GetMetric()))
		}

		const expectedValue = 1
		for _, m := range mf.GetMetric() {
			if m.GetGauge().GetValue() != expectedValue {
				t.Errorf("%q metric value expected %d, got %f", instanceInfoMetricName, expectedValue, m.GetGauge().GetValue())
			}

			labels := make(map[string]string)
			for _, lp := range m.GetLabel() {
				labels[lp.GetName()] = lp.GetValue()
			}
			if !maps.Equal(expectedLabels, labels) {
				t.Errorf("expected labels %v, got %v", expectedLabels, labels)
			}
		}
	}

Please also take a look at the other loops in these tests, the same can probably be applied to them as well.

[ayoub3bidi]

Hi @lvlcn-t and @niklastreml, thanks for the reviews. All comments have been addressed:

• README: added the Instance metadata section to the table of contents
• Design doc: renamed the heading to "Why a Dedicated Info Metric"
• instance_info.go: replaced the custom regex with model.UTF8Validation.IsValidLabelName from prometheus/common
• instance_info_test.go: simplified the loops, introduced expectedLabels and maps.Equal, and improved error messages

Tests are passing. I’ll open an issue to track splitting the README into smaller docs.