Add thermal status instrumentation (#1799)

[hitkall]

What

Adds a new, opt-in instrumentation module (instrumentation/thermal) that listens for device thermal-status changes and emits one log event per change.

Fixes #1799

Approach

• Event-driven, no polling. ThermalInstrumentation.install() registers a PowerManager.OnThermalStatusChangedListener via PowerManager.addThermalStatusListener(executor, listener) on a single-thread executor. uninstall() calls removeThermalStatusListener and shuts the executor down.
• API 29+ gated. The thermal APIs (addThermalStatusListener, THERMAL_STATUS_*) are only available on API level 29 (Android Q). Since the project minSdk is 23, install() gates on Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q and no-ops on older devices. The API-29 call sites are annotated @RequiresApi(29) so Animal Sniffer is satisfied.
• Opt-in. This module is not added to android-agent, so it is not bundled by default — consumers add the dependency and install it explicitly. The README documents this.
• ThermalDetector maps the integer status codes to readable strings (none, light, moderate, severe, critical, emergency, shutdown, with an unknown fallback) and emits via the logs bridge.

This module closely mirrors the existing instrumentation/screen-orientation module in structure, style, and conventions.

Telemetry

Scope	io.opentelemetry.thermal
Event name	device.thermal_state
Attribute	android.thermal.state (string)

Note on naming: the event name (device.thermal_state) and attribute (android.thermal.state) are proposals. Happy to align them with whatever the maintainers prefer for semantic conventions.

Tests

ThermalDetectorTest (JUnit 4 + MockK + AssertJ + OpenTelemetryRule) covers:

• a single status change emits the right event name + attribute,
• the full code→name mapping for every known status,
• the unknown fallback for an unrecognized code.

Verification

Run locally against JDK 17 + Android SDK 36:

• ./gradlew spotlessApply
• ./gradlew :instrumentation:thermal:test (3 tests pass)
• ./gradlew apiDump (generated api/thermal.api)
• ./gradlew apiCheck
• ./gradlew :instrumentation:thermal:assemble
• (also detekt + lintDebug for the module)

🤖 Generated with Claude Code

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: hitkall / name: Hitesh Kalluru (0ac4f7e)

[codecov]

Codecov Report

❌ Patch coverage is 95.34884% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.13%. Comparing base (fec75d2) to head (3c3a5a0).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
.../instrumentation/thermal/ThermalInstrumentation.kt	92.59%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1801      +/-   ##
==========================================
+ Coverage   62.88%   63.13%   +0.25%     
==========================================
  Files         158      160       +2     
  Lines        3451     3494      +43     
  Branches      355      360       +5     
==========================================
+ Hits         2170     2206      +36     
- Misses       1179     1182       +3     
- Partials      102      106       +4     

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

[breedx-splk]

Thanks @hitkall this is great. I offered a few remarks, but this is definitely on track.

I also think you might have missed adding this module to the settings.gradle.kts in the root of the project. I don't think it'll be included and compiled until you do that.

[breedx-splk]

A bit of a drag to burn an entire thread on something that is probably rarely used. I'm not entirely sure what best practice around this is. We have a few other instrumentations that create their own, so it's not a show-stopper. We might want to consider a future mechanism for sharing these so that it's a little more scalable.

[breedx-splk]

nitpick: prefer to have the interface method above the private methods that it calls into.

[breedx-splk]

I think this can be removed, unless you have a reason for needing it? I see that the screen orientation also has an empty one, but maybe that can be removed as well (separately from this PR tho).

[breedx-splk]

I'm not sure what sut is a convention for or shortening of ("[s]omething [u]nder [t]est"?), but it's not something we really use. Maybe just call it detector instead?

[breedx-splk]

reminder to change readme to match the name change suggested above (or whatever it lands on).

[hitkall]

Thanks for the thorough review, really appreciate it!
Addressing everything:
settings.gradle.kts — I think this is actually handled already. The includeFromDir("instrumentation") function in settings.gradle.kts walks the directory tree looking for build.gradle.kts files up to depth 3, so instrumentation/thermal gets auto-discovered without a manual entry. That said, I want to double-check that api/thermal.api was committed properly — its absence might be what made the module look unregistered in CI. Will verify and push a fix if it's missing.
Executor — totally fair point. A dedicated thread for something that fires maybe a handful of times a day is wasteful. Happy to follow whatever pattern the project lands on for sharing executors across instrumentations — flagging it as a known issue in the code for now sounds reasonable if there's no existing pattern to hook into yet.
device.thermal_status.change — accepted, makes more sense as "what happened". Will update EVENT_NAME, the README, and the test references.
Method ordering — will fix, onThermalStatusChanged above the private extension.
AndroidManifest.xml — will delete it.
sut → detector — will rename throughout the test.
android.thermal.state attribute — I like the direction of framing it around throttling impact rather than raw thermal state. Open to android.thermal.throttling_status or similar if you have a preference — otherwise I'll leave it as-is for now and we can revisit when semconv gets more formal here.
Will push an update addressing all of the above shortly.

@breedx-splk

[breedx-splk]

Looking good! Thanks for the help and for the quick responses.

[hitkall]

Thanks for the review @breedx-splk! All feedback is addressed in the latest commits:

• Renamed the attribute to android.thermal.throttling_status — agreed the API reports throttling severity (0 = none … 6 = shutdown) rather than temperature, so this is more accurate. README updated to match.
• Renamed the event to device.thermal_status.change.
• Moved the interface method (onThermalStatusChanged) above the private helpers.
• Removed the empty AndroidManifest.xml.
• Renamed sut → detector in the detector test.
• Added ThermalInstrumentationTest covering the API-29 gate, listener registration/removal, and the uninstall-before-install no-op.

Re: settings.gradle.kts — the module is picked up automatically by includeFromDir("instrumentation"), and CI is compiling/testing :instrumentation:thermal, so no manual include is needed.

The event/attribute names are still open to whatever the semantic-conventions discussion lands on. Let me know if you'd like anything else.