docs(metrics): add design doc

[cijothomas]

Adds docs/design/metrics.md, a companion to the existing logs/traces/otlp/observability design docs.

The intent is to capture the architectural choices behind the metrics API+SDK in one place: the instrument-based API surface, the per-stream ValueMap hot path (empty-attribute fast path, caller-order lookup, sorted-key fallback, write-lock upgrade, lock-free aggregator updates), cardinality limit + overflow behavior, the known contention story and the prior attempts to relieve it (#1564, #2304, #3473, #1386, umbrella #2450), bound instruments and why they exist (hot-path self-diagnostics), views, and the reader/exporter side.

Companion to docs/metrics.md, which stays focused on user-facing guidance.

Opening as draft to invite review on framing/accuracy before merging. Happy to split sections out if anything reads as too detailed for a design doc.

Merge requirement checklist

• CONTRIBUTING guidelines followed
• Unit tests added/updated (if applicable) — N/A, docs only
• Appropriate CHANGELOG.md files updated for non-trivial, user-facing changes — N/A, docs only
• Changes in public API reviewed (if applicable) — N/A

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.0%. Comparing base (90a39a0) to head (1fd3d7e).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #3569     +/-   ##
=======================================
- Coverage   83.0%   83.0%   -0.1%     
=======================================
  Files        130     130             
  Lines      27992   27992             
=======================================
- Hits       23251   23250      -1     
- Misses      4741    4742      +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Thank you for your contribution! This PR has been automatically marked as stale because it has not had activity in the last 14 days. This may be due to a delay in review on our side or awaiting a response from you; either is fine, and we appreciate your patience.

It will be closed in 14 days if no further activity occurs. Pushing a new commit or leaving a comment will remove the stale label and keep the PR open.

[github-actions]

Closed as inactive. Thank you again for the contribution; please feel free to reopen this PR (or open a new one) if you'd like to continue the work.