Merge branch 'master' into add-express-plugin

.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
@@ -170,7 +170,7 @@ jobs:
           name: Docs tests
           command: yarn docs-test
       - persist_to_workspace:
-          root: packages/opentelemetry-types/docs
+          root: packages/opentelemetry-api/docs
           paths:
             - out
       - run:
@@ -185,7 +185,7 @@ jobs:
     steps:
       - checkout
       - attach_workspace:
-          at: packages/opentelemetry-types/docs
+          at: packages/opentelemetry-api/docs
       - run:
           name: Install and configure dependencies
           command: |
@@ -197,7 +197,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

@@ -96,8 +96,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.

examples/ioredis/README.md

@@ -0,0 +1,39 @@
+# Overview
+
+OpenTelemetry IORedis Instrumentation allows the user to automatically collect trace data and export them to the backend(s) of choice (Jaeger in this example).
+
+## Tracing backend setup
+
+### Jaeger
+
+- Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Installation
+
+```sh
+npm install
+```
+
+## Run the Application
+
+- Start redis via docker
+
+   ```sh
+   npm run docker:start
+   ```
+
+- Run the main program
+
+   ```sh
+   npm run start
+   ```
+
+- Cleanup docker
+
+   ```sh
+   npm run docker:stop
+   ```
+
+## LICENSE
+
+Apache License 2.0

examples/ioredis/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// Require tracer before any other modules
+require('./tracer');
+const Redis = require('ioredis');
+
+const redis = new Redis();
+
+async function main() {
+  try {
+    await redis.set('test', 'data');
+    process.exit(0);
+  } catch (error) {
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+main();

examples/ioredis/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ioredis-example",
+  "private": true,
+  "version": "0.3.3",
+  "description": "Example of HTTP integration with OpenTelemetry",
+  "main": "index.js",
+  "scripts": {
+    "docker:start": "docker run -d -p 6379:6379 --name otjsredis redis:alpine",
+    "docker:stop": "docker stop otjsredis && docker rm otjsredis",
+    "start": "node index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "redis",
+    "ioredis",
+    "tracing"
+  ],
+  "engines": {
+    "node": ">=8"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js/issues"
+  },
+  "dependencies": {
+    "@opentelemetry/core": "^0.3.3",
+    "@opentelemetry/exporter-jaeger": "^0.3.3",
+    "@opentelemetry/node": "^0.3.3",
+    "@opentelemetry/plugin-ioredis": "^0.3.3",
+    "@opentelemetry/tracing": "^0.3.3",
+    "ioredis": "^4.14.1"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {}
+}

examples/ioredis/tracer.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/core');
+const { NodeTracerRegistry } = require('@opentelemetry/node');
+const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+
+const tracerRegistry = new NodeTracerRegistry();
+
+const exporter = new JaegerExporter({ serviceName: 'ioredis-example' });
+
+tracerRegistry.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+// Initialize the OpenTelemetry APIs to use the BasicTracer bindings
+opentelemetry.initGlobalTracerRegistry(tracerRegistry);
+
+module.exports = opentelemetry.getTracer();

examples/postgres/package.json

@@ -39,11 +39,11 @@
     "@opentelemetry/plugin-pg-pool": "^0.3.3",
     "@opentelemetry/tracing": "^0.3.3",
     "@opentelemetry/types": "^0.3.3",
-    "express": "^4.17.1"
+    "express": "^4.17.1",
+    "pg": "^7.12.1"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
   "devDependencies": {
-    "cross-env": "^6.0.0",
-    "pg": "^7.12.1"
+    "cross-env": "^6.0.0"
   }
 }

examples/stackdriver-trace/index.js

@@ -1,27 +1,27 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/core');
-const { BasicTracer, SimpleSpanProcessor } = require('@opentelemetry/tracing');
+const { BasicTracerRegistry, SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { CanonicalCode } = require('@opentelemetry/types');
 const { StackdriverTraceExporter } = require('@opentelemetry/exporter-stackdriver-trace');
 
 // Initialize an exporter
 const exporter = new StackdriverTraceExporter({
-  serviceName: 'basic-service',
-  logger: new opentelemetry.ConsoleLogger(),
+  projectId: '<PROJECT_ID>',
 });
 
-const tracer = new BasicTracer();
+const registry = new BasicTracerRegistry();
 
 // Configure span processor to send spans to the provided exporter
-tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
+registry.addSpanProcessor(new SimpleSpanProcessor(exporter));
 
-// Initialize the OpenTelemetry APIs to use the BasicTracer bindings
-opentelemetry.initGlobalTracer(tracer);
+// Initialize the OpenTelemetry APIs to use the BasicTracerRegistry bindings
+opentelemetry.initGlobalTracerRegistry(registry);
+const tracer = opentelemetry.getTracer('stackdriver-basic');
 
 // Create a span. A span must be closed.
-const root = opentelemetry.getTracer().startSpan('main');
-const related = opentelemetry.getTracer().startSpan('related', {
+const root = tracer.startSpan('main');
+const related = tracer.startSpan('related', {
   links: [{ spanContext: root.context() }],
 });
 
@@ -42,9 +42,7 @@ exporter.shutdown();
 function doWork(parent) {
   // Start another span. In this example, the main method already started a
   // span, so that'll be the parent span, and this will be a child span.
-  const span = opentelemetry.getTracer().startSpan('doWork', {
-    parent,
-  });
+  const span = tracer.startSpan('doWork', { parent });
 
   // simulate some random work.
   const work = Math.floor(Math.random() * 40000000);

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",
     "lint-examples": "eslint ./examples/**/*.js",
     "fix-examples": "eslint ./examples/**/*.js --fix"
   },

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/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