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:/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:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-shim-opentracing
 [otel-tracing]: https:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing
 [otel-web]: https:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web
-[otel-types]: https:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-types
+[otel-api]: https:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-api
 [otel-core]: https:/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:/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:/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:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web
+[tracing]: https:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing
+[node]: https:/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-node
+[metrics]: https:/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);
+ }
+}