Merge branch 'main' into semantic-convention/alibaba-cloud

open-telemetry · Jul 29, 2021 · 2f9fbad · 2f9fbad
2 parents 134da67 + 09944db
commit 2f9fbad
Show file tree

Hide file tree

Showing 8 changed files with 197 additions and 16 deletions.
diff --git a/.github/auto_assign_issue.yml b/.github/auto_assign_issue.yml
@@ -10,6 +10,7 @@ assignees:
    - bogdandrutu
    - carlosalberto
    - jmacd
+   - jsuereth
    - SergeyKanzhelev
    - tigrannajaryan
    - yurishkuro

diff --git a/.github/auto_assign.yml → .github/auto_assign_pr.yml b/.github/auto_assign.yml → .github/auto_assign_pr.yml
@@ -14,6 +14,7 @@ assigneeGroups:
         - bogdandrutu
         - carlosalberto
         - jmacd
+        - jsuereth
         - SergeyKanzhelev
         - tigrannajaryan
         - yurishkuro

diff --git a/.github/workflows/auto-assign-tc-members.yml → .github/workflows/auto-assign-pr.yml b/.github/workflows/auto-assign-tc-members.yml → .github/workflows/auto-assign-pr.yml
@@ -1,4 +1,4 @@
-name: 'Auto Assign'
+name: 'Auto Assign PR'
 on:
   pull_request_target:
     types: [opened, ready_for_review]
@@ -10,5 +10,5 @@ jobs:
       - name: run
         uses: kentaro-m/[email protected]
         with:
-          configuration-path: ".github/auto_assign.yml"
+          configuration-path: ".github/auto_assign_pr.yml"
           repo-token: '${{ secrets.GITHUB_TOKEN }}'
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,8 +11,13 @@ release.
 
 ### Traces
 
