refactor(metrics): export pipeline

getting-started/ts-example/monitoring.ts

@@ -1,20 +1,13 @@
-import { MeterProvider } from '@opentelemetry/metrics';
-import { Metric, BoundCounter } from '@opentelemetry/api';
-import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
+import { metrics, Metric, BoundCounter } from '@opentelemetry/api';
+import { installExportPipeline } from '@opentelemetry/exporter-prometheus';
 
-const exporter = new PrometheusExporter(
-  {
-    startServer: true,
-  },
-  () => {
-    console.log('prometheus scrape endpoint: http://localhost:9464/metrics');
-  },
-);
+installExportPipeline({
+  startServer: true,
+}, () => {
+  console.log('prometheus scrape endpoint: http://localhost:9464/metrics');
+});
 
-const meter = new MeterProvider({
-  exporter,
-  interval: 1000,
-}).getMeter('example-ts');
+const meter = metrics.getMeter('example-ts');
 
 const requestCount: Metric<BoundCounter> = meter.createCounter("requests", {
   monotonic: true,

packages/opentelemetry-exporter-prometheus/README.md

@@ -12,27 +12,23 @@ The OpenTelemetry Prometheus Metrics Exporter allows the user to send collected
 ## Installation
 
 ```bash
-npm install --save @opentelemetry/metrics
-npm install --save @opentelemetry/exporter-prometheus
+npm install --save @opentelemetry/exporter-prometheus @opentelemetry/api
 ```
 
 ## Usage
 
 Create & register the exporter on your application.
 
 ```js
-const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
-const { MeterProvider }  = require('@opentelemetry/metrics');
+const prometheus = require('@opentelemetry/exporter-prometheus');
+const api  = require('@opentelemetry/api');
 
 // Add your port and startServer to the Prometheus options
-const options = {port: 9464, startServer: true};
-const exporter = new PrometheusExporter(options);
+const options = { port: 9464, startServer: true };
+prometheus.installExportPipeline(options);
 
 // Register the exporter
-const meter = new MeterProvider({
-  exporter,
-  interval: 1000,
-}).getMeter('example-prometheus');
+const meter = api.metrics.getMeter('example-prometheus');
 
 // Now, start recording data
 const counter = meter.createCounter('metric_name', {

packages/opentelemetry-exporter-prometheus/src/export/export-pipeline.ts

@@ -0,0 +1,38 @@
+/*!
+ * Copyright 2020, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as api from '@opentelemetry/api';
+import { PullController } from '@opentelemetry/metrics';
+import { PrometheusExporter } from '../prometheus';
+import { ExporterConfig } from './types';
+
+/**
+ * Install Prometheus export pipeline to global metrics api.
+ * @param exporterConfig Exporter configuration
+ * @param callback Callback to be called after a server was started
+ * @param controllerConfig Default meter configuration
+ */
+export function installExportPipeline(
+  exporterConfig?: ExporterConfig,
+  callback?: () => void,
+  controllerConfig?: ConstructorParameters<typeof PullController>[0]
+) {
+  const exporter = new PrometheusExporter(exporterConfig, callback);
+  const pullController = new PullController({ ...controllerConfig, exporter });
+  exporter.setPullCallback(() => pullController.collect());
+  api.metrics.setGlobalMeterProvider(pullController);
+  return { exporter, controller: pullController };
+}

packages/opentelemetry-exporter-prometheus/src/index.ts

@@ -16,3 +16,4 @@
 
 export * from './prometheus';
 export * from './export/types';
+export * from './export/export-pipeline';

packages/opentelemetry-exporter-prometheus/src/prometheus.ts

@@ -50,6 +50,7 @@ export class PrometheusExporter implements MetricExporter {
   private readonly _server: Server;
   private readonly _prefix?: string;
   private readonly _invalidCharacterRegex = /[^a-z0-9_]/gi;
+  private _pullCallback: (() => void) | undefined;
 
   // This will be required when histogram is implemented. Leaving here so it is not forgotten
   // Histogram cannot have a label named 'le'
@@ -117,6 +118,15 @@ export class PrometheusExporter implements MetricExporter {
     this.stopServer(cb);
   }
 
+  /**
+   * Set the pulling callback will be called on request of metrics.
+   *
+   * @param cb The callback
+   */
+  setPullCallback(cb?: () => void) {
+    this._pullCallback = cb;
+  }
+
   /**
    * Updates the value of a single metric in the registry
    *
@@ -295,6 +305,7 @@ export class PrometheusExporter implements MetricExporter {
     response: ServerResponse
   ) => {
     if (url.parse(request.url!).pathname === this._endpoint) {
+      this._pullCallback?.();
       this._exportMetrics(response);
     } else {
       this._notFound(response);

packages/opentelemetry-exporter-prometheus/test/export/export-pipeline.test.ts

@@ -0,0 +1,63 @@
+/*!
+ * Copyright 2020, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as api from '@opentelemetry/api';
+import * as assert from 'assert';
+import { installExportPipeline, PrometheusExporter } from '../../src';
+import { get } from '../request-util';
+import { mockedTimeMS } from '../sandbox';
+import { PullController } from '@opentelemetry/metrics';
+
+describe('Prometheus Export Pipeline', () => {
+  let exporter: PrometheusExporter;
+
+  afterEach(done => {
+    exporter?.shutdown(done);
+  });
+
+  it('should install to global metrics api', async () => {
+    let controller: PullController;
+    await new Promise(resolve => {
+      ({ exporter, controller } = installExportPipeline(
+        { startServer: true },
+        resolve
+      ));
+    });
+
+    assert.strictEqual(api.metrics.getMeterProvider(), controller!);
+
+    const counter = api.metrics.getMeter('test').createCounter('counter', {
+      description: 'a test description',
+      labelKeys: ['key1'],
+    });
+    const boundCounter = counter.bind({ key1: 'labelValue1' });
+    boundCounter.add(10);
+
+    const res = await get('http://localhost:9464/metrics');
+    assert.strictEqual(res.statusCode, 200);
+    assert(res.body != null);
+    const lines = res.body!.split('\n');
+
+    assert.strictEqual(lines[0], '# HELP counter a test description');
+
+    assert.deepStrictEqual(lines, [
+      '# HELP counter a test description',
+      '# TYPE counter counter',
+      `counter{key1="labelValue1"} 10 ${mockedTimeMS}`,
+      '',
+    ]);
+  });
+});

packages/opentelemetry-exporter-prometheus/test/prometheus.test.ts

@@ -14,35 +14,19 @@
  * limitations under the License.
  */
 
-import { HrTime, ObserverResult } from '@opentelemetry/api';
+import { ObserverResult } from '@opentelemetry/api';
 import {
   CounterMetric,
-  CounterSumAggregator,
   Meter,
-  MeterProvider,
+  PushController,
   ObserverMetric,
-  Point,
 } from '@opentelemetry/metrics';
 import * as assert from 'assert';
 import * as http from 'http';
 import { PrometheusExporter } from '../src';
-
-const mockedHrTime: HrTime = [1586347902211, 0];
-const mockedTimeMS = 1586347902211000;
+import { mockedTimeMS } from './sandbox';
 
 describe('PrometheusExporter', () => {
-  let toPoint: () => Point;
-  before(() => {
-    toPoint = CounterSumAggregator.prototype.toPoint;
-    CounterSumAggregator.prototype.toPoint = function (): Point {
-      const point = toPoint.apply(this);
-      point.timestamp = mockedHrTime;
-      return point;
-    };
-  });
-  after(() => {
-    CounterSumAggregator.prototype.toPoint = toPoint;
-  });
   describe('constructor', () => {
     it('should construct an exporter', () => {
       const exporter = new PrometheusExporter();
@@ -189,7 +173,7 @@ describe('PrometheusExporter', () => {
 
     beforeEach(done => {
       exporter = new PrometheusExporter();
-      meter = new MeterProvider().getMeter('test-prometheus');
+      meter = new PushController().getMeter('test-prometheus');
       exporter.startServer(done);
     });
 
@@ -418,7 +402,7 @@ describe('PrometheusExporter', () => {
     let exporter: PrometheusExporter | undefined;
 
     beforeEach(() => {
-      meter = new MeterProvider().getMeter('test-prometheus');
+      meter = new PushController().getMeter('test-prometheus');
       counter = meter.createCounter('counter') as CounterMetric;
       counter.bind({ key1: 'labelValue1' }).add(10);
     });

packages/opentelemetry-exporter-prometheus/test/request-util.ts

@@ -0,0 +1,42 @@
+/*!
+ * Copyright 2020, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as http from 'http';
+
+export interface TestMessage {
+  statusCode?: number;
+  body?: string;
+}
+
+export function get(url: string): Promise<TestMessage> {
+  return new Promise((resolve, reject) => {
+    http
+      .get(url, (res: http.IncomingMessage) => {
+        res.on('error', reject);
+
+        res.setEncoding('utf8');
+
+        let body = '';
+        res.on('data', data => {
+          body += data;
+        });
+        res.on('end', () => {
+          resolve({ statusCode: res.statusCode, body });
+        });
+      })
+      .on('error', reject);
+  });
+}

packages/opentelemetry-exporter-prometheus/test/sandbox.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2020, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Point, CounterSumAggregator } from '@opentelemetry/metrics';
+import { HrTime } from '@opentelemetry/api';
+
+export const mockedHrTime: HrTime = [1586347902211, 0];
+export const mockedTimeMS = 1586347902211000;
+
+let toPoint: () => Point;
+before(() => {
+  toPoint = CounterSumAggregator.prototype.toPoint;
+  CounterSumAggregator.prototype.toPoint = function (): Point {
+    const point = toPoint.apply(this);
+    point.timestamp = mockedHrTime;
+    return point;
+  };
+});
+after(() => {
+  CounterSumAggregator.prototype.toPoint = toPoint;
+});