ctubbsii commented on code in PR #4850: URL: https://github.com/apache/accumulo/pull/4850#discussion_r1737015139
########## core/src/main/java/org/apache/accumulo/core/metrics/Metric.java: ########## @@ -0,0 +1,67 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.accumulo.core.metrics; + +public enum Metric { + SERVER_IDLE("accumulo.server.idle", MetricType.GAUGE, + "Indicates if the server is idle or not. The value will be 1 when idle and 0 when not idle.", + MetricCategory.GENERAL_SERVER), + LOW_MEMORY("accumulo.detected.low.memory", MetricType.GAUGE, + "reports 1 when process memory usage is above threshold, 0 when memory is okay", + MetricCategory.GENERAL_SERVER), + SCAN_BUSY_TIMEOUT_COUNT("accumulo.scan.busy.timeout.count", MetricType.COUNTER, + "Count of the scans where a busy timeout happened", MetricCategory.SCAN_SERVER); + + private final String name; + private final MetricType type; + private final String description; Review Comment: > I think we should add the other fields (related properties, conditions to monitor, recommended actions) I would just be careful to avoid too much prose in the generated docs. I think, like properties, these docs work best like reference documentation (answering "what is it?" rather than "what should I do with it?"), and filling them with a lot of instructional prose makes it harder to use them that way because of the noise. Recommended actions and troubleshooting scenarios tend to fall much more into the "art of debugging" to me, and while I think that kind of content can make good blog posts, how-to guides, or even full books, I don't think it fits well into good concise reference docs. However, if it can be made concise, then it's probably not going to detract from the utility of the docs as a reference. For example, related properties can be concisely referenced with "See: X, Y, Z", and brief explanations of the consequences of abnormal values can sometimes fit in the description like "High values correlate with poor scan performance". So long as we don't find ourselves writing things like "If you see this value consistently above <some threshold> for more than a few seconds, then you may wish to consider tuning property <X>, to something lower, with the understanding that it will have consequence <Y>, unless you allocate more memory (at least <Z>GB) using `-Xmx` in `accumulo-env.sh`). If you do that, take care that it doesn't.... blah blah blah blah". That kind of prose, although it may contain useful information, detracts from the user's ability to consult the reference docs (and is also hard to keep up-to-date and accurate, as we change implementations for p erformance or bug fixes). Example of good reference docs: https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html Example of good "how-to" guide containing reference information, but not well-structured as a reference doc: https://perldoc.perl.org/perlre -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
