@opentelemetry/api 0.18.1 → 1.0.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +56 -132
- package/build/src/version.d.ts +1 -1
- package/build/src/version.js +1 -1
- package/build/src/version.js.map +1 -1
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 1.0.0-rc.0
|
|
6
|
+
|
|
7
|
+
### :memo: Documentation
|
|
8
|
+
|
|
9
|
+
* [#20](https://github.com/open-telemetry/opentelemetry-js-api/pull/20) docs: document latest manual tracing ([@dyladan](https://github.com/dyladan))
|
|
10
|
+
* [#18](https://github.com/open-telemetry/opentelemetry-js-api/pull/18) chore: deploy docs on a release ([@dyladan](https://github.com/dyladan))
|
|
11
|
+
* [#19](https://github.com/open-telemetry/opentelemetry-js-api/pull/19) docs: fix readme links ([@dyladan](https://github.com/dyladan))
|
|
12
|
+
|
|
13
|
+
### Committers: 1
|
|
14
|
+
|
|
15
|
+
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
|
|
16
|
+
|
|
5
17
|
## 0.18.1
|
|
6
18
|
|
|
7
19
|
### :bug: Bug Fix
|
package/README.md
CHANGED
|
@@ -7,140 +7,71 @@
|
|
|
7
7
|
|
|
8
8
|
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.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
The 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].
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## Tracing Quick Start
|
|
13
13
|
|
|
14
|
-
###
|
|
15
|
-
|
|
16
|
-
```sh
|
|
17
|
-
$ # Install tracing dependencies
|
|
18
|
-
$ npm install \
|
|
19
|
-
@opentelemetry/api \
|
|
20
|
-
@opentelemetry/core \
|
|
21
|
-
@opentelemetry/node \
|
|
22
|
-
@opentelemetry/tracing \
|
|
23
|
-
@opentelemetry/exporter-jaeger \ # add exporters as needed
|
|
24
|
-
@opentelemetry/plugin-http # add plugins as needed
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
> Note: this example is for node.js. See [examples/tracer-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/tracer-web) for a browser example.
|
|
28
|
-
|
|
29
|
-
### Initialize the SDK
|
|
30
|
-
|
|
31
|
-
Before any other module in your application is loaded, you must initialize the global tracer and meter providers. If you fail to initialize a provider, no-op implementations will be provided to any library which acquires them from the API.
|
|
32
|
-
|
|
33
|
-
To collect traces and metrics, you will have to tell the SDK where to export telemetry data to. This example uses Jaeger and Prometheus, but exporters exist for [other tracing backends][other-tracing-backends]. If you're not sure if there is an exporter for your tracing backend, contact your tracing provider.
|
|
34
|
-
|
|
35
|
-
#### Tracing
|
|
36
|
-
|
|
37
|
-
```javascript
|
|
38
|
-
const { NodeTracerProvider } = require("@opentelemetry/node");
|
|
39
|
-
const { SimpleSpanProcessor } = require("@opentelemetry/tracing");
|
|
40
|
-
const { JaegerExporter } = require("@opentelemetry/exporter-jaeger");
|
|
41
|
-
|
|
42
|
-
const tracerProvider = new NodeTracerProvider();
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
* The SimpleSpanProcessor does no batching and exports spans
|
|
46
|
-
* immediately when they end. For most production use cases,
|
|
47
|
-
* OpenTelemetry recommends use of the BatchSpanProcessor.
|
|
48
|
-
*/
|
|
49
|
-
tracerProvider.addSpanProcessor(
|
|
50
|
-
new SimpleSpanProcessor(
|
|
51
|
-
new JaegerExporter({
|
|
52
|
-
serviceName: 'my-service'
|
|
53
|
-
})
|
|
54
|
-
)
|
|
55
|
-
);
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* Registering the provider with the API allows it to be discovered
|
|
59
|
-
* and used by instrumentation libraries. The OpenTelemetry API provides
|
|
60
|
-
* methods to set global SDK implementations, but the default SDK provides
|
|
61
|
-
* a convenience method named `register` which registers same defaults
|
|
62
|
-
* for you.
|
|
63
|
-
*
|
|
64
|
-
* By default the NodeTracerProvider uses Trace Context for propagation
|
|
65
|
-
* and AsyncHooksScopeManager for context management. To learn about
|
|
66
|
-
* customizing this behavior, see API Registration Options below.
|
|
67
|
-
*/
|
|
68
|
-
tracerProvider.register();
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## Version Compatibility
|
|
72
|
-
|
|
73
|
-
Because 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.
|
|
74
|
-
|
|
75
|
-
## Advanced Use
|
|
14
|
+
### You Will Need
|
|
76
15
|
|
|
77
|
-
|
|
16
|
+
- An application you wish to instrument
|
|
17
|
+
- [OpenTelemetry JS SDK][opentelemetry-js]
|
|
18
|
+
- Node.js >=8.5.0 (14+ is preferred) or an ECMAScript 5+ compatible browser
|
|
78
19
|
|
|
79
|
-
|
|
20
|
+
**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.
|
|
80
21
|
|
|
81
|
-
|
|
82
|
-
const { B3Propagator } = require("@opentelemetry/propagator-b3");
|
|
22
|
+
**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].
|
|
83
23
|
|
|
84
|
-
|
|
85
|
-
// Use B3 Propagation
|
|
86
|
-
propagator: new B3Propagator(),
|
|
24
|
+
### Install Dependencies
|
|
87
25
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
});
|
|
26
|
+
```sh
|
|
27
|
+
npm install @opentelemetry/api @opentelemetry/tracing
|
|
91
28
|
```
|
|
92
29
|
|
|
93
|
-
###
|
|
30
|
+
### Trace Your Application
|
|
94
31
|
|
|
95
|
-
|
|
32
|
+
In 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].
|
|
96
33
|
|
|
97
|
-
|
|
98
|
-
- [Propagation API Documentation][propagation-api-docs]
|
|
99
|
-
- [Context API Documentation][context-api-docs]
|
|
34
|
+
Once 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].
|
|
100
35
|
|
|
101
36
|
```javascript
|
|
102
|
-
const
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
37
|
+
const { trace } = require("@opentelemetry/api");
|
|
38
|
+
const { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } = require("@opentelemetry/tracing");
|
|
39
|
+
|
|
40
|
+
// Create and register an SDK
|
|
41
|
+
const provider = new BasicTracerProvider();
|
|
42
|
+
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
|
|
43
|
+
trace.setGlobalTracerProvider(provider);
|
|
44
|
+
|
|
45
|
+
// Acquire a tracer from the global tracer provider which will be used to trace the application
|
|
46
|
+
const name = 'my-application-name';
|
|
47
|
+
const version = '0.1.0';
|
|
48
|
+
const tracer = trace.getTracer(name, version);
|
|
49
|
+
|
|
50
|
+
// Trace your application by creating spans
|
|
51
|
+
async function operation() {
|
|
52
|
+
const span = tracer.startSpan("do operation");
|
|
53
|
+
|
|
54
|
+
// mock some work by sleeping 1 second
|
|
55
|
+
await new Promise((resolve, reject) => {
|
|
56
|
+
setTimeout(resolve, 1000);
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
span.end();
|
|
60
|
+
return output;
|
|
61
|
+
}
|
|
110
62
|
|
|
111
|
-
|
|
112
|
-
|
|
63
|
+
async function main() {
|
|
64
|
+
while (true) {
|
|
65
|
+
await operation();
|
|
66
|
+
}
|
|
67
|
+
}
|
|
113
68
|
|
|
114
|
-
|
|
115
|
-
api.context.setGlobalContextManager(asyncHooksContextManager);
|
|
69
|
+
main();
|
|
116
70
|
```
|
|
117
71
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
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.
|
|
72
|
+
## Version Compatibility
|
|
121
73
|
|
|
122
|
-
|
|
123
|
-
const api = require("@opentelemetry/api");
|
|
124
|
-
|
|
125
|
-
const tracer = api.trace.getTracer("my-library-name", "0.2.3");
|
|
126
|
-
|
|
127
|
-
async function doSomething() {
|
|
128
|
-
const span = tracer.startSpan("doSomething");
|
|
129
|
-
try {
|
|
130
|
-
const result = await doSomethingElse();
|
|
131
|
-
span.end();
|
|
132
|
-
return result;
|
|
133
|
-
} catch (err) {
|
|
134
|
-
span.setStatus({
|
|
135
|
-
// use an appropriate status code here
|
|
136
|
-
code: api.SpanStatusCode.ERROR,
|
|
137
|
-
message: err.message,
|
|
138
|
-
});
|
|
139
|
-
span.end();
|
|
140
|
-
return null;
|
|
141
|
-
}
|
|
142
|
-
}
|
|
143
|
-
```
|
|
74
|
+
Because 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.
|
|
144
75
|
|
|
145
76
|
## Useful links
|
|
146
77
|
|
|
@@ -152,24 +83,17 @@ async function doSomething() {
|
|
|
152
83
|
|
|
153
84
|
Apache 2.0 - See [LICENSE][license-url] for more information.
|
|
154
85
|
|
|
86
|
+
[opentelemetry-js]: https://github.com/open-telemetry/opentelemetry-js
|
|
87
|
+
|
|
155
88
|
[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
|
|
156
|
-
[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/main/LICENSE
|
|
89
|
+
[license-url]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/LICENSE
|
|
157
90
|
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
|
|
158
|
-
[dependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/status.svg
|
|
159
|
-
[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js
|
|
160
|
-
[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/dev-status.svg
|
|
161
|
-
[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js
|
|
91
|
+
[dependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js-api/status.svg
|
|
92
|
+
[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-api
|
|
93
|
+
[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js-api/dev-status.svg
|
|
94
|
+
[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-api?type=dev
|
|
162
95
|
[npm-url]: https://www.npmjs.com/package/@opentelemetry/api
|
|
163
96
|
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fapi.svg
|
|
164
97
|
|
|
165
|
-
[
|
|
166
|
-
[
|
|
167
|
-
[propagation-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/propagationapi.html
|
|
168
|
-
[context-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/contextapi.html
|
|
169
|
-
|
|
170
|
-
[web]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-web
|
|
171
|
-
[tracing]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-tracing
|
|
172
|
-
[node]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node
|
|
173
|
-
[metrics]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-metrics
|
|
174
|
-
|
|
175
|
-
[other-tracing-backends]: https://github.com/open-telemetry/opentelemetry-js#trace-exporters
|
|
98
|
+
[docs-tracing]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/tracing.md
|
|
99
|
+
[docs-sdk-registration]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/sdk-registration.md
|
package/build/src/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const VERSION = "0.
|
|
1
|
+
export declare const VERSION = "1.0.0-rc.0";
|
|
2
2
|
//# sourceMappingURL=version.d.ts.map
|
package/build/src/version.js
CHANGED
package/build/src/version.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,4DAA4D;AAC/C,QAAA,OAAO,GAAG,
|
|
1
|
+
{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,4DAA4D;AAC/C,QAAA,OAAO,GAAG,YAAY,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opentelemetry/api",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0-rc.0",
|
|
4
4
|
"description": "Public API for OpenTelemetry",
|
|
5
5
|
"main": "build/src/index.js",
|
|
6
6
|
"types": "build/src/index.d.ts",
|
|
@@ -15,8 +15,9 @@
|
|
|
15
15
|
"codecov:browser": "nyc report --reporter=json && codecov -f coverage/*.json -p .",
|
|
16
16
|
"codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p .",
|
|
17
17
|
"compile": "tsc --build",
|
|
18
|
-
"docs-test": "linkinator docs/out --silent --skip david-dm.org",
|
|
19
18
|
"docs": "typedoc",
|
|
19
|
+
"docs:deploy": "gh-pages --dist docs/out",
|
|
20
|
+
"docs:test": "linkinator docs/out --silent --skip david-dm.org",
|
|
20
21
|
"lint:fix": "eslint src test --ext .ts --fix",
|
|
21
22
|
"lint": "eslint src test --ext .ts",
|
|
22
23
|
"test:browser": "nyc karma start --single-run",
|