feat(metrics): Trace-connected Metrics (Analyzers)

[Flash0ver]

based on (but to be merged to main individually)

• feat(metrics): Trace-connected Metrics #4834
• ref!: remove Experimental from Metrics API #5023

Summary

My little weekend-project:
Add a Diagnostic-Analyzer to our Compiler-Extensions, that warn users when a metric would not be emitted due to an unsupported numeric value type -or- likewise, a SentryMetric.TryGetValue<> invocation with an unsupported numeric value type is detected.

Changelog Entry

Report a new Diagnostic (SENTRY1001) when a Metrics-API is invoked with an unsupported numeric type

Remarks

For the numeric type of a Metric, we currently allow 64-bit sized integral (signed) and floating-point numbers.
That means that e.g. ulong, System.Int128, or decimal are currently not supported by Sentry.
The compile-time constraint of Sentry.SentryMetric<T> only constrains to non-nullable value types.
Alternatively, we could have implemented respectively types overloads for the method groups:

public void EmitCounter(string name, long value);
public void EmitCounter(string name, float value);
public void EmitCounter(string name, double value);
public void EmitCounter(string name, long value, Scope? scope)
public void EmitCounter(string name, float value, Scope? scope)
public void EmitCounter(string name, double value, Scope? scope)
public void EmitCounter ..

public void EmitGauge ..
public void EmitDistribution ..

To avoid this explosion of overloads per method group,
and be similar to the implementation of System.Diagnostics.Metrics,
we are not compile-time constraining unsupported types,
but are instead run-time constraining unsupported types (no-op and Debug-Diagnostic-Logging).

To still warn users unfamiliar with the System.Diagnostics.Metrics.Meter-based APIs,
I built an Analyzer over some weekends to guide new users.

Examples

options.SetBeforeSendMetric(static SentryMetric? (SentryMetric metric) =>
{
    if (metric.TryGetValue<int>(out int int32) && int32 < 0)
    {
        return null;
    }

    if (metric.TryGetValue<uint>(out uint uint32) && uint32 == 0) //SENTRY1001
    {
        return null;
    }

    return metric;
});

SentrySdk.Metrics.EmitCounter("my.counter", 1);
SentrySdk.Metrics.EmitCounter("my.counter", 1m); //SENTRY1001
SentrySdk.Metrics.EmitCounter("my.counter", StringComparison.CurrentCultureIgnoreCase); //SENTRY1001
SentrySdk.Metrics.EmitCounter<ulong>("my.counter", default); //SENTRY1001

[github-actions]

	Fails
🚫	Please consider adding a changelog entry for the next release.

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Instructions and example for changelog

Please add an entry to CHANGELOG.md to the "Unreleased" section. Make sure the entry includes this PR's number.

Example:

## Unreleased

### Features

- Trace-connected Metrics (Analyzers) ([#4840](https://github.com/getsentry/sentry-dotnet/pull/4840))

If none of the above apply, you can opt out of this check by adding #skip-changelog to the PR description or adding a skip-changelog label.

Generated by 🚫 dangerJS against bd6e462

[codecov]

Codecov Report

❌ Patch coverage is 76.47059% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.95%. Comparing base (a87d441) to head (9330572).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
...ensions/Analyzers/TraceConnectedMetricsAnalyzer.cs	73.91%	6 Missing and 6 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4840      +/-   ##
==========================================
+ Coverage   73.71%   73.95%   +0.24%     
==========================================
  Files         497      499       +2     
  Lines       17966    18017      +51     
  Branches     3516     3527      +11     
==========================================
+ Hits        13244    13325      +81     
+ Misses       3858     3829      -29     
+ Partials      864      863       -1     

☔ View full report in Codecov by Sentry.
📢 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]

Semver Impact of This PR

⚪ None (no version bump detected)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

Breaking Changes 🛠

• The _Metrics_ APIs are now stable: removed Experimental from SentrySdk, SentryOptions and IHub by Flash0ver in #5023

Features ✨

• Report a new _Diagnostic_ (SENTRY1001) when a Metrics-API is invoked with an unsupported numeric type by Flash0ver in #4840

Dependencies ⬆️

Deps

• chore(deps): update Cocoa SDK to v9.7.0 by github-actions in #5015
• chore(deps): update Java SDK to v8.35.0 by github-actions in #5017
• chore(deps): replaced the heavy protobuf-javalite 3.25.8 dependency with a light-weight epitaph 0.1.0 alternative on Android (getsentry/sentry-java#5157) by github-actions in #5017
• chore(deps): update CLI to v3.3.3 by github-actions in #5002
• chore(deps): update Cocoa SDK to v9.6.0 by github-actions in #4958

---

_{🤖 This preview updates automatically when you update the PR.}

[jamescrosswell]

LGTM - nice work @Flash0ver !