spec updates to make base metrics be optional

Signed-off-by: Don Bourne <dbourne@ca.ibm.com>

spec/src/main/asciidoc/app-programming-model.adoc

@@ -500,7 +500,7 @@ MetricRegistry metricRegistry;
 ----
 
 ==== Base Metric Registry
-The implementation must produce the _base_ `MetricRegistry` when the `RegistryScope` is `base` (i.e. `MetricRegistry.BASE_SCOPE`). The _base_ `MetricRegistry` must contain the required metrics specified in <<required-metrics#required-metrics>>.
+The implementation must produce the _base_ `MetricRegistry` when the `RegistryScope` is `base` (i.e. `MetricRegistry.BASE_SCOPE`). The _base_ `MetricRegistry` contains any metrics the vendor has chosen to provide from <<base-metrics#base-metrics>>.
 
 .Example of the application injecting the base registry
 [source, java]

spec/src/main/asciidoc/architecture.adoc

@@ -24,7 +24,7 @@
 This chapter describes the architectural overview of how metrics are setup, stored and exposed for consumption.
 This chapter also lists the various scopes of metrics.
 
-See section <<required-metrics#required-metrics>> for more information regarding metrics that are required for each vendor.
+See section <<base-metrics#base-metrics>> for more information regarding spec-described metrics that vendors may provide.
 
 See section <<app-programming-model#app-programming-model>> for more information regarding the application metrics programming model.
 
@@ -35,31 +35,32 @@ Metrics that are exposed need to be configured in the server. On top of the pure
 
 The following three sets of sub-resource (scopes) are exposed.
 
-* base: metrics that all MicroProfile vendors have to provide
+* base: spec-described metrics that vendors may provide (optional)
 * vendor: vendor specific metrics (optional)
 * application: application-specific metrics (optional)
 
 [[scopes]]
 ==== Scopes
 
-===== Required Base metrics
+===== Base metrics
 
-Required base metrics describe a set of metrics that all MicroProfile-compliant servers have to provide.
-Each vendor can implement the set-up of the metrics in the _base_ scope in a vendor-specific way.
+Base metrics describe a set of optional metrics that MicroProfile-compliant servers may provide. 
+Vendors may choose to implement all of the base metrics, some of them, or none of them. They are provided to ensure consistency between vendors that choose to implement them. 
+One reason vendors may choose to use a different set of metrics is that the metrics libraries they are using in their implementation come with metrics with a similar purpose to the spec-described base metrics.
+If vendors choose to use different metrics, for example to measure values related to the JVM, they must do so using the _vendor_ scope for those metrics.
+If vendors choose to use these base scope metrics, they can implement the set-up of the metrics in a vendor-specific way.
 The metrics can be hard coded into the server or read from a configuration file or supplied via the Java-API described in <<app-programming-model#app-programming-model>>.
 The Appendix shows a possible data format for such a configuration.
-The configuration and set up of the _base_ scope is thus an implementation detail and is not expected to be portable across vendors.
+The configuration and set up of the base scope is thus an implementation detail and is not expected to be portable across vendors.
 
-Section <<required-metrics#required-metrics>> lists the required metrics. This list also includes a few items marked as optional.
-These are listed here as they are dependent on the underlying JVM and not the server and thus fit better in _base_ scope
-than the _vendor_ one.
+Section <<base-metrics#base-metrics>> lists the base metrics.
 
-The implementation must tag base metrics with `scope=base`.
+The implementation must tag base metrics with `mp_scope=base`.
 
-Required base metrics are exposed under `/metrics?scope=base`.
+Base metrics are exposed under `/metrics?scope=base`.
 
 The `base` scope is used for, and only for, any metrics that are defined in MicroProfile specifications. 
-Metrics in the base scope are intended to be portable between different MicroProfile-compatible runtimes at the same version.
+Metrics in the base scope, where implemented, are intended to be portable between different MicroProfile-compatible runtimes at the same version.
 
 ===== Application metrics
 

spec/src/main/asciidoc/required-metrics.adoc → spec/src/main/asciidoc/base-metrics.adoc

@@ -17,16 +17,16 @@
 // limitations under the License.
 //
 
-[[required-metrics]]
-== Required Metrics
+[[base-metrics]]
+== Base Metrics
 
