[
https://issues.apache.org/jira/browse/BEAM-1974?focusedWorklogId=296264&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-296264
]
ASF GitHub Bot logged work on BEAM-1974:
----------------------------------------
Author: ASF GitHub Bot
Created on: 16/Aug/19 12:47
Start Date: 16/Aug/19 12:47
Worklog Time Spent: 10m
Work Description: RyanSkraba commented on pull request #9328: [BEAM-1974]
Add Metrics user-oriented documentation
URL: https://github.com/apache/beam/pull/9328#discussion_r314703039
##########
File path: website/src/documentation/programming-guide.md
##########
@@ -2907,3 +2907,137 @@ elements, or after a minute.
```py
{% github_sample
/apache/beam/blob/master/sdks/python/apache_beam/examples/snippets/snippets_test.py
tag:model_other_composite_triggers
%}```
+
+## 9. Metrics {#metrics}
+The Beam model provides a way to use different types of metrics in a user
pipeline. There could be
+different reasons for that, for instance:
+* Check the number of errors encountered while running a specific step in
the pipeline;
+* Monitor the number of RPCs made to backend service;
+* Retrieve an accurate count of the number of elements that have been
processed;
+* ...and so on.
+
+### 9.1 The main concepts of Beam metrics
+* **Named**. Each metric has a name which consists of a namespace and an
actual name. The
+ namespace can be used to differentiate between multiple metrics with the
same name and also
+ allows querying for all metrics within a specific namespace.
+* **Scoped**. Each metric is reported against a specific step in the
pipeline, indicating what
+ code was running when the metric was incremented.
+* **Dynamically Created**. Metrics may be created during runtime without
pre-declaring them, in
+ much the same way a logger could be created. This makes it easier to
produce metrics in utility
+ code and have them usefully reported.
+* **Degrade Gracefully**. If a runner doesn’t support some part of reporting
metrics, the
+ fallback behavior is to drop the metric updates rather than failing the
pipeline. If a runner
+ doesn’t support some part of querying metrics, the runner will not return
the associated data.
+
+Reported metrics are implicitly scoped to the transform within the pipeline
that reported them.
+This allows reporting the same metric name in multiple places and identifying
the value each
+transform reported, as well as aggregating the metric across
Review comment:
```suggestion
transform reported, as well as aggregating the metric across the entire
pipeline.
```
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
Issue Time Tracking
-------------------
Worklog Id: (was: 296264)
Time Spent: 40m (was: 0.5h)
> Metrics documentation
> ---------------------
>
> Key: BEAM-1974
> URL: https://issues.apache.org/jira/browse/BEAM-1974
> Project: Beam
> Issue Type: Improvement
> Components: website
> Reporter: Aviem Zur
> Assignee: Alexey Romanenko
> Priority: Major
> Time Spent: 40m
> Remaining Estimate: 0h
>
> Document metrics API and uses (make sure to remark that it is still
> experimental).
--
This message was sent by Atlassian JIRA
(v7.6.14#76016)
