docs: update OpenCensus shim example for metrics (#4078)

experimental/examples/opencensus-shim/README.md

@@ -9,6 +9,8 @@ The example has:
 - Root Spans (on client), instrumented with OpenCensus's HTTP instrumentation
 - Child Span from a remote parent (on server), instrumented with OpenCensus's HTTP instrumentation
 - Another Child Span created in the server representing some work being done, instrumented manually with OpenTelemetry.
+- Server metrics coming from OpenCensus's HTTP instrumentation, available through the
+OpenTelemetry's Prometheus exporter.
 
 ## Installation
 
@@ -64,6 +66,14 @@ Go to Jaeger with your browser <http://localhost:16686/> and click on the "Servi
 
 <p align="center"><img src="./images/jaeger-trace.png"/></p>
 
+## Check the Prometheus metrics
+
+Load the Prometheus metrics endpoint of the server at <http://localhost:9464/metrics> in your
+browser. You should see the `opencensus_io_http_server_*` related metrics in
+the output.
+
+<p align="center"><img src="./images/prom-metrics.png"/></p>
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

experimental/examples/opencensus-shim/package.json

@@ -28,10 +28,13 @@
   },
   "dependencies": {
     "@opencensus/core": "0.1.0",
+    "@opencensus/instrumentation-http": "0.1.0",
     "@opencensus/nodejs-base": "0.1.0",
     "@opentelemetry/api": "1.6.0",
+    "@opentelemetry/exporter-prometheus": "0.43.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "0.43.0",
     "@opentelemetry/resources": "1.17.0",
+    "@opentelemetry/sdk-metrics": "1.17.0",
     "@opentelemetry/sdk-trace-node": "1.17.0",
     "@opentelemetry/semantic-conventions": "1.17.0",
     "@opentelemetry/shim-opencensus": "0.43.0"

experimental/examples/opencensus-shim/server.js

@@ -5,6 +5,8 @@ const setup = require('./setup');
 const utils = require('./utils');
 const { trace } = require('@opentelemetry/api');
 
+const oc = require('@opencensus/core');
+
 setup('opencensus-shim-example-server');
 const http = require('http');
 

experimental/examples/opencensus-shim/setup.js

@@ -15,37 +15,64 @@
  */
 'use strict';
 
-const { DiagConsoleLogger, diag, DiagLogLevel } = require('@opentelemetry/api');
+const { diag, metrics } = require('@opentelemetry/api');
 const {
   NodeTracerProvider,
   BatchSpanProcessor,
 } = require('@opentelemetry/sdk-trace-node');
+const { MeterProvider } = require('@opentelemetry/sdk-metrics');
 const {
   OTLPTraceExporter,
 } = require('@opentelemetry/exporter-trace-otlp-grpc');
+const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
 const { Resource } = require('@opentelemetry/resources');
 const {
   SemanticResourceAttributes,
 } = require('@opentelemetry/semantic-conventions');
+const { OpenCensusMetricProducer } = require('@opentelemetry/shim-opencensus');
+const instrumentationHttp = require('@opencensus/instrumentation-http');
+const { TracingBase } = require('@opencensus/nodejs-base');
+const oc = require('@opencensus/core');
 
 module.exports = function setup(serviceName) {
-  const tracing = require('@opencensus/nodejs-base');
+  /**
+   * You can alternatively just use the @opentelemetry/nodejs package directly:
+   *
+   * ```js
+   * const tracing = require('@opencensus/nodejs');
+   * ```
+   */
+  const tracing = new TracingBase(['http']);
+  tracing.tracer = new oc.CoreTracer();
 
-  diag.setLogger(new DiagConsoleLogger(), { logLevel: DiagLogLevel.ALL });
-  const provider = new NodeTracerProvider({
-    resource: new Resource({
-      [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
-    }),
+  const resource = new Resource({
+    [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
   });
-  provider.addSpanProcessor(
+  const tracerProvider = new NodeTracerProvider({ resource });
+  tracerProvider.addSpanProcessor(
     new BatchSpanProcessor(new OTLPTraceExporter(), {
       scheduledDelayMillis: 5000,
     })
   );
-  provider.register();
+  tracerProvider.register();
+
+  const meterProvider = new MeterProvider({ resource });
+  meterProvider.addMetricReader(
+    new PrometheusExporter({
+      metricProducers: [
+        new OpenCensusMetricProducer({
+          openCensusMetricProducerManager:
+            oc.Metrics.getMetricProducerManager(),
+        }),
+      ],
+    })
+  );
+  metrics.setGlobalMeterProvider(meterProvider);
 
   // Start OpenCensus tracing
-  tracing.start({ samplingRate: 1, logger: diag });
+  tracing.start({ samplingRate: 1, logger: diag, stats: oc.globalStats });
+  // Register OpenCensus HTTP stats views
+  instrumentationHttp.registerAllViews(oc.globalStats);
 
-  return provider;
+  return tracerProvider;
 };

experimental/packages/shim-opencensus/README.md

@@ -13,11 +13,11 @@ More details are available in the [OpenCensus Compatibility Specification](https
 npm install --save @opentelemetry/shim-opencensus
 ```
 
-## Usage
+## Tracing usage
 
 ### Installing the shim's require-in-the-middle hook
 
-This is the recommended way to use the shim.
+This is the recommended way to use the shim for tracing.
 
 This package provides a `require-in-the-middle` hook which replaces OpenCensus's `CoreTracer`
 class with a shim implementation that writes to the OpenTelemetry API. This will cause all
@@ -72,6 +72,25 @@ tracer.startRootSpan({name: 'main'}, rootSpan => {
 });
 ```
 
+## Metrics usage
+
+OpenCensus metrics can be collected and sent to an OpenTelemetry exporter by providing the
+`OpenCensusMetricProducer` to your `MetricReader`. For example, to export OpenCensus metrics
+through the OpenTelemetry Prometheus exporter:
+
+```js
+meterProvider.addMetricReader(
+  new PrometheusExporter({
+    metricProducers: [
+      new OpenCensusMetricProducer({
+        openCensusMetricProducerManager:
+          oc.Metrics.getMetricProducerManager(),
+      }),
+    ],
+  })
+);
+```
+
 ## Example
 
 See [examples/opencensus-shim](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/examples/opencensus-shim) for a short example.