Rename "advice" to "advisory parameters"

CHANGELOG.md

@@ -23,6 +23,8 @@ release.
   ([#3600](https://github.com/open-telemetry/opentelemetry-specification/pull/3600))
 - Clarify that advice is non-identifying.
   ([#3661](https://github.com/open-telemetry/opentelemetry-specification/pull/3661))
+- Rename "advice" to "advisory parameters".
+  ([#3662](https://github.com/open-telemetry/opentelemetry-specification/pull/3662))
 
 ### Logs
 

spec-compliance-matrix.md

@@ -115,15 +115,14 @@ formats is required. Implementing more than one format is optional.
 | Instruments have kind.                                                                                                                                                 |          | +  | +    | +   | +      |      |        | +   |  +   | +   | +    |       |
 | Instruments have an optional unit of measure.                                                                                                                          |          | +  | +    | +   | +      |      |        | +   |  +   | +   | +    |       |
 | Instruments have an optional description.                                                                                                                              |          | +  | +    | +   | +      |      |        | +   |  +   | +   | +    |       |
-| Instruments have an optional advice.                                                                                                                                   |          |    |      |     |        |      |        |     |      |     |      |       |
 | A valid instrument MUST be created and warning SHOULD be emitted when multiple instruments are registered under the same `Meter` using the same `name`.                |          |    | +    | +   | +      |      |        |     |      |     |      |       |
 | Duplicate instrument registration name conflicts are resolved by using the first-seen for the stream name.                                                             |          |    | +    |     |        |      |        |     |      |     |      |       |
 | It is possible to register two instruments with same `name` under different `Meter`s.                                                                                  |          | +  | +    | +   | +      |      |        |     |  +   | +   | +    |       |
 | Instrument names conform to the specified syntax.                                                                                                                      |          | -  | +    |     | +      |      |        |     | +   | +   | +    |       |
 | Instrument units conform to the specified syntax.                                                                                                                      |          | -  | +    |     | +      |      |        |     | +    | +   | +    |       |
 | Instrument descriptions conform to the specified syntax.                                                                                                               |          | -  | +    |     | -      |      |        |     |      | -   | +    |       |
-| Instrument advice supports ExplicitBucketBoundaries.                                                                                                                   |          |    |      |     |        |      |        |     |      |     |      |       |
-| Instrument advice supports Attributes.                                                                                                                                 |          |    |      |     |        |      |        |     |      |     |      |       |
+| Instrument supports the advisory ExplicitBucketBoundaries parameter.                                                                                                                   |          |    |      |     |        |      |        |     |      |     |      |       |
+| Instrument supports the advisory Attributes parameter.                                                                                                                                 |          |    |      |     |        |      |        |     |      |     |      |       |
 | `create_counter` returns a `Counter`.                                                                                                                                  |          | +  | +    | +   | +      |      |        | +   |  +   | +   | +    |       |
 | The API for `Counter` accepts the name, unit and description of the instrument.                                                                                        |          | +  | +    | +   | +      |      |        | +   |  +   | +   | +    |       |
 | `Counter` has an `add` method.                                                                                                                                         |          | +  | +    | +   | +      |      |        | +   |  +   | +   | +    |       |

specification/metrics/api.md

@@ -22,7 +22,7 @@ linkTitle: API
     + [Instrument name syntax](#instrument-name-syntax)
     + [Instrument unit](#instrument-unit)
     + [Instrument description](#instrument-description)
-    + [Instrument advice](#instrument-advice)
+    + [Instrument advisory parameters](#instrument-advisory-parameters)
     + [Synchronous and Asynchronous instruments](#synchronous-and-asynchronous-instruments)
       - [Synchronous Instrument API](#synchronous-instrument-api)
       - [Asynchronous Instrument API](#asynchronous-instrument-api)
@@ -180,14 +180,14 @@ Also see the respective sections below for more information on instrument creati
 ## Instrument
 
 Instruments are used to report [Measurements](#measurement). Each Instrument
-will have the following fields:
+will have the following parameters:
 
 * The `name` of the Instrument
 * The `kind` of the Instrument - whether it is a [Counter](#counter) or
   one of the other kinds, whether it is synchronous or asynchronous
 * An optional `unit` of measure
 * An optional `description`
-* Optional `advice` (**experimental**)
+* Optional `advisory` parameters (**experimental**)
 
 Instruments are associated with the Meter during creation. Instruments
 are identified by the `name`, `kind`, `unit`, and `description`.
@@ -244,17 +244,19 @@ instrument. The API MUST treat it as an opaque string.
 * It MUST support at least 1023 characters. [OpenTelemetry
   API](../overview.md#api) authors MAY decide if they want to support more.
 
-#### Instrument advice
+#### Instrument advisory parameters
 
 **Status**: [Experimental](../document-status.md)
 
-`advice` are an optional set of recommendations provided by the author of the
-Instrument, aimed at assisting implementations in providing useful output with
-minimal configuration.
+`advisory` parameters are an optional set of recommendations provided by the
+author of the Instrument, aimed at assisting implementations in providing
+useful output with minimal configuration. They differ from other parameters
+in that Implementations MAY ignore `advisory` parameters.
 
-* Implementations MAY ignore `advice`. However, OpenTelemetry SDKs
-  handle `advice` as described [here](./sdk.md#instrument-advice).
-* `advice` parameters may be general, or vary by instrument `kind`.
+* OpenTelemetry SDKs MUST handle `advisory` parameters as described
+  [here](./sdk.md#instrument-advisory-parameters).
+* `advisory` parameters may be general, or may be accepted only for specific
+  instrument `kind`s.
   * `Histogram`:
     * `ExplicitBucketBoundaries` (`double[]`): The recommended set of bucket
       boundaries to use if aggregating to
@@ -323,16 +325,16 @@ The API to construct synchronous instruments MUST accept the following parameter
   0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane)
   encoded characters and hold at least 1023 characters.
 
-* `advice` for implementations.
+* `advisory` parameters associated with the instrument `kind`.
 
-  Users can provide `advice`, but its up to their discretion. Therefore, this
-  API needs to be structured to accept `advice`, but MUST NOT obligate the user
-  to provide it.
+  Users can provide `advisory` parameters, but its up to their discretion.
+  Therefore, this API needs to be structured to accept `advisory` parameters,
+  but MUST NOT obligate the user to provide it.
 
-  `advice` needs to be structured as described
-  in [instrument advice](#instrument-advice), with parameters that are general
-  and specific to a particular instrument `kind`. The API SHOULD NOT
-  validate `advice`.
+  `advisory` parameters need to be structured as described in
+  [instrument advisory parameters](#instrument-advisory-parameters), with
+  parameters that are general and specific to a particular instrument `kind`.
+  The API SHOULD NOT validate `advisory` parameters.
 
 ##### Asynchronous Instrument API
 
@@ -375,6 +377,16 @@ The API to construct asynchronous instruments MUST accept the following paramete
   supports at least [BMP (Unicode Plane
   0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane)
   encoded characters and hold at least 1023 characters.
+* `advisory` parameters associated with the instrument `kind`.
+
+  Users can provide `advisory` parameters, but its up to their discretion.
+  Therefore, this API needs to be structured to accept `advisory` parameters,
+  but MUST NOT obligate the user to provide it.
+
+  `advisory` parameters need to be structured as described in
+  [instrument advisory parameters](#instrument-advisory-parameters), with
+  parameters that are general and specific to a particular instrument `kind`.
+  The API SHOULD NOT validate `advisory` parameters.
 * `callback` functions that report [Measurements](#measurement) of the created
   instrument.
 

specification/metrics/sdk.md

@@ -46,7 +46,7 @@ linkTitle: SDK
   * [Instrument name](#instrument-name)
   * [Instrument unit](#instrument-unit)
   * [Instrument description](#instrument-description)
-  * [Instrument advice](#instrument-advice)
+  * [Instrument advisory parameters](#instrument-advisory-parameters)
 - [Attribute limits](#attribute-limits)
 - [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
@@ -322,8 +322,9 @@ The SDK MUST accept the following stream configuration parameters:
   Therefore, the stream configuration parameter needs to be structured to
   accept `attribute_keys`, but MUST NOT obligate a user to provide them.
   If the user does not provide any value, the SDK SHOULD use
-  the [`advice`](./api.md#instrument-advice) configured on the instrument
-  instead. If the `advice` is absent, all attributes MUST be kept.
+  the [`Attributes`](./api.md#instrument-advisory-parameters) advisory
+  parameter configured on the instrument instead. If the `Attributes`
+  advisory parameter is absent, all attributes MUST be kept.
 
 * `aggregation`: The name of an [aggregation](#aggregation) function to use in
   aggregating the metric stream data.
@@ -518,8 +519,8 @@ This Aggregation does not have any configuration parameters.
 #### Default Aggregation
 
 The Default Aggregation informs the SDK to use the Instrument `kind` to select
-an aggregation and `advice` to influence aggregation configuration parameters
-(as noted in the "Selected Aggregation" column).
+an aggregation and `advisory` parameters to influence aggregation configuration
+parameters (as noted in the "Selected Aggregation" column).
 
 | Instrument Kind                                                   | Selected Aggregation                                                                                                                                                           |
 |-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -529,7 +530,7 @@ an aggregation and `advice` to influence aggregation configuration parameters
 | [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation)                                                                                                                                    |
 | [Gauge](./api.md#gauge)                                           | [Last Value Aggregation](./sdk.md#last-value-aggregation)                                                                                                                      |
 | [Asynchronous Gauge](./api.md#asynchronous-gauge)                 | [Last Value Aggregation](./sdk.md#last-value-aggregation)                                                                                                                      |
-| [Histogram](./api.md#histogram)                                   | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with `ExplicitBucketBoundaries` from [advice](./api.md#instrument-advice) if provided |
+| [Histogram](./api.md#histogram)                                   | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with the `ExplicitBucketBoundaries` [advisory parameter](./api.md#instrument-advisory-parameters) if provided |
 
 This Aggregation does not have any configuration parameters.
 
@@ -848,12 +849,12 @@ When a Meter creates an instrument, it SHOULD NOT validate the instrument
 description. If a description is not provided or the description is null, the
 Meter MUST treat it the same as an empty description string.
 
-### Instrument advice
+### Instrument advisory parameters
 
 **Status**: [Experimental](../document-status.md)
 
-When a Meter creates an instrument, it SHOULD validate the instrument advice
-parameters. If an advice parameter is not valid, the Meter SHOULD emit an error
+When a Meter creates an instrument, it SHOULD validate the instrument advisory
+parameters. If an advisory parameter is not valid, the Meter SHOULD emit an error
 notifying the user and proceed as if the parameter was not provided.
 
 If multiple [identical Instruments](api.md#instrument) are created with

specification/metrics/semantic_conventions/http-metrics.md

@@ -62,7 +62,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 This metric is required.
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
 
 <!-- semconv metric.http.server.duration(metric_table) -->
@@ -247,7 +247,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 This metric is required.
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
 
 <!-- semconv metric.http.client.duration(metric_table) -->

specification/metrics/semantic_conventions/runtime-environment-metrics.md

@@ -222,7 +222,7 @@ This metric is obtained by subscribing to
 [`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--)
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advice)
+[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advisory-parameters)
 of `[]` (single bucket histogram capturing count, sum, min, max).
 
 <!-- semconv metric.process.runtime.jvm.gc.duration(metric_table) -->