Modify Javadoc line length in OsProbe.java

This commit changes the Javadocs in OsProbe.java to take advantage of
the fact that the line-length limit is 140 characters. This change makes
these Javadocs easier to read and easier to maintain.
This commit is contained in:
Jason Tedor 2016-11-07 17:26:28 -05:00
parent 6a6e1bed55
commit 7c31e8cc58
1 changed files with 53 additions and 105 deletions

View File

@ -121,8 +121,7 @@ public class OsProbe {
*
* On Windows, this method returns {@code null}.
*
* On Linux, this method returns the 1, 5, and 15-minute load
* averages.
* On Linux, this method returns the 1, 5, and 15-minute load averages.
*
* On macOS, this method should return the 1-minute load average.
*
@ -161,12 +160,9 @@ public class OsProbe {
}
/**
* The line from {@code /proc/loadavg}. The first three fields are
* the load averages averaged over 1, 5, and 15 minutes. The fourth
* field is two numbers separated by a slash, the first is the
* number of currently runnable scheduling entities, the second is
* the number of scheduling entities on the system. The fifth field
* is the PID of the most recently created process.
* The line from {@code /proc/loadavg}. The first three fields are the load averages averaged over 1, 5, and 15 minutes. The fourth
* field is two numbers separated by a slash, the first is the number of currently runnable scheduling entities, the second is the
* number of scheduling entities on the system. The fifth field is the PID of the most recently created process.
*
* @return the line from {@code /proc/loadavg} or {@code null}
*/
@ -196,15 +192,11 @@ public class OsProbe {
private static final Pattern CONTROL_GROUP_PATTERN = Pattern.compile("\\d+:([^:,]+(?:,[^:,]+)?):(/.*)");
/**
* A map of the control groups to which the Elasticsearch process
* belongs. Note that this is a map because the control groups can
* vary from subsystem to subsystem. Additionally, this map can not
* be cached because a running process can be reclassified.
* A map of the control groups to which the Elasticsearch process belongs. Note that this is a map because the control groups can vary
* from subsystem to subsystem. Additionally, this map can not be cached because a running process can be reclassified.
*
* @return a map from subsystems to the control group for the
* Elasticsearch process.
* @throws IOException if an I/O exception occurs reading
* {@code /proc/self/cgroup}
* @return a map from subsystems to the control group for the Elasticsearch process.
* @throws IOException if an I/O exception occurs reading {@code /proc/self/cgroup}
*/
private Map<String, String> getControlGroups() throws IOException {
final List<String> lines = readProcSelfCgroup();
@ -227,21 +219,16 @@ public class OsProbe {
}
/**
* The lines from {@code /proc/self/cgroup}. This file represents
* the control groups to which the Elasticsearch process belongs.
* Each line in this file represents a control group hierarchy of
* the form
* The lines from {@code /proc/self/cgroup}. This file represents the control groups to which the Elasticsearch process belongs. Each
* line in this file represents a control group hierarchy of the form
* <p>
* {@code \d+:([^:,]+(?:,[^:,]+)?):(/.*)}
* <p>
* with the first field representing the hierarchy ID, the second
* field representing a comma-separated list of the subsystems
* bound to the hierarchy, and the last field representing the
* control group.
* with the first field representing the hierarchy ID, the second field representing a comma-separated list of the subsystems bound to
* the hierarchy, and the last field representing the control group.
*
* @return the lines from {@code /proc/self/cgroup}
* @throws IOException if an I/O exception occurs reading
* {@code /proc/self/cgroup}
* @throws IOException if an I/O exception occurs reading {@code /proc/self/cgroup}
*/
@SuppressForbidden(reason = "access /proc/self/cgroup")
List<String> readProcSelfCgroup() throws IOException {
@ -251,33 +238,24 @@ public class OsProbe {
}
/**
* The total CPU time in nanoseconds consumed by all tasks in the
* cgroup to which the Elasticsearch process belongs for the
* {@code cpuacct} subsystem.
* The total CPU time in nanoseconds consumed by all tasks in the cgroup to which the Elasticsearch process belongs for the {@code
* cpuacct} subsystem.
*
* @param controlGroup the control group for the Elasticsearch
* process for the {@code cpuacct} subsystem
* @param controlGroup the control group for the Elasticsearch process for the {@code cpuacct} subsystem
* @return the total CPU time in nanoseconds
* @throws IOException if an I/O exception occurs reading
* {@code cpuacct.usage} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpuacct.usage} for the control group
*/
private long getCgroupCpuAcctUsageNanos(final String controlGroup) throws IOException {
return Long.parseLong(readSysFsCgroupCpuAcctCpuAcctUsage(controlGroup));
}
/**
* Returns the line from {@code cpuacct.usage} for the control
* group to which the Elasticsearch process belongs for the
* {@code cpuacct} subsystem. This line represents the total CPU
* time in nanoseconds consumed by all tasks in the same control
* group.
* Returns the line from {@code cpuacct.usage} for the control group to which the Elasticsearch process belongs for the {@code cpuacct}
* subsystem. This line represents the total CPU time in nanoseconds consumed by all tasks in the same control group.
*
* @param controlGroup the control group to which the Elasticsearch
* process belongs for the {@code cpuacct}
* subsystem
* @param controlGroup the control group to which the Elasticsearch process belongs for the {@code cpuacct} subsystem
* @return the line from {@code cpuacct.usage}
* @throws IOException if an I/O exception occurs reading
* {@code cpuacct.usage} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpuacct.usage} for the control group
*/
@SuppressForbidden(reason = "access /sys/fs/cgroup/cpuacct")
String readSysFsCgroupCpuAcctCpuAcctUsage(final String controlGroup) throws IOException {
@ -285,33 +263,25 @@ public class OsProbe {
}
/**
* The total period of time in microseconds for how frequently the
* Elasticsearch control group's access to CPU resources will be
* The total period of time in microseconds for how frequently the Elasticsearch control group's access to CPU resources will be
* reallocated.
*
* @param controlGroup the control group for the Elasticsearch
* process for the {@code cpuacct} subsystem
* @param controlGroup the control group for the Elasticsearch process for the {@code cpuacct} subsystem
* @return the CFS quota period in microseconds
* @throws IOException if an I/O exception occurs reading
* {@code cpu.cfs_period_us} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpu.cfs_period_us} for the control group
*/
private long getCgroupCpuAcctCpuCfsPeriodMicros(final String controlGroup) throws IOException {
return Long.parseLong(readSysFsCgroupCpuAcctCpuCfsPeriod(controlGroup));
}
/**
* Returns the line from {@code cpu.cfs_period_us} for the control
* group to which the Elasticsearch process belongs for the
* {@code cpu} subsystem. This line represents the period of time
* in microseconds for how frequently the control group's access to
* CPU resources will be reallocated.
* Returns the line from {@code cpu.cfs_period_us} for the control group to which the Elasticsearch process belongs for the {@code cpu}
* subsystem. This line represents the period of time in microseconds for how frequently the control group's access to CPU resources
* will be reallocated.
*
* @param controlGroup the control group to which the Elasticsearch
* process belongs for the {@code cpu}
* subsystem
* @param controlGroup the control group to which the Elasticsearch process belongs for the {@code cpu} subsystem
* @return the line from {@code cpu.cfs_period_us}
* @throws IOException if an I/O exception occurs reading
* {@code cpu.cfs_period_us} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpu.cfs_period_us} for the control group
*/
@SuppressForbidden(reason = "access /sys/fs/cgroup/cpu")
String readSysFsCgroupCpuAcctCpuCfsPeriod(final String controlGroup) throws IOException {
@ -319,33 +289,25 @@ public class OsProbe {
}
/**
* The total time in microseconds that all tasks in the
* Elasticsearch control group can run during one period as
* specified by {@code cpu.cfs_period_us}.
* The total time in microseconds that all tasks in the Elasticsearch control group can run during one period as specified by {@code
* cpu.cfs_period_us}.
*
* @param controlGroup the control group for the Elasticsearch
* process for the {@code cpuacct} subsystem
* @param controlGroup the control group for the Elasticsearch process for the {@code cpuacct} subsystem
* @return the CFS quota in microseconds
* @throws IOException if an I/O exception occurs reading
* {@code cpu.cfs_quota_us} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpu.cfs_quota_us} for the control group
*/
private long getCgroupCpuAcctCpuCfsQuotaMicros(final String controlGroup) throws IOException {
return Long.parseLong(readSysFsCgroupCpuAcctCpuAcctCfsQuota(controlGroup));
}
/**
* Returns the line from {@code cpu.cfs_quota_us} for the control
* group to which the Elasticsearch process belongs for the
* {@code cpu} subsystem. This line represents the total time in
* microseconds that all tasks in the control group can run during
* one period as specified by {@code cpu.cfs_period_us}.
* Returns the line from {@code cpu.cfs_quota_us} for the control group to which the Elasticsearch process belongs for the {@code cpu}
* subsystem. This line represents the total time in microseconds that all tasks in the control group can run during one period as
* specified by {@code cpu.cfs_period_us}.
*
* @param controlGroup the control group to which the Elasticsearch
* process belongs for the {@code cpu}
* subsystem
* @param controlGroup the control group to which the Elasticsearch process belongs for the {@code cpu} subsystem
* @return the line from {@code cpu.cfs_quota_us}
* @throws IOException if an I/O exception occurs reading
* {@code cpu.cfs_quota_us} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpu.cfs_quota_us} for the control group
*/
@SuppressForbidden(reason = "access /sys/fs/cgroup/cpu")
String readSysFsCgroupCpuAcctCpuAcctCfsQuota(final String controlGroup) throws IOException {
@ -353,14 +315,11 @@ public class OsProbe {
}
/**
* The CPU time statistics for all tasks in the Elasticsearch
* control group.
* The CPU time statistics for all tasks in the Elasticsearch control group.
*
* @param controlGroup the control group for the Elasticsearch
* process for the {@code cpuacct} subsystem
* @param controlGroup the control group for the Elasticsearch process for the {@code cpuacct} subsystem
* @return the CPU time statistics
* @throws IOException if an I/O exception occurs reading
* {@code cpu.stat} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpu.stat} for the control group
*/
private OsStats.Cgroup.CpuStat getCgroupCpuAcctCpuStat(final String controlGroup) throws IOException {
final List<String> lines = readSysFsCgroupCpuAcctCpuStat(controlGroup);
@ -388,28 +347,20 @@ public class OsProbe {
}
/**
* Returns the lines from {@code cpu.stat} for the control
* group to which the Elasticsearch process belongs for the
* {@code cpu} subsystem. These lines represent the CPU time
* statistics and have the form
* Returns the lines from {@code cpu.stat} for the control group to which the Elasticsearch process belongs for the {@code cpu}
* subsystem. These lines represent the CPU time statistics and have the form
* <blockquote><pre>
* nr_periods \d+
* nr_throttled \d+
* throttled_time \d+
* </pre></blockquote>
* where {@code nr_periods} is the number of period intervals
* as specified by {@code cpu.cfs_period_us} that have elapsed,
* {@code nr_throttled} is the number of times tasks in the given
* control group have been throttled, and {@code throttled_time} is
* the total time in nanoseconds for which tasks in the given
* control group have been throttled.
* where {@code nr_periods} is the number of period intervals as specified by {@code cpu.cfs_period_us} that have elapsed, {@code
* nr_throttled} is the number of times tasks in the given control group have been throttled, and {@code throttled_time} is the total
* time in nanoseconds for which tasks in the given control group have been throttled.
*
* @param controlGroup the control group to which the Elasticsearch
* process belongs for the {@code cpu}
* subsystem
* @param controlGroup the control group to which the Elasticsearch process belongs for the {@code cpu} subsystem
* @return the lines from {@code cpu.stat}
* @throws IOException if an I/O exception occurs reading
* {@code cpu.stat} for the control group
* @throws IOException if an I/O exception occurs reading {@code cpu.stat} for the control group
*/
@SuppressForbidden(reason = "access /sys/fs/cgroup/cpu")
List<String> readSysFsCgroupCpuAcctCpuStat(final String controlGroup) throws IOException {
@ -419,11 +370,10 @@ public class OsProbe {
}
/**
* Checks if cgroup stats are available by checking for the existence of {@code /proc/self/cgroup},
* {@code /sys/fs/cgroup/cpu}, and {@code /sys/fs/cgroup/cpuacct}.
* Checks if cgroup stats are available by checking for the existence of {@code /proc/self/cgroup}, {@code /sys/fs/cgroup/cpu}, and
* {@code /sys/fs/cgroup/cpuacct}.
*
* @return {@code true} if the stats are available, otherwise
* {@code false}
* @return {@code true} if the stats are available, otherwise {@code false}
*/
@SuppressForbidden(reason = "access /proc/self/cgroup, /sys/fs/cgroup/cpu, and /sys/fs/cgroup/cpuacct")
protected boolean areCgroupStatsAvailable() {
@ -442,8 +392,7 @@ public class OsProbe {
/**
* Basic cgroup stats.
*
* @return basic cgroup stats, or {@code null} if an I/O exception
* occurred reading the cgroup stats
* @return basic cgroup stats, or {@code null} if an I/O exception occurred reading the cgroup stats
*/
private OsStats.Cgroup getCgroup() {
try {
@ -507,8 +456,7 @@ public class OsProbe {
}
/**
* Returns a given method of the OperatingSystemMXBean,
* or null if the method is not found or unavailable.
* Returns a given method of the OperatingSystemMXBean, or null if the method is not found or unavailable.
*/
private static Method getMethod(String methodName) {
try {