Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Combined Metrics API updates for v0.3 (Add Observer instrument, remove Gauge instrument, etc.) #430

Merged
merged 57 commits into from
Feb 14, 2020
Merged
Changes from 1 commit
Commits
Show all changes
57 commits
Select commit Hold shift + click to select a range
3e17050
Gauge/Observer rewrite pt 1
Jan 23, 2020
56e1606
Checkpoint
Jan 28, 2020
4f4f4f8
Checkpoint
Jan 28, 2020
12339db
Optional features restored
Jan 28, 2020
5945fa3
Update selection process
Jan 29, 2020
da61304
Update TOC
Jan 29, 2020
c70cc97
Upstream
Jan 29, 2020
cc9caef
Reword intro para on standard impl
Jan 29, 2020
210491e
Add detail on label set
Jan 29, 2020
891759e
Add examples
Jan 30, 2020
a68d28c
Misspellings
Feb 4, 2020
610056b
Rewrite the introductory material
Feb 5, 2020
4f85830
Add a section on time
Feb 6, 2020
23a3430
Clarify 'standard implementation' and 'default interpretation'
Feb 6, 2020
c97fefd
Explain aggregations; Discourage timestamp use
Feb 6, 2020
ab5088c
Reword the metric event format
Feb 6, 2020
da8f189
Update Counter and Measure
Feb 6, 2020
afa0bb1
Update Observer (partial)
Feb 6, 2020
a0730c6
Remove options, discuss views API
Feb 6, 2020
e1298ea
Fixes
Feb 7, 2020
cf896f3
Fixes
Feb 7, 2020
baba6e4
Fixes
Feb 7, 2020
12753e0
Rename BoundTimer
Feb 11, 2020
b3da9d1
Typos and suggestions
Feb 11, 2020
445a8a8
Reword global Meter
Feb 11, 2020
3325599
Rearrange early paragraphs
Feb 11, 2020
21fd3e0
Use _run time_ and _simultaneous_
Feb 11, 2020
bb16feb
Rearrange early paragraphs (again)
Feb 11, 2020
01ae0d5
Define _run time_
Feb 11, 2020
f92b42b
These
Feb 11, 2020
d651afa
Iterate
Feb 11, 2020
49c19d4
Remove a TODO
Feb 11, 2020
a53ad58
More on global/named meters
Feb 11, 2020
313cd32
Difference, Capture
Feb 11, 2020
968caff
Timer wording
Feb 11, 2020
0faf458
Explicit timestamp
Feb 11, 2020
0081967
Rewrite simultaneous
Feb 11, 2020
bd1e06f
Example: active requests
Feb 11, 2020
b0ef3e4
Synchronously
Feb 11, 2020
cb3d369
Wording
Feb 11, 2020
dc61b4e
Example using correlation context
Feb 11, 2020
6dce940
Detail on WithKeys
Feb 11, 2020
ec8b3d5
Counter is a special case
Feb 11, 2020
775725f
Counter fixes; typo
Feb 11, 2020
245db59
Typo
Feb 11, 2020
81ac205
Split the leading example into Counter and Measure cases
Feb 11, 2020
7b56958
Remove poor example
Feb 11, 2020
52be8c9
Upstream
Feb 11, 2020
dfe0446
Update TOC
Feb 11, 2020
641a397
Add note about Observer and Context
Feb 11, 2020
c1b7c10
Add note about context-freedom in Observer
Feb 11, 2020
6accb05
Run MDL
Feb 11, 2020
18bdaa8
WithRecommendedKeys
Feb 11, 2020
e51023d
Typo
Feb 12, 2020
6ebfb6e
Address most of Bogdan's feedback
Feb 13, 2020
9f186b5
Typo
Feb 13, 2020
2a74584
Merge branch 'master' into jmacd/api-metrics-03
bogdandrutu Feb 14, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Clarify 'standard implementation' and 'default interpretation'
  • Loading branch information
jmacd committed Feb 6, 2020
commit 23a3430f51cfefe3fb2804c96e1258965a2c1a51
19 changes: 10 additions & 9 deletions specification/api-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ is used extensively in this document to define and explain these API
functions and how we should interpret them. As far as possible, the
terminology used here tries to convey the intended semantics, and a
_standard implementation_ will be described below to help us
understand their meaning. The standard implementation defined here
corresponds to the behavior of the default [OpenTelemetry Metrics
Default SDK](TODO: after PR #347 merges).
understand their meaning. The standard implementation performs
aggregation corresponding to the default interpretation for each kind
of metric event.

### Metric Instruments

Expand Down Expand Up @@ -185,19 +185,19 @@ events produced through an instrument consist of:
- an implicit timestamp at the moment the API function is called
- the instrument definition (name, kind, and options)
- a value (numeric)
- a [Context](api-context.md) (span context, correlation context)
- a label set
- a [Context](api-context.md)

This is the outcome of separating the API from the SDK--a common
representation for metric events, where the only semantic distinction
is the kind of instrument that was used.

## Three kinds of instrument

Because of API-SDK separation, the `Meter` implementation ultimately
determines how metrics events are handled. Therefore, the choice of
instrument should be guided by semantics and the intended
interpretation. Here we detail the three instruments.
Because the API is separated from the SDK, the implementation
ultimately determines how metric events are handled. Therefore, the
choice of instrument should be guided by semantics and the intended
interpretation. Here we detail the three instruments and their semantics.

### Counter

Expand All @@ -206,7 +206,8 @@ to monitor rates, and they are sometimes used to report totals. One
key property of Counter instruments is that two `Add(1)` events are
semantically equivalent to one `Add(2)` event--`Add(m)` and `Add(n)`
is equivalent to `Add(m+n)`. This means that Counter events can be
combined using addition, by definition.
combined using addition, by definition, which makes them relatively
inexpensive

Labels associated with Counter instrument events can be used to
compute rates and totals over selected dimensions. When aggregating
Expand Down