Api separation #727
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 and enums. 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 DK implementations and acquire resources from the API. | ||
dyladan marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| - [Trace API Documentation][trace-api-docs] | ||
| - [Metrics API Documentation][metrics-api-docs] | ||
|
|
||
| ```javascript | ||
| const api = require("@opentelemetry/api") | ||
|
|
||
| /* returns traceRegistry */ | ||
dyladan marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| 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); | ||
|
|
||
| /* returns meterRegistry */ | ||
dyladan marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| 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-types | ||
dyladan marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| [dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-types | ||
| [devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/dev-status.svg?path=packages/opentelemetry-types | ||
| [devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-types&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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| })) | ||
| }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| /*! | ||
| * 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; | ||
|
|
||
| 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); | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| /*! | ||
| * 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 { NOOP_TRACER_REGISTRY } from '../trace/NoopTracerRegistry'; | ||
| import { TracerRegistry } from '../trace/tracer_registry'; | ||
| import { Tracer } from '../trace/tracer'; | ||
|
|
||
| /** | ||
dyladan marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| * Singleton object which represents the entry point to the OpenTelemetry Tracing API | ||
| */ | ||
| export class TraceAPI { | ||
| private static _instance?: TraceAPI; | ||
| private _tracerRegistry: TracerRegistry = NOOP_TRACER_REGISTRY; | ||
|
|
||
| private constructor() {} | ||
dyladan marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| /** Get the singleton instance of the Trace API */ | ||
| public static getInstance(): TraceAPI { | ||
dyladan marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| if (!this._instance) { | ||
| this._instance = new TraceAPI(); | ||
| } | ||
|
|
||
| return this._instance; | ||
| } | ||
|
|
||
| /** | ||
| * Set the current global tracer. Returns the initialized global tracer registry | ||
|
Member
There was a problem hiding this comment. if this function only sets registry, it should have different name then
Member
Author
There was a problem hiding this comment. This was brought over from the old |
||
| */ | ||
| public initGlobalTracerRegistry(registry: TracerRegistry): TracerRegistry { | ||
| this._tracerRegistry = registry; | ||
| return registry; | ||
| } | ||
|
|
||
| /** | ||
| * Returns the global tracer registry. | ||
| */ | ||
| public getTracerRegistry(): TracerRegistry { | ||
| return this._tracerRegistry; | ||
| } | ||
|
|
||
| /** | ||
| * Returns a tracer from the global tracer registry. | ||
| */ | ||
| public getTracer(name: string, version?: string): Tracer { | ||
| return this.getTracerRegistry().getTracer(name, version); | ||
| } | ||
| } | ||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.