forked from open-telemetry/opentelemetry-js
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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
Showing
47 changed files
with
2,801 additions
and
1 deletion.
There are no files selected for viewing
This file contains 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 |
---|---|---|
@@ -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 |
This file contains 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,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" | ||
} | ||
} |
Oops, something went wrong.