-Base metrics is a list of metrics that all vendors need to implement. Optional base metrics are recommended to be implemented but are not required.
+Base metrics is an optional list of metrics that vendors may implement in whole or in part.
 These metrics are exposed under `/metrics/base`.
 
-The following is a list of required and optional base metrics. All metrics are singletons and have `Multi:` set to `false` unless otherwise stated.
+The following is a list of base metrics. All metrics are singletons and have `Multi:` set to `false` unless otherwise stated.
 Visit <<architecture#meta-data-def>> for the meaning of each key
 
-NOTE: Although vendors are required to implement these base metrics, some virtual machines can not provide them.
+NOTE: Some virtual machines can not provide the data required for some of the base metrics.
 Vendors should either use other metrics that are close enough as substitute or not fill these base metrics at all.
 
 
@@ -134,7 +134,7 @@ Vendors should either use other metrics that are close enough as substitute or n
 
 === Thread Pool Stats
 
-*(Optional) ActiveThreads*
+*ActiveThreads*
 [cols="1,4"]
 |===
 |Name| threadpool.activeThreads
@@ -146,7 +146,7 @@ Vendors should either use other metrics that are close enough as substitute or n
 |Notes| The %s should be substituted with the name of the thread pool. This is a vendor specific attribute/operation that is not defined in java.lang.
 |===
 
-*(Optional) PoolSize*
+*PoolSize*
 [cols="1,4"]
 |===
 |Name| threadpool.size
@@ -202,7 +202,7 @@ Vendors should either use other metrics that are close enough as substitute or n
 |MBean| java.lang:type=OperatingSystem/AvailableProcessors
 |===
 
-*(Optional) SystemLoadAverage*
+*SystemLoadAverage*
 [cols="1,4"]
 |===
 |Name| cpu.systemLoadAverage
@@ -212,7 +212,7 @@ Vendors should either use other metrics that are close enough as substitute or n
 |MBean| java.lang:type=OperatingSystem/SystemLoadAverage
 |===
 
-*(Optional) ProcessCpuLoad*
+*ProcessCpuLoad*
 [cols="1,4"]
 |===
 |Name| cpu.processCpuLoad
@@ -223,7 +223,7 @@ Vendors should either use other metrics that are close enough as substitute or n
 Note: This is a vendor specific attribute/operation that is not defined in java.lang
 |===
 
-*(Optional) ProcessCpuTime*
+*ProcessCpuTime*
 [cols="1,4"]
 |===
 |Name| cpu.processCpuTime
@@ -235,17 +235,15 @@ Note: This is a vendor specific attribute/operation that is not defined in java.
 |===
 
 
-=== (Optional) REST
+=== REST
 
-Metrics gathered from REST stats are optional and therefore may not be available in every implementation.
-
-The MicroProfile Metrics runtime will track metrics from RESTful resource method calls during runtime (i.e GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD). It is up to the implementation to decide how to enable the REST metrics.
+The MicroProfile Metrics runtime may track metrics from RESTful resource method calls during runtime (ie. GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD). It is up to the implementation to decide how to enable the REST metrics.
 
 === Mapped and Unmapped Exceptions
 
 The metrics defined below will treat a REST request that ends in a mapped exception or an unmapped exception differently. For the MicroProfile Metrics runtime, mapped exceptions and _succesful_ REST requests should be considered and handled the same way. This is because mapped exceptions are expected by the developer and may then be handled appropriately as part of the application's expected behviour.  Unmapped exceptions on the other hand are unexpected and can skew metric data if its' respective REST request is recorded. To avoid contaminating the metric values with these _unsuccesful_ REST requests, the below metrics may omit tracking a REST request that ends with an unmapped exception. There are also metrics that purposely track REST requests that end with an unmapped exception.
 
-*(Optional) RESTRequest*
+*RESTRequest*
 [cols="1,4"]
 |===
 |Name| REST.request
@@ -268,7 +266,7 @@ Parameter type formatting rules: +
 
 |===
 
-*(Optional) RESTRequestUnmappedExceptions*
+*RESTRequestUnmappedExceptions*
 [cols="1,4"]
 |===
 |Name| REST.request.unmappedException.total

spec/src/main/asciidoc/microprofile-metrics-spec.asciidoc

@@ -54,7 +54,7 @@ include::architecture.adoc[]
 
 include::rest-endpoints.adoc[]
 
-include::required-metrics.adoc[]
+include::base-metrics.adoc[]
 
 include::app-programming-model.adoc[]