Track changes to upstream configuration over time

[rfratto]

Background

We frequently risk desyncing with upstream configuration every time we upgrade; upstream can have a large API surface (particularly OpenTelemetry) and even if we audit changes to components between upgrades, it's fairly easy to miss something, whether that be a change to default values, a new field, a renamed field, or a removed field.

Automatically tracking upstream's configuration changes will give us more confidence while upgrading, and generally make upgrading easier.

Proposal

Create API surface dumps of upstream code we map to (OpenTelemetry Components, Prometheus subsystems, etc.) which include all known fields and their defaults.

The API surface dump will be saved in the repository, and CI jobs will regenerate the API surface dump every PR to check for changes, failing if the file has been changed without committing the changes to the repository.

This will signal to PR reviewers that something has changed with upstream, making it harder to miss things. When one of these files changes, it'll signal to the reviewer to what additional work needs to be done to resynchronize with upstream, or if no action should be taken for a particular change.

This is a similar approach to what Go does with its API surface to check for backwards incompatible changes. In this case we're using it for tracking upstream types, but we may also want to consider using it for our own components as well for backwards-incompatible detection.