Api separation

.circleci/config.yml

@@ -45,7 +45,7 @@ cache_1: &cache_1
     - ./yarn.lock
     - packages/opentelemetry-base/node_modules
     - packages/opentelemetry-scope-base/node_modules
-    - packages/opentelemetry-types/node_modules
+    - packages/opentelemetry-api/node_modules
     - packages/opentelemetry-scope-async-hooks/node_modules
     - packages/opentelemetry-core/node_modules
     - packages/opentelemetry-exporter-prometheus/node_modules
@@ -169,7 +169,7 @@ jobs:
           name: Docs tests
           command: yarn docs-test
       - persist_to_workspace:
-          root: packages/opentelemetry-types/docs
+          root: packages/opentelemetry-api/docs
           paths:
             - out
   docs-deploy:
@@ -178,7 +178,7 @@ jobs:
     steps:
       - checkout
       - attach_workspace:
-          at: packages/opentelemetry-types/docs
+          at: packages/opentelemetry-api/docs
       - run:
           name: Install and configure dependencies
           command: |
@@ -190,7 +190,7 @@ jobs:
             - "1d:a3:60:b5:b4:8d:e7:8a:96:ce:6a:0a:e9:58:4c:54"
       - run:
           name: Deploy docs to gh-pages branch
-          command: gh-pages --dist packages/opentelemetry-types/docs/out
+          command: gh-pages --dist packages/opentelemetry-api/docs/out
   node8:
     docker:
       - image: node:8

CONTRIBUTING.md

@@ -65,7 +65,7 @@ The `opentelemetry-js` project is written in TypeScript.
 
 
 ### Generating API documentation
-- `yarn docs` or `npm run docs` to generate API documentation. Generates the documentation in `packages/opentelemetry-types/docs/out`
+- `yarn docs` or `npm run docs` to generate API documentation. Generates the documentation in `packages/opentelemetry-api/docs/out`
 
 ### Generating CHANGELOG documentation
 - `yarn changelog` or `npm run changelog` to generate CHANGELOG documentation in your terminal (see [RELEASING.md](RELEASING.md) for more details).

README.md

