JDK-8203357 : Container Metrics
  • Type: Enhancement
  • Component: core-svc
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2018-05-17
  • Updated: 2020-08-13
  • Resolved: 2018-06-13
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 11 Other
11 b19Fixed openjdk8u272Fixed
Related Reports
Blocks :  
Blocks :  
CSR :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Sub Tasks
JDK-8184303 :  
JDK-8184427 :  
JDK-8184428 :  
JDK-8184430 :  
Description
Container Metrics

Provide an internal API that can be used to extract container specific configuration and runtime statistics.  This JEP will only support Docker on Linux-x64 although the design should be flexible enough to allow support for other platforms and container technologies.  The initial focus will be on Linux cgroups technology so that we will be able to easily support other container technologies running on Linux in addition to Docker.

Non-Goals
---------

Although it is expected that this API will function properly on all cgroup enabled Linux platforms, it is not a goal of this JEP to perform validation of any configuration other than Docker containers running on Linux x64 and direct Linux host process execution.  Since cgroups are enabled for processes running directly on Linux hosts, this configuration will also be verified.

Motivation
----------

Container technology is becoming more and more prevalent in Cloud based applications.  The Cloud Serverless application programming model motivates developers to split large monolithic applications into 100s of smaller pieces each running in thier own container.  This move increases the importance of the observability of each running container process.  Adding the proposed set of APIs will allow more details related to each container process to be made available to external tools thereby improving the observability.

Description
-----------

This enhancement will be made up of the following work items:

Detecting if Java is running in a container.

The Java runtime, as well as any tests that we might write for this feature, will need to be able to detect that the current Java process is running in a container.  A new API will be made available for this purpose.

Exposing container resource limits, configuration and runtime statistics.

There are several configuration options and limits that can be imposed upon a running container.  Not all of these
are important to a running Java process.  We clearly want to be able to detect how many CPUs have been allocated to our process along with the maximum amount of memory that the process has been allocated but there are other options that we might want to base runtime decisions on.

In addition, since containers typically impose limits on system resources, they also provide the ability to easily access the amount of consumption of these resources.  The goal is to provide this information in addition to the configuration data.

A new jdk.internal.platform.Metrics class will define the API to obtain the types of configuration and consumption metrics listed below.

    class Container {
         public static Metrics metrics();
    }

Here are some of the types of configuration and consumption statistics that will be made available:

    Total Memory Limit
    Soft Memory Limit
    Maximum Memory Usage
    Current Memory Usage 
    Maximum Kernel Memory Usage
    Current Kernel Memory Usage
    Kernel Memory Limit
    Swap Memory Limit
    Maximum Swap Usage
    Current Swap Usage 
    CPU Shares
    CPU Period
    CPU Quota
    Number of CPUs
    CPU Sets
    CPU Set Memory Nodes
    CPU Usage
    CPU Usage Per CPU
    Block I/O Requests Serviced
    Block I/O Total Bytes Transferred
    OOM Kill Enabled
    
In addition to the new internal API, a new java -XshowSettings:system option will be added to allow the reporting of the system metrics.

Once this API has been integrated in the Java sources, enhancements to [JMX][1] and [JFR][2] will be done separately to enable the use and reporting of these metrics.

  [1]: https://bugs.openjdk.java.net/browse/JDK-8199944
  [2]: https://bugs.openjdk.java.net/browse/JDK-8203359
Comments
Final RFR is actually: https://mail.openjdk.java.net/pipermail/jdk8u-dev/2020-August/012426.html Confusing that this review was completed yesterday, but the above comment is dated 2020-07-03 :/ Anyway, approving.
13-08-2020

Fix Request (OpenJDK 8u): Please approve backporting this to OpenJDK 8u. It's a dependency for JDK-8226575 which has been backported to Oracle JDK 8. A CSR has been filed for the added -XshowSettings:system CLI flag and it's approved. Risk of this patch stand-alone is low as nothing is using those classes other than LauncherHelper.java via said switch. Testing: added container tests, tier1. Patch didn't apply cleanly from JDK 11u. The JDK 8u patch got reviewed by Andrew Hughes. webrev: http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8203357/jdk8/03/webrev/ CSR (approved): https://bugs.openjdk.java.net/browse/JDK-8249895 RFR: http://mail.openjdk.java.net/pipermail/jdk8u-dev/2020-July/012306.html
12-08-2020