Skip to content

Commit

Permalink
add opencensus metric bridge specification
Browse files Browse the repository at this point in the history
  • Loading branch information
dashpole committed Aug 16, 2022
1 parent 4f8d9f6 commit f1e5146
Showing 1 changed file with 49 additions and 8 deletions.
57 changes: 49 additions & 8 deletions specification/compatibility/opencensus.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,11 +187,52 @@ OpenCensus specifies the following [HTTP Attributes](https://github.com/census-i

## 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.
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.

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.

### Requirements

* This component MUST be an optional dependency.
* MUST NOT require OpenCensus to depend on OpenTelemetry
* MUST require few or no changes to OpenCensus
* 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

### Resource

The shim MUST discard the resource attached to OpenCensus metrics, and insert
the resource provided during initialization, or fall back to the the default
OpenTelemetry resource.

### Metric Attributes

Metric attributes SHOULD be mapped following
[semantic convention mappings](#semantic-convention-mappings).

### 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 support OpenCensus' GaugeHistogram type; these metrics
MUST be dropped when using the bridge.
* OpenTelemetry does not currently support context-based attributes (tags).

0 comments on commit f1e5146

Please sign in to comment.