+- Adding SDK configuration for Jaeger remote sampler ([#1791](https://github.com/open-telemetry/opentelemetry-specification/pull/1791))
+
 ### Metrics
 
+- Metrics API specification Feature-freeze.
+  ([#1833](https://github.com/open-telemetry/opentelemetry-specification/pull/1833))
+
 ### Logs
 
 ### Resource
@@ -45,6 +50,7 @@ release.
   ([#1738](https://github.com/open-telemetry/opentelemetry-specification/pull/1738))
 - Clarify meaning of the Certificate File option.
   ([#1803](https://github.com/open-telemetry/opentelemetry-specification/pull/1803))
+- Adding environment variables for event and link attribute limits. ([#1751](https://github.com/open-telemetry/opentelemetry-specification/pull/1751))
 
 ### Metrics
 

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -131,12 +131,12 @@ Note: Support for environment variables is optional.
 |Feature                                       |Go |Java|JS |Python|Ruby|Erlang|PHP|Rust|C++|.Net|Swift|
 |----------------------------------------------|---|----|---|------|----|------|---|----|---|----|-----|
 |OTEL_RESOURCE_ATTRIBUTES                      | + | +  | + | +    | +  | +    | - | +  | + | +  | -   |
-|OTEL_SERVICE_NAME                             |   |    |   |      |    |      |   |    |   |    |     |
+|OTEL_SERVICE_NAME                             | + |    |   |      |    |      |   |    |   |    |     |
 |OTEL_LOG_LEVEL                                | - | -  | + | [-][py1059] | +  | + | -  |    | - | -  | -   |
 |OTEL_PROPAGATORS                              | - | +  |   | +    | +  | +    | - | -  | - | -  | -   |
 |OTEL_BSP_*                                    | - | +  |   | +    | +  | +    | - | +  | - | -  | -   |
 |OTEL_EXPORTER_OTLP_*                          | + | +  |   | +    | +  | -    | - | +  | - | -  | -   |
-|OTEL_EXPORTER_JAEGER_*                        | - |    |   |      |    | -    | - |    | - | -  | -   |
+|OTEL_EXPORTER_JAEGER_*                        | + |    |   |      |    | -    | - |    | - | +  | -   |
 |OTEL_EXPORTER_ZIPKIN_*                        | - |    |   |      |    | -    | - | -  | - | -  | -   |
 |OTEL_TRACES_EXPORTER                          | - | +  |   | +    | +  | +    |   | -  | - |    |     |
 |OTEL_METRICS_EXPORTER                         | - | +  |   | +    | -  | -    |   | -  | - | -  | -   |

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -1,6 +1,6 @@
 # Metrics API
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Feature-freeze](../document-status.md)
 
 <details>
 <summary>

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -33,12 +33,179 @@ Table of Contents
 
 ## MeterProvider
 
-TODO:
+### Meter Creation
+
+New `Meter` instances are always created through a `MeterProvider` (see
+[API](./api.md#meterprovider)). The `name`, `version` (optional), and
+`schema_url` (optional) arguments supplied to the `MeterProvider` MUST be used
+to create an
+[`InstrumentationLibrary`](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md)
+instance which is stored on the created `Meter`.
+
+Configuration (i.e., [MeasurementProcessors](#measurementprocessor),
+[MetricProcessors](#metricprocessor), [MetricExporters](#metricexporter) and
+[`Views`](#view)) MUST be managed solely by the `MeterProvider` and the SDK MUST
+provide a way to configure all options that are implemented by the SDK. This MAY be done at the
+time of MeterProvider creation if appropriate.
+
+The `MeterProvider` MAY provide methods to update the configuration. If
+configuration is updated (e.g., adding a `MetricProcessor`), the updated
+configuration MUST also apply to all already returned `Meters` (i.e. it MUST NOT
+matter whether a `Meter` was obtained from the `MeterProvider` before or after
+the configuration change). Note: Implementation-wise, this could mean that
+`Meter` instances have a reference to their `MeterProvider` and access
+configuration only via this reference.
+
+### Shutdown
+
+TODO
+
+### ForceFlush
+
+TODO
+
+### View
+
+A `View` provides SDK users with the flexibility to customize the metrics that
+are output by the SDK. Here are some examples when a `View` might be needed:
+
+* Customize which [Instruments](./api.md#instrument) are to be
+  processed/ignored. For example, an [instrumented
+  library](../glossary.md#instrumented-library) can provide both temperature and
+  humidity, but the application developer might only want temperature.
+* Customize the aggregation - if the default aggregation associated with the
+  Instrument does not meet the needs of the user. For example, an HTTP client
+  library might expose HTTP client request duration as
+  [Histogram](./api.md#histogram) by default, but the application developer
+  might only want the total count of outgoing requests.
+* Customize which attribute(s) are to be reported as metrics dimension(s). For
+  example, an HTTP server library might expose HTTP verb (e.g. GET, POST) and
+  HTTP status code (e.g. 200, 301, 404). The application developer might only
+  care about HTTP status code (e.g. reporting the total count of HTTP requests
+  for each HTTP status code). There could also be extreme scenarios in which the
+  application developer does not need any dimension (e.g. just get the total
+  count of all incoming requests).
+* Add additional dimension(s) from the [Context](../context/context.md). For
+  example, a [Baggage](../baggage/api.md) value might be available indicating
+  whether an HTTP request is coming from a bot/crawler or not. The application
+  developer might want this to be converted to a dimension for HTTP server
+  metrics (e.g. the request/second from bots vs. real users).
+
+The SDK MUST provide the means to register Views with a `MeterProvider`. Here
+are the inputs:
+
+* The Instrument selection criteria (required), which covers:
+  * The `type` of the Instrument(s) (optional).
+  * The `name` of the Instrument(s), with wildcard support (optional).
+  * The `name` of the Meter (optional).
+  * The `version` of the Meter (optional).
+  * The `schema_url` of the Meter (optional).
+  * Individual language client MAY choose to support more criteria. For example,
+    a strong typed language MAY support point type (e.g. allow the users to
+    select Instruments based on whether the underlying type is integer or
+    double).
+  * The criteria SHOULD be treated as additive, which means the Instrument has
+    to meet _all_ the provided criteria. For example, if the criteria are
+    _instrument name == "Foobar"_ and _instrument type is Histogram_, it will be
+    treated as _(instrument name == "Foobar") AND (instrument type is
+    Histogram)_.
+  * If _none_ the optional criteria is provided, the SDK SHOULD treat it as an
+    error. It is recommended that the SDK implementations fail fast. Please
+    refer to [Error handling in OpenTelemetry](../error-handling.md) for the
+    general guidance.
+* The `name` of the View (optional). If not provided, the Instrument `name`
+  would be used by default. This will be used as the name of the [metrics
+  stream](./datamodel.md#events--data-stream--timeseries).
+* The configuration for the resulting [metrics
+  stream](./datamodel.md#events--data-stream--timeseries):
+  * The `description`. If not provided, the Instrument `description` would be
+    used by default.
+  * A list of `attribute keys` (optional). If not provided, all the attribute
+    keys will be used by default (TODO: once the Hint API is available, the
+    default behavior should respect the Hint if it is available).
+  * The `extra dimensions` which come from Baggage/Context (optional). If not
+    provided, no extra dimension will be used. Please note that this only
+    applies to [synchronous Instruments](./api.md#synchronous-instrument).
+  * The `aggregation` (optional) to be used. If not provided, a default
+    aggregation will be applied by the SDK. The default aggregation is a TODO.
+
+The SDK SHOULD use the following logic to determine how to process Measurements
+made with an Instrument:
+
+* Determine the `MeterProvider` which "owns" the Instrument.
+* If the `MeterProvider` has no `View` registered, take the Instrument and apply
+    the default configuration.
+* If the `MeterProvider` has one or more `View`(s) registered:
+  * For each View, if the Instrument could match the instrument selection
+    criteria:
+    * Try to apply the View configuration. If there is an error (e.g. the View
+      asks for extra dimensions from the Baggage, but the Instrument is
+      [asynchronous](./api.md#asynchronous-instrument) which doesn't have
+      Context) or a conflict (e.g. the View requires to export the metrics using
+      a certain name, but the name is already used by another View), provide a
+      way to let the user know (e.g. expose [self-diagnostics
+      logs](../error-handling.md#self-diagnostics)).
+  * If the Instrument could not match with any of the registered `View`(s), the
+    SDK SHOULD provide a default behavior. The SDK SHOULD also provide a way for
+    the user to turn off the default behavior via MeterProvider (which means the
+    Instrument will be ignored when there is no match). Individual
+    implementations can decide what the default behavior is, and how to turn the
+    default behavior off.
+* END.
+
+Here are some examples:
+
+```python
+# Python
+'''
++------------------+
+| MeterProvider    |
+|   Meter A        |
+|     Counter X    |
+|     Histogram Y  |
+|   Meter B        |
+|     Gauge Z      |
++------------------+
+'''
+
+# metrics from X and Y (reported as Foo and Bar) will be exported
+meter_provider
+    .add_view("X")
+    .add_view("Foo", instrument_name="Y")
+    .add_view(
+        "Bar",
+        instrument_name="Y",
+        aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0]))
+    .set_exporter(PrometheusExporter())
+```
+
+```python
+# all the metrics will be exported using the default configuration
+meter_provider.set_exporter(ConsoleExporter())
+```
 
-* Allow multiple pipelines (processors, exporters).
-* Configure "Views".
-* Configure timing (related to [issue
-  1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)).
+```python
+# all the metrics will be exported using the default configuration
+meter_provider
+    .add_view("*") # a wildcard view that matches everything
+    .set_exporter(ConsoleExporter())
+```
+
+```python
+# Counter X will be exported as cumulative sum
+meter_provider
+    .add_view("X", aggregation=SumAggregation(CUMULATIVE))
+    .set_exporter(ConsoleExporter())
+```
+
+```python
+# Counter X will be exported as delta sum
+# Histogram Y and Gauge Z will be exported with 2 dimensions (a and b)
+meter_provider
+    .add_view("X", aggregation=SumAggregation(DELTA))
+    .add_view("*", attribute_keys=["a", "b"])
+    .set_exporter(ConsoleExporter())
+```
 
 ## MeasurementProcessor
 
@@ -69,13 +236,13 @@ active span](../trace/api.md#context-interaction)).
 +------------------+
 | MeterProvider    |                 +----------------------+            +-----------------+
 |   Meter A        | Measurements... |                      | Metrics... |                 |
-|     Instrument X |-----------------> MeasurementProcessor +------------> In-memory state |
-|     Instrument Y +                 |                      |            |                 |
+|     Instrument X +-----------------> MeasurementProcessor +------------> In-memory state |
+|     Instrument Y |                 |                      |            |                 |
 |   Meter B        |                 +----------------------+            +-----------------+
 |     Instrument Z |
 |     ...          |                 +----------------------+            +-----------------+
 |     ...          | Measurements... |                      | Metrics... |                 |
-|     ...          |-----------------> MeasurementProcessor +------------> In-memory state |
+|     ...          +-----------------> MeasurementProcessor +------------> In-memory state |
 |     ...          |                 |                      |            |                 |
 |     ...          |                 +----------------------+            +-----------------+
 +------------------+
@@ -95,20 +262,20 @@ in the SDK:
 ```text
 +-----------------+            +-----------------+            +-----------------------+
 |                 | Metrics... |                 | Metrics... |                       |
-> In-memory state | -----------> MetricProcessor | -----------> MetricExporter (push) |--> Another process
+| In-memory state +------------> MetricProcessor +------------> MetricExporter (push) +--> Another process
 |                 |            |                 |            |                       |
 +-----------------+            +-----------------+            +-----------------------+
 
 +-----------------+            +-----------------+            +-----------------------+
 |                 | Metrics... |                 | Metrics... |                       |
-> In-memory state |------------> MetricProcessor |------------> MetricExporter (pull) |--> Another process (scraper)
+| In-memory state +------------> MetricProcessor +------------> MetricExporter (pull) +--> Another process (scraper)
 |                 |            |                 |            |                       |
 +-----------------+            +-----------------+            +-----------------------+
 ```
 
 ## MetricExporter
 
-`MetricExporter` defines the interface that protocol-specific exporters must
+`MetricExporter` defines the interface that protocol-specific exporters MUST
 implement so that they can be plugged into OpenTelemetry SDK and support sending
 of telemetry data.
 

diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md
@@ -56,10 +56,16 @@ Known values for `OTEL_TRACES_SAMPLER` are:
 - `"parentbased_always_on"`: `ParentBased(root=AlwaysOnSampler)`
 - `"parentbased_always_off"`: `ParentBased(root=AlwaysOffSampler)`
 - `"parentbased_traceidratio"`: `ParentBased(root=TraceIdRatioBased)`
+- `"jaeger_remote"`: `JaegerRemoteSampler`
 
 Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may be set as follows:
 
 - For `traceidratio` and `parentbased_traceidratio` samplers: Sampling probability, a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset.
+- For `jaeger_remote`: The value is a comma separated list:
+  - `endpoint`: the endpoint in form of `host:port` of gRPC server that serves the sampling strategy for the service ([sampling.proto](https://github.com/jaegertracing/jaeger-idl/blob/master/proto/api_v2/sampling.proto)).
+  - `pollingIntervalMs`:  in milliseconds indicating how often the sampler will poll the backend for updates to sampling strategy.
+  - `initialSamplingRate`:  in the [0..1] range, which is used as the sampling probability when the backend cannot be reached to retrieve a sampling strategy. This value stops having an effect once a sampling strategy is retrieved successfully, as the remote strategy will be used until a new update is retrieved.
+  - Example: `endpoint=localhost:14250,pollingIntervalMs=5000,initialSamplingRate=0.25`
 
 ## Batch Span Processor