UNPKG

7.13 kBMarkdownView Raw
1
2---
3<p align="center">
4 <strong>
5 <a href="https://open-telemetry.github.io/opentelemetry-js-api">API Documentation<a/>
6 &nbsp;&nbsp;&bull;&nbsp;&nbsp;
7 <a href="https://github.com/open-telemetry/opentelemetry-js/discussions">Getting In Touch (GitHub Discussions)<a/>
8 </strong>
9</p>
10
11<p align="center">
12 <a href="https://github.com/open-telemetry/opentelemetry-js-api/releases">
13 <img alt="GitHub release (latest by date including pre-releases)" src="https://img.shields.io/github/v/release/open-telemetry/opentelemetry-js-api?include_prereleases&style=for-the-badge">
14 </a>
15 <a href="https://codecov.io/gh/open-telemetry/opentelemetry-js-api/branch/main/">
16 <img alt="Codecov Status" src="https://img.shields.io/codecov/c/github/open-telemetry/opentelemetry-js-api?style=for-the-badge">
17 </a>
18 <a href="https://github.com/open-telemetry/opentelemetry-js-api/blob/main/LICENSE">
19 <img alt="license" src="https://img.shields.io/badge/license-Apache_2.0-green.svg?style=for-the-badge">
20 </a>
21 <br/>
22 <a href="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/docs.yaml">
23 <img alt="Build Status" src="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/test.yaml/badge.svg?branch=main">
24 </a>
25 <a href="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/test.yaml?query=branch%3Amain">
26 <img alt="Build Status" src="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/docs.yaml/badge.svg">
27 </a>
28</p>
29
30---
31
32# OpenTelemetry API for JavaScript
33
34[![NPM Published Version][npm-img]][npm-url]
35
36This 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.
37
38The methods in this package perform no operations by default. This means they can be safely called by a library or end-user application whether there is an SDK registered or not. In order to generate and export telemetry data, you will also need an SDK such as the [OpenTelemetry JS SDK][opentelemetry-js].
39
40## Tracing Quick Start
41
42### You Will Need
43
44- An application you wish to instrument
45- [OpenTelemetry JS SDK][opentelemetry-js]
46- Node.js >=8.5.0 (14+ is preferred) or an ECMAScript 5+ compatible browser
47
48**Note:** ECMAScript 5+ compatibility is for this package only. Please refer to the documentation for the SDK you are using to determine its minimum ECMAScript version.
49
50**Note for library authors:** Only your end users will need an OpenTelemetry SDK. If you wish to support OpenTelemetry in your library, you only need to use the OpenTelemetry API. For more information, please read the [tracing documentation][docs-tracing].
51
52### Install Dependencies
53
54```sh
55npm install @opentelemetry/api @opentelemetry/sdk-trace-base
56```
57
58### Trace Your Application
59
60In order to get started with tracing, you will need to first register an SDK. The SDK you are using may provide a convenience method which calls the registration methods for you, but if you would like to call them directly they are documented here: [sdk registration methods][docs-sdk-registration].
61
62Once you have registered an SDK, you can start and end spans. A simple example of basic SDK registration and tracing a simple operation is below. The example should export spans to the console once per second. For more information, see the [tracing documentation][docs-tracing].
63
64```javascript
65const { trace } = require("@opentelemetry/api");
66const { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
67
68// Create and register an SDK
69const provider = new BasicTracerProvider();
70provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
71trace.setGlobalTracerProvider(provider);
72
73// Acquire a tracer from the global tracer provider which will be used to trace the application
74const name = 'my-application-name';
75const version = '0.1.0';
76const tracer = trace.getTracer(name, version);
77
78// Trace your application by creating spans
79async function operation() {
80 const span = tracer.startSpan("do operation");
81
82 // mock some work by sleeping 1 second
83 await new Promise((resolve, reject) => {
84 setTimeout(resolve, 1000);
85 })
86
87 span.end();
88}
89
90async function main() {
91 while (true) {
92 await operation();
93 }
94}
95
96main();
97```
98
99## Version Compatibility
100
101Because the npm installer and node module resolution algorithm could potentially allow two or more copies of any given package to exist within the same `node_modules` structure, the OpenTelemetry API takes advantage of a variable on the `global` object to store the global API. When an API method in the API package is called, it checks if this `global` API exists and proxies calls to it if and only if it is a compatible API version. This means if a package has a dependency on an OpenTelemetry API version which is not compatible with the API used by the end user, the package will receive a no-op implementation of the API.
102
103## Upgrade Guidelines
104
105### 0.21.0 to 1.0.0
106
107No breaking changes
108
109### 0.20.0 to 0.21.0
110
111- [#78](https://github.com/open-telemetry/opentelemetry-js-api/issues/78) `api.context.bind` arguments reversed and `context` is now a required argument.
112- [#46](https://github.com/open-telemetry/opentelemetry-js-api/issues/46) Noop classes and singletons are no longer exported. To create a noop span it is recommended to use `api.trace.wrapSpanContext` with `INVALID_SPAN_CONTEXT` instead of using the `NOOP_TRACER`.
113
114### 1.0.0-rc.3 to 0.20.0
115
116- Removing `TimedEvent` which was not part of spec
117- `HttpBaggage` renamed to `HttpBaggagePropagator`
118- [#45](https://github.com/open-telemetry/opentelemetry-js-api/pull/45) `Span#context` renamed to `Span#spanContext`
119- [#47](https://github.com/open-telemetry/opentelemetry-js-api/pull/47) `getSpan`/`setSpan`/`getSpanContext`/`setSpanContext` moved to `trace` namespace
120- [#55](https://github.com/open-telemetry/opentelemetry-js-api/pull/55) `getBaggage`/`setBaggage`/`createBaggage` moved to `propagation` namespace
121
122## Useful links
123
124- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
125- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
126- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
127
128## License
129
130Apache 2.0 - See [LICENSE][license-url] for more information.
131
132[opentelemetry-js]: https://github.com/open-telemetry/opentelemetry-js
133
134[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
135[license-url]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/LICENSE
136[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
137[npm-url]: https://www.npmjs.com/package/@opentelemetry/api
138[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fapi.svg
139[docs-tracing]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/tracing.md
140[docs-sdk-registration]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/sdk-registration.md