Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Api separation #727

Merged
Merged
Show file tree
Hide file tree
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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: |
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,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

Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion doc/development-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
123 changes: 123 additions & 0 deletions packages/opentelemetry-api/README.md
Original file line number Diff line number Diff line change
@@ -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/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://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
24 changes: 24 additions & 0 deletions packages/opentelemetry-api/karma.conf.js
Original file line number Diff line number Diff line change
@@ -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
}))
};
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
{
"name": "@opentelemetry/types",
"name": "@opentelemetry/api",
dyladan marked this conversation as resolved.
Show resolved Hide resolved
"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"
},
Expand Down Expand Up @@ -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"
}
}
61 changes: 61 additions & 0 deletions packages/opentelemetry-api/src/api/metrics.ts
Original file line number Diff line number Diff line change
@@ -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);
}
}
Loading