Browser
Warning
Client instrumentation for the browser is experimental and mostly unspecified. If you are interested in helping out, get in touch with the Client Instrumentation SIG.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
- TypeScript, 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.
Copy the following file into an empty directory and call it index.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:
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:
tsc --init
Then acquire parcel, which will (among other things) let you work in TypeScript.
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:
<script type="module" src="document-load.ts"></script>
<script type="module" src="document-load.js"></script>
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:
/* 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:
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 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:
/* 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:
{
"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:
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