257 lines
7.2 KiB
Markdown
257 lines
7.2 KiB
Markdown
---
|
|
title: Browser
|
|
aliases: [/docs/js/getting_started/browser]
|
|
description: Learn how to add OpenTelemetry to your browser app
|
|
weight: 20
|
|
---
|
|
|
|
{{% alert title="Warning" color="warning" %}}
|
|
{{% _param notes.browser-instrumentation %}} {{% /alert %}}
|
|
|
|
While this guide uses the example application presented below, the steps to
|
|
instrument your own application should be similar.
|
|
|
|
## Prerequisites
|
|
|
|
Ensure that you have the following installed locally:
|
|
|
|
- [Node.js](https://nodejs.org/en/download/)
|
|
- [TypeScript](https://www.typescriptlang.org/download), if you will be using
|
|
TypeScript.
|
|
|
|
## Example Application
|
|
|
|
This is a very simple guide, if you'd like to see more complex examples go to
|
|
[examples/opentelemetry-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/opentelemetry-web).
|
|
|
|
Copy the following file into an empty directory and call it `index.html`.
|
|
|
|
```html
|
|
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<title>Document Load Instrumentation Example</title>
|
|
<base href="/" />
|
|
<!--
|
|
https://www.w3.org/TR/trace-context/
|
|
Set the `traceparent` in the server's HTML template code. It should be
|
|
dynamically generated server side to have the server's request trace Id,
|
|
a parent span Id that was set on the server's request span, and the trace
|
|
flags to indicate the server's sampling decision
|
|
(01 = sampled, 00 = not sampled).
|
|
'{version}-{traceId}-{spanId}-{sampleDecision}'
|
|
-->
|
|
<meta
|
|
name="traceparent"
|
|
content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01"
|
|
/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
</head>
|
|
<body>
|
|
Example of using Web Tracer with document load instrumentation with console
|
|
exporter and collector exporter
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### Installation
|
|
|
|
To create traces in the browser, you will need `@opentelemetry/sdk-trace-web`,
|
|
and the instrumentation `@opentelemetry/instrumentation-document-load`:
|
|
|
|
```shell
|
|
npm init -y
|
|
npm install @opentelemetry/api \
|
|
@opentelemetry/sdk-trace-web \
|
|
@opentelemetry/instrumentation-document-load \
|
|
@opentelemetry/context-zone
|
|
```
|
|
|
|
### Initialization and Configuration
|
|
|
|
If you are coding in TypeScript, then run the following command:
|
|
|
|
```shell
|
|
tsc --init
|
|
```
|
|
|
|
Then acquire [parcel](https://parceljs.org/), which will (among other things)
|
|
let you work in TypeScript.
|
|
|
|
```shell
|
|
npm install --save-dev parcel
|
|
```
|
|
|
|
Create an empty code file named `document-load` with a `.ts` or `.js` extension,
|
|
as appropriate, based on the language you've chosen to write your app in. Add
|
|
the following code to your HTML right before the `</body>` closing tag:
|
|
|
|
{{< tabpane text=true >}} {{% tab TypeScript %}}
|
|
|
|
```html
|
|
<script type="module" src="document-load.ts"></script>
|
|
```
|
|
|
|
{{% /tab %}} {{% tab JavaScript %}}
|
|
|
|
```html
|
|
<script type="module" src="document-load.js"></script>
|
|
```
|
|
|
|
{{% /tab %}} {{< /tabpane >}}
|
|
|
|
We will add some code that will trace the document load timings and output those
|
|
as OpenTelemetry Spans.
|
|
|
|
### Creating a Tracer Provider
|
|
|
|
Add the following code to the `document-load.ts|js` to create a tracer provider,
|
|
which brings the instrumentation to trace document load:
|
|
|
|
```js
|
|
/* document-load.ts|js file - the code snippet is the same for both the languages */
|
|
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
|
|
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
|
|
import { ZoneContextManager } from '@opentelemetry/context-zone';
|
|
import { registerInstrumentations } from '@opentelemetry/instrumentation';
|
|
|
|
const provider = new WebTracerProvider();
|
|
|
|
provider.register({
|
|
// Changing default contextManager to use ZoneContextManager - supports asynchronous operations - optional
|
|
contextManager: new ZoneContextManager(),
|
|
});
|
|
|
|
// Registering instrumentations
|
|
registerInstrumentations({
|
|
instrumentations: [new DocumentLoadInstrumentation()],
|
|
});
|
|
```
|
|
|
|
Now build the app with parcel:
|
|
|
|
```shell
|
|
npx parcel index.html
|
|
```
|
|
|
|
and open the development web server (e.g. at `http://localhost:1234`) to see if
|
|
your code works.
|
|
|
|
There will be no output of traces yet, for this we need to add an exporter.
|
|
|
|
### Creating an Exporter
|
|
|
|
In the following example, we will use the `ConsoleSpanExporter` which prints all
|
|
spans to the console.
|
|
|
|
In order to visualize and analyze your traces, you will need to export them to a
|
|
tracing backend. Follow [these instructions](../../exporters) for setting up a
|
|
backend and exporter.
|
|
|
|
You may also want to use the `BatchSpanProcessor` to export spans in batches in
|
|
order to more efficiently use resources.
|
|
|
|
To export traces to the console, modify `document-load.ts|js` so that it matches
|
|
the following code snippet:
|
|
|
|
```js
|
|
/* document-load.ts|js file - the code is the same for both the languages */
|
|
import {
|
|
ConsoleSpanExporter,
|
|
SimpleSpanProcessor,
|
|
} from '@opentelemetry/sdk-trace-base';
|
|
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
|
|
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
|
|
import { ZoneContextManager } from '@opentelemetry/context-zone';
|
|
import { registerInstrumentations } from '@opentelemetry/instrumentation';
|
|
|
|
const provider = new WebTracerProvider();
|
|
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
|
|
|
|
provider.register({
|
|
// Changing default contextManager to use ZoneContextManager - supports asynchronous operations - optional
|
|
contextManager: new ZoneContextManager(),
|
|
});
|
|
|
|
// Registering instrumentations
|
|
registerInstrumentations({
|
|
instrumentations: [new DocumentLoadInstrumentation()],
|
|
});
|
|
```
|
|
|
|
Now, rebuild your application and open the browser again. In the console of the
|
|
developer toolbar you should see some traces being exported:
|
|
|
|
```json
|
|
{
|
|
"traceId": "ab42124a3c573678d4d8b21ba52df3bf",
|
|
"parentId": "cfb565047957cb0d",
|
|
"name": "documentFetch",
|
|
"id": "5123fc802ffb5255",
|
|
"kind": 0,
|
|
"timestamp": 1606814247811266,
|
|
"duration": 9390,
|
|
"attributes": {
|
|
"component": "document-load",
|
|
"http.response_content_length": 905
|
|
},
|
|
"status": {
|
|
"code": 0
|
|
},
|
|
"events": [
|
|
{
|
|
"name": "fetchStart",
|
|
"time": [1606814247, 811266158]
|
|
},
|
|
{
|
|
"name": "domainLookupStart",
|
|
"time": [1606814247, 811266158]
|
|
},
|
|
{
|
|
"name": "domainLookupEnd",
|
|
"time": [1606814247, 811266158]
|
|
},
|
|
{
|
|
"name": "connectStart",
|
|
"time": [1606814247, 811266158]
|
|
},
|
|
{
|
|
"name": "connectEnd",
|
|
"time": [1606814247, 811266158]
|
|
},
|
|
{
|
|
"name": "requestStart",
|
|
"time": [1606814247, 819101158]
|
|
},
|
|
{
|
|
"name": "responseStart",
|
|
"time": [1606814247, 819791158]
|
|
},
|
|
{
|
|
"name": "responseEnd",
|
|
"time": [1606814247, 820656158]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Add Instrumentations
|
|
|
|
If you want to instrument Ajax requests, User Interactions and others, you can
|
|
register additional instrumentations for those:
|
|
|
|
```javascript
|
|
registerInstrumentations({
|
|
instrumentations: [
|
|
new UserInteractionInstrumentation(),
|
|
new XMLHttpRequestInstrumentation(),
|
|
],
|
|
});
|
|
```
|
|
|
|
## Meta Packages for Web
|
|
|
|
To leverage the most common instrumentations all in one you can simply use the
|
|
[OpenTelemetry Meta Packages for Web](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-web)
|