Skip to content

Commit

Permalink
Add OpenCensus metric bridge specification (#2979)
Browse files Browse the repository at this point in the history
  • Loading branch information
dashpole authored Nov 28, 2022
1 parent 3ed2087 commit 9dfe23d
Showing 1 changed file with 47 additions and 8 deletions.
55 changes: 47 additions & 8 deletions specification/compatibility/opencensus.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,11 +187,50 @@ 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.

### Requirements

* This component MUST be an optional dependency
* MUST NOT require OpenTelemetry to be included in OpenCensus API distributions
* SHOULD NOT require OpenCensus to depend on OpenTelemetry at runtime
* MUST require few or no changes to OpenCensus
* MUST be compatible with push and pull exporters
* MUST support Gauges, Counters, Cumulative Histograms, and Summaries
* Is NOT REQUIRED to support Gauge Histograms
* MUST support exemplar span context in language that provide utilities for recording span context in 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).
* OpenTelemetry does not support OpenCensus' SumOfSquaredDeviation field; this
is dropped when using the bridge.

0 comments on commit 9dfe23d

Please sign in to comment.