Allow selected metadata as opt-in Prometheus labels #1826

Description

Description

Diun already supports user-defined metadata on provider entries. This metadata
can, for example, be used in notification templates.

The label set of the per-image Prometheus metrics is intentionally small. This
keeps cardinality predictable across different providers, and the default
behavior should remain unchanged.

There are cases, however, where a Prometheus consumer needs to retain a small
amount of user-defined context associated with a watched entry.

Motivation

One concrete example is monitoring Envoy releases.

Envoy publishes exact stable version tags and minor-series tags such as:

envoyproxy/envoy:v1.39.0
envoyproxy/envoy:v1.39-latest

For users interested in the newest stable release across minor series, Diun can
already discover the appropriate image using a repository watch:

- name: docker.io/envoyproxy/envoy
  watch_repo: true
  sort_tags: semver
  max_tags: 1
  include_tags:
    - '^v[0-9]+\.[0-9]+\.[0-9]+$'
  metadata:
    channel: newest

This correctly selects the newest matching stable release. However, the
resulting Prometheus series only retains labels such as provider and image:

diun_image_created_timestamp_seconds{
  provider="file",
  image="docker.io/envoyproxy/envoy:v1.39.0"
}

The consumer can no longer see that this image originated from the entry marked
with:

metadata:
  channel: newest

A Prometheus or Grafana consumer therefore has to parse and normalize the
image label and combine multiple series to reconstruct the purpose of the
watched entry.

Envoy is only an example here. The requested functionality is generic entry
metadata handling and would not contain any Envoy-specific behavior.

Envoy's documented image tagging strategy can be found here:

https://hub.docker.com/r/envoyproxy/envoy

Proposed configuration

Add an explicit allowlist to the metrics configuration:

metrics:
  enabled: true
  metadataLabels:
    - channel

Only metadata keys listed in metadataLabels would be exposed on per-image
metrics. Given:

metadata:
  channel: newest

the resulting metric would include:

metadata_channel="newest"

For example:

diun_image_created_timestamp_seconds{
  provider="file",
  image="docker.io/envoyproxy/envoy:v1.39.0",
  metadata_channel="newest"
}

The metadata_ prefix keeps user-defined labels separate from native labels
such as provider, image, and status.

Expected behavior

• The feature is disabled by default.
• Without metrics.metadataLabels, metric descriptors and label sets remain
  unchanged.
• Metadata is never exported implicitly.
• Only explicitly allowlisted metadata keys are exposed.
• Configured label names are fixed when the metrics recorder is initialized.
• If an entry does not contain a configured key, the corresponding label uses
  an empty value so that the label schema remains consistent.
• Non-allowlisted metadata remains available to notifications and other
  existing consumers but does not appear on /metrics.
• Selected labels are applied consistently to the existing per-image metrics:
  • diun_image_update_available
  • diun_image_last_check_timestamp_seconds
  • diun_image_last_check_status
  • diun_image_created_timestamp_seconds
• Non-image metrics remain unchanged.
• Invalid metadata keys should be rejected by configuration validation rather
  than silently renamed.

Cardinality

The existing restricted label set is useful and should remain the default.

This proposal deliberately uses an explicit global allowlist instead of
exporting all entry metadata. The additional label names are therefore known
when the metrics recorder is initialized, and users remain responsible for
selecting only a small number of metadata fields with appropriate values.

Scope

This should be a small extension of the existing metrics and entry metadata
functionality:

• no automatic metadata export
• no provider-specific implementation
• no separate metadata metric
• no changes to existing metadata semantics
• no changes to the default metric label set

I have a small implementation prepared using metrics.metadataLabels and the
metadata_ prefix, but I am happy to adjust the configuration shape or naming
if another form fits the project better.