Github user srdo commented on a diff in the pull request:
https://github.com/apache/storm/pull/2200#discussion_r126516022
--- Diff: docs/Metrics.md ---
@@ -125,3 +126,193 @@ The [builtin
metrics]({{page.git-blob-base}}/storm-client/src/jvm/org/apache/sto
[BuiltinMetricsUtil.java]({{page.git-blob-base}}/storm-client/src/jvm/org/apache/storm/daemon/metrics/BuiltinMetricsUtil.java)
sets up data structures for the built-in metrics, and facade methods that the
other framework components can use to update them. The metrics themselves are
calculated in the calling code -- see for example
[`ackSpoutMsg`]({{page.git-blob-base}}/storm-client/src/jvm/org/apache/storm/executor/Executor.java).
+#### Reporting Rate
+
+The rate at which built in metrics are reported is configurable through
the `topology.builtin.metrics.bucket.size.secs` metric. If you set this too
low it can overload the consumers
+and some metrics consumers expect metrics to show up at a fixed rate or
the numbers could be off, so please use caution when modifying this.
+
+
+#### Tuple Counting Metrics
+
+There are several different metrics related to counting what a bolt or
spout does to a tuple. These include things like emitting, transferring,
acking, and failing of tuples.
+
+In general all of these tuple count metrics are randomly sub-sampled
unless otherwise state. This means that the counts you see both on the UI and
from the built in metrics are not necessarily exact. In fact by default we
sample only 5% of the events and estimate the total number of events from that.
The sampling percentage is configurable per topology through the
`topology.stats.sample.rate` config. Setting it to 1.0 will make the counts
exact, but be aware that the more events we sample the slower your topology
will run (as the metrics are counted on the critical path). This is why we
have a 5% sample rate as the default.
+
+The tuple counting metrics are generally reported as maps unless
explicitly stated otherwise. They break down each count for finer grained
reporting.
--- End diff --
nit: "generally reported" -> "generally reported to metrics consumers"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
