Skip to content

Commit

Permalink
Api separation (open-telemetry#727)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
dyladan committed Feb 18, 2021
1 parent 5c45894 commit 5d2b028
Show file tree
Hide file tree
Showing 47 changed files with 2,801 additions and 1 deletion.
124 changes: 123 additions & 1 deletion api/README.md
Original file line number Diff line number Diff line change
@@ -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
72 changes: 72 additions & 0 deletions api/package.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
Loading

0 comments on commit 5d2b028

Please sign in to comment.