@@ -98,8 +98,8 @@ Maintainers ([@open-telemetry/js-maintainers](https://github.com/orgs/open-telem
 
 | Package                 | Description |
 | ----------------------- | -----------------|
-| [@opentelemetry/types][otel-types] | This package provides TypeScript interfaces and enums for the OpenTelemetry core trace and metrics model. It is intended for use both on the server and in the browser. |
-| [@opentelemetry/core][otel-core] | This package provides default and no-op implementations of the OpenTelemetry types for trace and metrics. It's intended for use both on the server and in the browser. |
+| [@opentelemetry/api][otel-api] | This package provides TypeScript interfaces and enums for the OpenTelemetry core trace and metrics model. It is intended for use both on the server and in the browser. |
+| [@opentelemetry/core][otel-core] | This package provides default and no-op implementations of the OpenTelemetry api for trace and metrics. It's intended for use both on the server and in the browser. |
 
 ### Implementation / SDKs
 
@@ -197,5 +197,5 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [otel-shim-opentracing]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-shim-opentracing
 [otel-tracing]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing
 [otel-web]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web
-[otel-types]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-types
+[otel-api]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-api
 [otel-core]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-core

doc/development-guide.md

@@ -77,4 +77,4 @@ To generate the docs, use:
 $ yarn docs
 ```
 
-The document will be available under `packages/opentelemetry-types/docs/out` path.
+The document will be available under `packages/opentelemetry-api/docs/out` path.

package.json

@@ -23,7 +23,7 @@
     "predocs-test": "yarn docs",
     "docs-test": "lerna run docs-test",
     "docs": "lerna run docs",
-    "docs-deploy": "gh-pages --dist packages/opentelemetry-types/docs/out"
+    "docs-deploy": "gh-pages --dist packages/opentelemetry-api/docs/out"
   },
   "repository": "open-telemetry/opentelemetry-js",
   "keywords": [

packages/opentelemetry-api/README.md

@@ -0,0 +1,123 @@
+# OpenTelemetry API for JavaScript
+[![Gitter chat][gitter-image]][gitter-url]
+[![NPM Published Version][npm-img]][npm-url]
+[![dependencies][dependencies-image]][dependencies-url]
+[![devDependencies][devDependencies-image]][devDependencies-url]
+[![Apache License][license-image]][license-image]
+
+This package provides everything needed to interact with the OpenTelemetry API, including all TypeScript interfaces, enums, and no-op implementations. It is intended for use both on the server and in the browser.
+
+## Basic Use
+
+### API Entry Point
+
+API entry points are defined as global singleton objects `trace` and `metrics` which contain methods used to initialize SDK implementations and acquire resources from the API.
+
+- [Trace API Documentation][trace-api-docs]
+- [Metrics API Documentation][metrics-api-docs]
+
+```javascript
+const api = require("@opentelemetry/api")
+
+/* Initialize TraceRegistry */
+api.trace.initGlobalTracerRegistry(traceRegistry);
+/* returns traceRegistry (no-op if a working registry has not been initialized) */
+api.trace.getTracerRegistry();
+/* returns a tracer from the registered global tracer registry (no-op if a working registry has not been initialized); */
+api.trace.getTracer(name, version);
+
+/* Initialize MeterRegistry */
+api.metrics.initGlobalMeterRegistry(meterRegistry);
+/* returns meterRegistry (no-op if a working registry has not been initialized) */
+api.metrics.getMeterRegistry();
+/* returns a meter from the registered global meter registry (no-op if a working registry has not been initialized); */
+api.metrics.getMeter(name, version);
+```
+
+### Application Owners
+
+Application owners will also need a working OpenTelemetry SDK implementation. OpenTelemetry provides working SDK implementations for [web] and [node] for both [tracing] and [metrics].
+
+#### Simple NodeJS Example
+
+Before any other module in your application is loaded, you must initialize the global tracer and meter registries. If you fail to initialize a registry, no-op implementations will be provided to any library which acquires them from the API.
+
+```javascript
+const api = require("@opentelemetry/api");
+const sdk = require("@opentelemetry/node");
+
+const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+
+// Initialize an exporter
+const exporter = new JaegerExporter({
+  serviceName: 'basic-service'
+});
+
+// Create a registry which we will configure as the global tracer registry
+const registry = new sdk.NodeTracerRegistry();
+
+// Configure span processor to send spans to the exporter
+registry.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+// Initialize the OpenTelemetry APIs to use the NodeTracerRegistry bindings
+api.trace.initGlobalTracerRegistry(registry);
+
+// your application code below this line
+```
+
+### Library Authors
+
+Library authors need only to depend on the `@opentelemetry/api` package and trust that the application owners which use their library will initialize an appropriate SDK.
+
+```javascript
+const api = require("@opentelemetry/api");
+
+const tracer = api.trace.getTracer("my-library-name", "0.2.3");
+
+async function doSomething() {
+  const span = tracer.startSpan("doSomething", { parent: tracer.getCurrentSpan() });
+  try {
+    const result = await doSomethingElse();
+    span.end();
+    return result;
+  } catch (err) {
+    span.setStatus({
+      // use an appropriate status code here
+      code: api.CanonicalCode.INTERNAL,
+      message: err.message,
+    });
+    span.end();
+    return null;
+  }
+}
+```
+
+
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
+- For help or feedback on this project, join us on [gitter][gitter-url]
+
+## License
+
+Apache 2.0 - See [LICENSE][license-url] for more information.
+
+[gitter-image]: https://badges.gitter.im/open-telemetry/opentelemetry-js.svg
+[gitter-url]: https://gitter.im/open-telemetry/opentelemetry-node?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/master/LICENSE
+[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
+[dependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/status.svg?path=packages/opentelemetry-api
+[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-api
+[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/dev-status.svg?path=packages/opentelemetry-api
+[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-api&type=dev
+[npm-url]: https://www.npmjs.com/package/@opentelemetry/types
+[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Ftypes.svg
+
+[trace-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/traceapi.html
+[metrics-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/metricsapi.html
+
+[web]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web
+[tracing]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing
+[node]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-node
+[metrics]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-metrics

packages/opentelemetry-api/karma.conf.js

@@ -0,0 +1,24 @@
+/*!
+ * Copyright 2019, 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
+ *
+ *      http://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.
+ */
+
+const karmaWebpackConfig = require('../../karma.webpack');
+const karmaBaseConfig = require('../../karma.base');
+
+module.exports = (config) => {
+  config.set(Object.assign({}, karmaBaseConfig, {
+    webpack: karmaWebpackConfig
+  }))
+};

packages/opentelemetry-types/package.json → packages/opentelemetry-api/package.json

@@ -1,18 +1,22 @@
 {
-  "name": "@opentelemetry/types",
+  "name": "@opentelemetry/api",
   "version": "0.3.3",
-  "description": "TypeScript types for OpenTelemetry",
+  "description": "Public API for OpenTelemetry",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "repository": "open-telemetry/opentelemetry-js",
   "scripts": {
+    "test": "nyc ts-mocha -p tsconfig.json test/**/*.ts",
+    "test:browser": "nyc karma start --single-run",
+    "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
+    "codecov:browser": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "build": "npm run compile",
     "check": "gts check",
     "precompile": "tsc --version",
     "version:update": "node ../../scripts/version-update.js",
     "compile": "npm run version:update && tsc -p .",
     "fix": "gts fix",
-    "docs-test": "linkinator docs/out --skip david-dm.org",
+    "docs-test": "linkinator docs/out --silent --skip david-dm.org --skip https://open-telemetry.github.io/opentelemetry-js/classes/.+api.html",
     "docs": "typedoc --tsconfig tsconfig.json",
     "prepare": "npm run compile"
   },
@@ -42,11 +46,27 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/mocha": "^5.2.7",
+    "@types/node": "^12.6.8",
+    "@types/webpack-env": "1.13.9",
+    "codecov": "^3.6.1",
     "gts": "^1.1.0",
+    "istanbul-instrumenter-loader": "^3.0.1",
+    "karma-chrome-launcher": "^3.1.0",
+    "karma-coverage-istanbul-reporter": "^2.1.0",
+    "karma-mocha": "^1.3.0",
+    "karma-spec-reporter": "^0.0.32",
+    "karma-webpack": "^4.0.2",
+    "karma": "^4.4.1",
     "linkinator": "^1.5.0",
+    "mocha": "^6.1.0",
+    "nyc": "^14.1.1",
+    "ts-loader": "^6.0.4",
+    "ts-mocha": "^6.0.0",
     "tslint-consistent-codestyle": "^1.15.1",
     "tslint-microsoft-contrib": "^6.2.0",
     "typedoc": "^0.15.0",
-    "typescript": "3.7.2"
+    "typescript": "3.7.2",
+    "webpack": "^4.35.2"
   }
 }

packages/opentelemetry-api/src/api/metrics.ts

@@ -0,0 +1,61 @@
+/*!
+ * 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 { Meter } from '../metrics/Meter';
+import { MeterRegistry } from '../metrics/MeterRegistry';
+import { NOOP_METER_REGISTRY } from '../metrics/NoopMeterRegistry';
+
+/**
+ * Singleton object which represents the entry point to the OpenTelemetry Metrics API
+ */
+export class MetricsAPI {
+  private static _instance?: MetricsAPI;
+  private _meterRegistry: MeterRegistry = NOOP_METER_REGISTRY;
+
+  /** Empty private constructor prevents end users from constructing a new instance of the API */
+  private constructor() {}
+
+  /** Get the singleton instance of the Metrics API */
+  public static getInstance(): MetricsAPI {
+    if (!this._instance) {
+      this._instance = new MetricsAPI();
+    }
+
+    return this._instance;
+  }
+
+  /**
+   * Set the current global meter. Returns the initialized global meter registry.
+   */
+  public initGlobalMeterRegistry(registry: MeterRegistry): MeterRegistry {
+    this._meterRegistry = registry;
+    return registry;
+  }
+
+  /**
+   * Returns the global meter registry.
+   */
+  public getMeterRegistry(): MeterRegistry {
+    return this._meterRegistry;
+  }
+
+  /**
+   * Returns a meter from the global meter registry.
+   */
+  public getMeter(name: string, version?: string): Meter {
+    return this.getMeterRegistry().getMeter(name, version);
+  }
+}