Skip to content

Commit fec5e31

Browse files
austinlparkerjohnbleydyladanvmarchaud
authored
Add opentelemetry.io docs (#2051)
Co-authored-by: John Bley <[email protected]> Co-authored-by: Daniel Dyla <[email protected]> Co-authored-by: Valentin Marchaud <[email protected]>
1 parent 897c35f commit fec5e31

File tree

6 files changed

+681
-0
lines changed

6 files changed

+681
-0
lines changed

‎website_docs/_index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: "Javascript"
3+
weight: 20
4+
description: >
5+
<img width="35" src="https://raw.github.com/open-telemetry/opentelemetry.io/main/iconography/32x32/JS_SDK.svg"></img>
6+
A language-specific implementation of OpenTelemetry in JavaScript (for Node.JS & the browser).
7+
---
8+
9+
This page contains an introduction to OpenTelemetry in JavaScript. This guide
10+
will walk you through installation and instrumentation and show you how to
11+
export data.
12+
13+
## Status and Releases
14+
15+
| Tracing | Metrics |
16+
| ------- | ------- |
17+
| Beta | Alpha |
18+
19+
You can find release information [here](https://github.com/open-telemetry/opentelemetry-js/releases)
20+
21+
## Further Reading
22+
23+
- [OpenTelemetry for JavaScript on GitHub](https://github.com/open-telemetry/opentelemetry-js)
24+
- [Getting Started](https://github.com/open-telemetry/opentelemetry-js/blob/main/getting-started/README.md)
25+
- [API Documentation](https://open-telemetry.github.io/opentelemetry-js)
26+
- [Getting In Touch (Gitter)](https://gitter.im/open-telemetry/opentelemetry-node)

‎website_docs/getting_started/_index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: "Getting Started"
3+
weight: 1
4+
---
5+
These two guides for Node.JS and the browser use simple examples in javascript to get you started with OpenTelemetry. Both will show you the following steps:
6+
7+
- Install the required OpenTelemetry libraries
8+
- Initialize a global [tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer)
9+
- Initialize and register a [span exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-exporter)

‎website_docs/getting_started/browser.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
title: "Browser"
3+
weight: 2
4+
---
5+
6+
This guide uses the example application in HTML & javascript provided below, but the steps to instrument your own application should be broadly the same. Here is an overview of what we will be doing.
7+
8+
- Install the required OpenTelemetry libraries
9+
- Initialize a global [tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer)
10+
- Initialize and register a [span exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-exporter)
11+
12+
This is a very simple guide, if you'd like to see more complex examples go to [examples/tracer-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/tracer-web)
13+
14+
Copy the following file into an empty directory and call it `index.html`.
15+
16+
```html
17+
<!DOCTYPE html>
18+
<html lang="en">
19+
<head>
20+
<meta charset="utf-8">
21+
<title>Document Load Plugin Example</title>
22+
<base href="/">
23+
<!--
24+
https://www.w3.org/TR/trace-context/
25+
Set the `traceparent` in the server's HTML template code. It should be
26+
dynamically generated server side to have the server's request trace Id,
27+
a parent span Id that was set on the server's request span, and the trace
28+
flags to indicate the server's sampling decision
29+
(01 = sampled, 00 = notsampled).
30+
'{version}-{traceId}-{spanId}-{sampleDecision}'
31+
-->
32+
<meta name="traceparent" content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01">
33+
<meta name="viewport" content="width=device-width, initial-scale=1">
34+
</head>
35+
<body>
36+
Example of using Web Tracer with document load plugin with console exporter and collector exporter
37+
</body>
38+
</html>
39+
```
40+
41+
## Installation
42+
43+
To create traces in the browser, you will need `@opentelemetry/web`, and the plugin `@opentelemetry/plugin-document-load`:
44+
45+
```shell
46+
npm install @opentelemetry/web @opentelemetry/plugin-document-load
47+
```
48+
49+
In the following we will use parcel as web application bundler, but you can of course also use any other build tool:
50+
51+
```shell
52+
npm install -g parcel
53+
```
54+
55+
## Initialization and Configuration
56+
57+
Create a empty file called `document-load.js` and add the following code to your html right before the body end tag:
58+
59+
```html
60+
<script type="text/javascript" src="document-load.js"></script>
61+
```
62+
63+
We will add some code that will trace the document load timings and output those as OpenTelemetry Spans.
64+
65+
## Creating a Tracer Provider
66+
67+
Add the following code to the `document-load.js` to create a tracer provider, which brings the plugin to trace document load:
68+
69+
```javascript
70+
// This is necessary for "parcel" to work OOTB. It is not needed for other build tools.
71+
import 'regenerator-runtime/runtime'
72+
import { LogLevel } from "@opentelemetry/core";
73+
import { WebTracerProvider } from '@opentelemetry/web';
74+
import { DocumentLoad } from '@opentelemetry/plugin-document-load';
75+
76+
// Minimum required setup - supports only synchronous operations
77+
const provider = new WebTracerProvider({
78+
plugins: [
79+
new DocumentLoad()
80+
]
81+
});
82+
provider.register();
83+
```
84+
85+
Run `parcel index.html` and open the development webserver (e.g. at `http://localhost:1234`) to see if your code works.
86+
87+
There will be no output of traces yet, for this we need to add an exporter
88+
89+
## Creating a Console Exporter
90+
91+
To export traces, modify `document-load.js` so that it matches the following code snippet:
92+
93+
```javascript
94+
// This is necessary for "parcel" to work OOTB. It is not needed for other build tools.
95+
import 'regenerator-runtime/runtime'
96+
import { LogLevel } from "@opentelemetry/core";
97+
import { WebTracerProvider } from '@opentelemetry/web';
98+
import { DocumentLoad } from '@opentelemetry/plugin-document-load';
99+
import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
100+
101+
// Minimum required setup - supports only synchronous operations
102+
const provider = new WebTracerProvider({
103+
plugins: [
104+
new DocumentLoad()
105+
]
106+
});
107+
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()))
108+
provider.register();
109+
```
110+
111+
Now, rebuild your application and open the browser again. In the console of the developer toolbar you should see some traces being exporterd:
112+
113+
```json
114+
{
115+
"traceId": "ab42124a3c573678d4d8b21ba52df3bf",
116+
"parentId": "cfb565047957cb0d",
117+
"name": "documentFetch",
118+
"id": "5123fc802ffb5255",
119+
"kind": 0,
120+
"timestamp": 1606814247811266,
121+
"duration": 9390,
122+
"attributes": {
123+
"component": "document-load",
124+
"http.response_content_length": 905
125+
},
126+
"status": {
127+
"code": 0
128+
},
129+
"events": [
130+
{
131+
"name": "fetchStart",
132+
"time": [
133+
1606814247,
134+
811266158
135+
]
136+
},
137+
{
138+
"name": "domainLookupStart",
139+
"time": [
140+
1606814247,
141+
811266158
142+
]
143+
},
144+
{
145+
"name": "domainLookupEnd",
146+
"time": [
147+
1606814247,
148+
811266158
149+
]
150+
},
151+
{
152+
"name": "connectStart",
153+
"time": [
154+
1606814247,
155+
811266158
156+
]
157+
},
158+
{
159+
"name": "connectEnd",
160+
"time": [
161+
1606814247,
162+
811266158
163+
]
164+
},
165+
{
166+
"name": "requestStart",
167+
"time": [
168+
1606814247,
169+
819101158
170+
]
171+
},
172+
{
173+
"name": "responseStart",
174+
"time": [
175+
1606814247,
176+
819791158
177+
]
178+
},
179+
{
180+
"name": "responseEnd",
181+
"time": [
182+
1606814247,
183+
820656158
184+
]
185+
}
186+
]
187+
}
188+
```

0 commit comments

Comments
 (0)