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://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/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://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
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"
+  }
+}