Merge branch 'master' into http-sampling

stats/Exemplars.md

@@ -0,0 +1,45 @@
+# Exemplars
+
+Exemplars are example data points for aggregated data. In particular, for distribution-type
+metrics, exemplars are points associated with each bucket in the distribution giving an
+example of what was aggregated into the bucket.
+
+Exemplars consist of a value that was recorded, an exact timestamp of when that value
+was recorded, and a set of attachments.
+
+## Attachments
+
+Exemplars my have zero or more attachments. Attachments are key-value pairs that
+describe the context in which the exemplar was recored.
+
+Implementations should provide an extensible mechanism to extract custom attachments
+from the context.
+
+### Well-known attachment keys
+
+We define the following types of attachments:
+
+1. `trace_id`: lower-case base16 encoded trace ID
+2. `span_id`:  lower-case base16 encoded span ID
+4. `tag:KEY`: tags that were active at the time of recording, regardless of whether
+   they were ultimately added to views or not. `KEY` is the tag key, the value
+   of the attachment is the tag value in effect.
+
+If `trace_id` and `span_id` are provided, the associated trace should be sampled.
+
+## Retention in views
+
+Libraries should attempt to retain and export at least once exemplar per bucket per reporting
+period for distribution-type views. Libraries should not retain an unbounded number
+of exemplars.
+
+Libraries should prefer retaining exemplars with
+[sampled traces](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/Sampling.md)
+associated with them.
+After considering associated trace, libraries should prefer exemplars with more attachments
+over exemplars with fewer or no attachments.
+
+## Exporting
+
+The interpretation of attachments is up to the exporter. Currently, only Stackdriver is known
+to support exemplars.

stats/HTTP.md

@@ -22,7 +22,7 @@ Buckets for distributions in default views are as follows:
 
 ### Measures
 
-Client stats are recorded for each individual HTTP request, including for each individual redirect (followed or not).
+Client stats are recorded for each individual HTTP request, including for each individual redirect (followed or not). All stats are recorded after request processing (usually after the response body has been fully read).
 
 | Measure name                                | Unit | Description                                                                                                                                                                                                                                                                                       |
 |---------------------------------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -32,7 +32,7 @@ Client stats are recorded for each individual HTTP request, including for each i
 
 ### Tags
 
-All client metrics should be tagged with the following.
+All client measures should be tagged with the following.
 
 | Tag name           | Description                                                                                              |
 |--------------------|----------------------------------------------------------------------------------------------------------|
@@ -55,9 +55,9 @@ The following set of views are considered minimum required to monitor client sid
 
 | View name                                   | Measure                                     | Aggregation  | Tags                                   |
 |---------------------------------------------|---------------------------------------------|--------------|----------------------------------------|
-| opencensus.io/http/client/sent_bytes        | opencensus.io/http/client/sent_bytes        | distribution | http_client_method                     |
-| opencensus.io/http/client/received_bytes    | opencensus.io/http/client/received_bytes    | distribution | http_client_method                     |
-| opencensus.io/http/client/roundtrip_latency | opencensus.io/http/client/roundtrip_latency | distribution | http_client_method                     |
+| opencensus.io/http/client/sent_bytes        | opencensus.io/http/client/sent_bytes        | distribution | http_client_method, http_client_status                     |
+| opencensus.io/http/client/received_bytes    | opencensus.io/http/client/received_bytes    | distribution | http_client_method, http_client_status |
+| opencensus.io/http/client/roundtrip_latency | opencensus.io/http/client/roundtrip_latency | distribution | http_client_method, http_client_status |
 | opencensus.io/http/client/completed_count   | opencensus.io/http/client/roundtrip_latency | count        | http_client_method, http_client_status |
 
 ## Server
@@ -66,7 +66,7 @@ Server measures are recorded at the end of request processing.
 
 ### Measures
 
-Server stats are recorded for each individual HTTP request, including for each redirect (followed or not).
+Server stats are recorded for each individual HTTP request handled. They are recorded at the end of request handling.
 
 | Measure name                             | Unit | Description                                                                                                                                                                                                                                                                                   |
 |------------------------------------------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|