per #25820 (comment), we need to add documentation for the new metrics API, and probably some examples in other parts of the documentation to show how it's used.

opening this issue for tracking, so that we unblock the PR that implements the feature

/cc @mstanleyjones @crosbymichael - assigning you both so that we don't forget 😄