Skip to content

Add support for JVM Telemetry (Java sensor)

Enhancement proposal

Release notes

Problem to solve

The sensors need to be enhanced to support JVM Telemetry collection. This works best with a native Java implementation in the sensor.

Environment information

  • OS (Linux/Unix, macOS, Windows) and version: any
  • Metrics type (Prometheus, file, Arduino, other hardware sensors): new, JVM telemetry

Proposal

JVM Telemetry Agent Implementation Strategy

Overview

This document outlines the implementation strategy for a lightweight JVM agent to collect telemetry data from our sensor applications with minimal performance impact.

Implementation Tasks

1. Agent Framework Setup

  • Create a Maven/Gradle project with the agent module
  • Configure manifest for the Premain-Class attribute
  • Implement the premain method entry point
  • Set up build process to generate the agent JAR with all dependencies

2. Core Telemetry Metrics Collection

  • Implement JMX-based collectors for:
    • Heap memory usage (used/max/committed)
    • Non-heap memory usage
    • Garbage collection statistics
    • Thread information (count, state)
    • CPU usage
  • Set up a scheduled executor for metric collection with configurable frequency

3. Sensor-Specific Metrics

  • Implement custom collectors for sensor-specific metrics:
    • Data collection rate
    • Sensor connection status
    • Processing queue length
    • Sensor error rates
  • Create extension points for application-specific metrics

4. Data Buffer & Transmission

  • Implement circular buffer to store metrics locally
  • Create configurable batch transmission strategy
  • Add backpressure handling for network issues
  • Implement data compression for transmission

5. Performance Optimizations

  • Add sampling capabilities for high-frequency metrics
  • Implement adaptive collection rate based on system load
  • Create circuit breakers to disable collection under extreme load
  • Use weak references for class/object tracking to avoid memory leaks

6. Configuration

  • Create a configuration system for the agent (external properties file)
  • Allow runtime reconfiguration via JMX
  • Implement collection profiles (low/medium/high detail)
  • Add allowlist/blocklist for specific metrics

7. Integration & Usage

  • Document JVM arguments for agent attachment:

    java -javaagent:path/to/telemetry-agent.jar=configFile=/path/to/config.properties -jar application.jar

  • Create example configuration templates

  • Implement dashboard integration for metrics visualization

8. Testing

  • Measure baseline performance impact
  • Perform load testing with agent enabled
  • Verify data accuracy against manual JMX queries
  • Test agent behavior under extreme conditions

Design Principles

  • Asynchronous collection to avoid blocking application threads
  • Fail gracefully - agent issues should never impact the host application
  • Configurable verbosity to balance detail with performance
  • Minimal external dependencies to reduce conflicts

Next Steps

Once implemented, we'll integrate this agent with our monitoring infrastructure and establish baseline metrics for all sensor deployments.