specify the OpenCensus metrics shim

specification/compatibility/opencensus.md

@@ -72,16 +72,26 @@ Compatibility for these is defined separately.
 
 ## Goals
 
-OpenTelemetry<->OpenCensus compatibility has the following goals:
+OpenTelemetry<->OpenCensus bridges:
 
-1. OpenCensus has no hard dependency on OpenTelemetry
-2. Minimal changes to OpenCensus for implementation
-3. Easy for users to use, ideally no change to their code
+* MUST NOT require OpenCensus to depend on OpenTelemetry
+* MUST require few or no changes to OpenCensus
+* MUST convert HTTP and gRPC OpenCensus semantic conventions to OpenTelemetry semantic conventions for metric and span names and attributes
+* are NOT REQUIRED to support the entire OpenCensus instrumentation API Surface.
+* MUST NOT require users to change instrumentation to migrate
 
 Additionally, for tracing there are the following goals:
 
-1. Maintain parent-child span relationship between applications and libraries
-2. Maintain span link relationships between applications and libraries
+* MUST maintain parent-child span relationship between interleaved OpenCensus and OpenTelemetry instrumentation
+* MUST Maintain span link relationships between interleaved OpenCensus and OpenTelemetry instrumentation
+* MUST preseve span contents where an OpenTelemetry equivalent exists
+
+Additionally, for monitoring there are the following goals:
+
+* MUST be compatible with push and pull exporters
+* MUST support Gauges, Counters, Cumulative Histograms, and Summaries
+* are NOT REQUIRED to support Gauge Histograms
+* MUST support exemplars
 
 ## Trace
 
@@ -163,15 +173,52 @@ implementation may be drawn from OpenCensus if applicable.
 
 Note: resources appear not to be usable in the "API" section of OpenCensus.
 
-### Semantic Convention Mappings
+## Metrics / Stats
+
+OpenTelemetry will provide an OpenCensus-Metrics-Shim component which
+implements the OpenTelemetry [MetricProducer](../metrics/sdk.md#metricproducer)
+interface. When Produce() is invoked, the shim collects metrics from the
+OpenCensus global state, converts the metrics to an OpenTelemetry metrics
+batch, and returns.
+
+This component MUST be an optional dependency.
+
+To construct a shim, the caller MUST be able to provide the following:
+
+* A resource (optional) to attach to metrics batches. If not provided, the
+default resource is used.
+
+### Resource
+
+The shim MUST discard the resource attached to OpenCensus metrics, and insert
+the resource provided during initialization.
+
+### Instrumentation Scope
+
+The shim MUST add an instrumentation scope name and version which identifies
+the shim.
+
+### Usage
+
+The shim can be passed as an option to an OpenTelemetry
+[MetricReader](../metrics/sdk.md#metricreader) when configuring the
+OpenTelemetry SDK. This enables the bridge to work with both push and pull
+metric exporters.
+
+#### Known Incompatibilities
+
+* OpenTelemetry does not suport OpenCensus' GaugeHistogram type; these metrics
+  MUST be dropped when using the bridge.
+
+## Semantic Convention Mappings
 
 Where possible, the tracing shim should provide mappings of labels to attributes
 defined within the OpenTelemetry semantic convetions.
 
 > The principle is to ensure OpenTelemetry exporters, which use these semantic
 > conventions, are likely to export the correct data.
 
-#### HTTP Attributes
+### HTTP Attributes
 
 OpenCensus specifies the following [HTTP Attributes](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md#attributes):
 
@@ -183,15 +230,4 @@ OpenCensus specifies the following [HTTP Attributes](https://github.com/census-i
 | `http.status_code` | `http.status_code` |                      |
 | `http.url`         | `http.url`         |                      |
 | `http.path`        | `http.target`      | key-name change only |
-| `http.route`       | N/A                | Pass through ok      |
-
-## Metrics / Stats
-
-Metric compatibility with OpenCensus remains unspecified as the OpenTelemetry
-metrics specification solidifies for GA.   Once GA on metrics is declared,
-this section will be filled out.
-
-> Philosophically, this should follow the same principles as Trace.
-> Specifically: Metric names/attributes should be converted to OTel semantic
-> conventions, All API surface area should map to the closest relevant OTel
-> API and no SDK usage of OpenCensus will be compatible.
+| `http.route`       | N/A                | Pass through ok      |