Api separation (open-telemetry#727)

* feat: create an api package * chore: update circle for new api package * chore: bring back getTracer * chore: add wrongly removed dev dependency * chore: review comments * chore: review comments * chore: lint * chore: export all noop implementations * chore: update API README * chore: ignore known working links that are not yet published * chore: add jsdoc for getInstance calls * chore: add jsdoc for private constructors * chore: review comments * chore: fix readme npm url * chore: fix old readmes without registry * chore: update api calling convention
dyladan · Feb 18, 2021 · 5d2b028 · 5d2b028
1 parent 5c45894
commit 5d2b028
Show file tree

Hide file tree

Showing 47 changed files with 2,801 additions and 1 deletion.
diff --git a/api/README.md b/api/README.md
@@ -1 +1,123 @@
-# opentelemetry-js-api
+# 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/api
+[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
diff --git a/api/package.json b/api/package.json
@@ -0,0 +1,72 @@
+{
+ "name": "@opentelemetry/api",
+ "version": "0.3.3",
+ "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 --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"
+ },
+ "keywords": [
+ "opentelemetry",
+ "nodejs",
+ "browser",
+ "tracing",
+ "profiling",
+ "metrics",
+ "stats",
+ "monitoring"
+ ],
+ "author": "OpenTelemetry Authors",
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=8.0.0"
+ },
+ "files": [
+ "build/src/**/*.js",
+ "build/src/**/*.d.ts",
+ "doc",
+ "LICENSE",
+ "README.md"
+ ],
+ "publishConfig": {
+ "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",
+ "webpack": "^4.35.2"
+ }
+}