Add guidance for null checking, promote ApiUsageLogger to opentelemetry-common public API

[jack-berg]

Related to #8173.

Summary of new guidance:

• Add null guards are public API entry points
  • For configuration time boundaries (i.e. SDK builders), fail fast with Objects.requireNonNull
  • For runtime boundaries (i.e. opentelemetry-api), use ApiUsageLogger and exit early
  • For implementations of SDK extension plugins (i.e. SpanExporter, Sampler) fail fast with Objects.requireNonNull since SDK is the only thing calling these
• ApiUsageLogger has two methods:
• logNullParam(Class clazz, String methodName, String paramName), which logs warning that the param is null
• log(Class clazz, String methodName, String message), logs a generic message about some problem with param (i.e. stuff that would normally trigger IllegalArgumentException)
• Guidance for users is to enable "io.opentelemetry.usage" at dev time, and for debug purposes. That way, they can identify and fix instances of incorrect API usages in a standard way.
• Gaurds should exist at API boundaries. Once within otel internals, can depend on nullaway to ensure safety.

This advice somewhat codifies what we do today. But we're very loose / inconsistent, which is what I'm trying to solve here.

#8321 demonstrates what it looks like to apply this policy everywhere in this repo.

[otelbot]

⚠️ API changes detected — additional maintainer review required

@jack-berg @jkwatson

This PR modifies the public API surface area of the following module(s):

• opentelemetry-common

Please review the changes in docs/apidiffs/current_vs_latest/ carefully before approving.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.28%. Comparing base (6c205ae) to head (ae7548a).

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #8318   +/-   ##
=========================================
  Coverage     90.27%   90.28%           
- Complexity     7693     7695    +2     
=========================================
  Files           850      850           
  Lines         23207    23211    +4     
  Branches       2356     2357    +1     
=========================================
+ Hits          20951    20955    +4     
  Misses         1530     1530           
  Partials        726      726           

☔ 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.

[jack-berg]

As discussed in 4/23 java SIG, we want to create a convention for "code which is stable from API / ABI standpoint, but not intended for end users", since ApiUsageLogger is a prime candidate for this. Solved in #8325

We also discussed using an AtomicBoolean CAS to log a warning level message with instructions for enabling usage logging up to one time. This balances visibility and noise concerns.

[jkwatson]

Thanks!