Feature: A sparrow should expose its ownership metadata

[puffitos]

Is there an existing feature request for this?

• I have searched the existing issues

Problem Description

Summary

As a monitoring canary tool that can be deployed by multiple teams across different infrastructure platforms, Sparrow should expose metrics containing information about the team responsible for the specific Sparrow instance and the infrastructure/platform it's running on. This will improve observability and enable better ownership tracking in multi-team environments and larger organisations and assist in triaging and resolving incidents.

Problem Statement

Currently, Sparrow instances don't expose any metadata about:

• Which team owns/operates the specific Sparrow instance
• Team contact information for incident response
• Platform/infrastructure context where the Sparrow is deployed

This makes it difficult to:

• Identify ownership when issues arise with specific Sparrow instances
• Route alerts to the correct team
• Understand the organizational context of monitoring data
• Manage multiple Sparrow deployments across different teams/platforms

Proposed Solution

Implement a new metric similar to kube_pod_info that contains team and infrastructure metadata. The metric should include labels for:

• team_name: The name of the team responsible for this Sparrow instance
• team_email: Contact email for the responsible team
• platform: The infrastructure/platform where this Sparrow is running (e.g., "kubernetes-prod", "aws-eu-west-1", etc.)
• instance_name: The Sparrow instance identifier (already available as the dns name in config)

We eventually need to keep in mind how people have better correlation possibilities for the already exposed metrics when using them in a multi-tenant dashboard (which team is responsible for which metrics).

Example metric:

sparrow_instance_info{team_name="platform-team", team_email="platform@example.com", platform="k8s-prod-eu", instance_name="sparrow.example.com"} 1

Implementation Considerations

There are three potential approaches to implement this feature:

Option 1: Dedicated Prometheus Metric (Recommended)

• Create a new sparrow_instance_info metric in the metrics package
• Add configuration fields to the startup config for team/platform information
• Register the metric alongside existing target manager metrics
• Pros: Standard Prometheus pattern, easy to query, follows existing metric structure
• Cons: Requires configuration changes

Option 2: Extend Registration JSON

• Add team/platform information to the registration file in the target manager
• Include metadata in the checks.GlobalTarget structure
• Pros: Leverages existing registration mechanism
• Cons: Only available when target manager is enabled, harder to query

Option 3: Add Labels to Existing Metrics

• Add team/platform labels to all existing Sparrow metrics
• Pros: Information available on all metrics
• Cons: Increases cardinality significantly, may impact performance

Option 4: Expose as an API endpoint

• Pros: This would greatly assist with a UI implementation of sparrow
• Pros: Natural way for people using the API to interact with the sparrow

Solution Description

Recommended Implementation Plan

Option 1 is recommended for the following reasons:

• Follows Prometheus best practices (similar to kube_pod_info)
• Easy to maintain and extend with additional metadata
• Single metric to query for instance information
• Minimal performance impact
• Clear separation of concerns

Configuration Changes Required

Add new configuration section to the startup config:

# Sparrow instance metadata
metadata:
  team:
    name: "platform-team"
    email: "platform@example.com" 
  platform: "k8s-prod-eu"

For Helm deployments, add corresponding values:

sparrowConfig:
  name: sparrow.example.com
  metadata:
    team:
      name: "platform-team"
      email: "example@example.com"
    platform: "k8s-prod-eu"

Implementation Details

• Config Structure: Add Metadata field to config.Config struct
• Metric Creation: Create new metric in metrics package
• Registration: Register metric during Sparrow initialization
• Helm Integration: Update chart values and templates to support metadata configuration
• Documentation: Update README and configuration docs

Who can address the issue?

Engineers with some prometheus experience and go programmers.

Additional Context

No response