@opentelemetry/instrumentation-document-load

What is @opentelemetry/instrumentation-document-load?

@opentelemetry/instrumentation-document-load is an npm package that provides automatic instrumentation for document load events in web applications. It helps in capturing and reporting performance metrics related to the loading of web pages, which can be useful for monitoring and optimizing the performance of web applications.

What are @opentelemetry/instrumentation-document-load's main functionalities?

Automatic Instrumentation of Document Load

This feature allows you to automatically instrument document load events. The code sample demonstrates how to set up the instrumentation using the `DocumentLoadInstrumentation` class and `registerInstrumentations` function.

const { DocumentLoadInstrumentation } = require('@opentelemetry/instrumentation-document-load');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

registerInstrumentations({
  instrumentations: [
    new DocumentLoadInstrumentation(),
  ],
});

Custom Span Attributes

This feature allows you to add custom attributes to the spans created during document load events. The code sample shows how to use the `applyCustomAttributesOnSpan` option to set a custom attribute on the span.

const { DocumentLoadInstrumentation } = require('@opentelemetry/instrumentation-document-load');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const documentLoadInstrumentation = new DocumentLoadInstrumentation({
  applyCustomAttributesOnSpan: (span) => {
    span.setAttribute('custom_attribute', 'value');
  },
});

registerInstrumentations({
  instrumentations: [documentLoadInstrumentation],
});

Other packages similar to @opentelemetry/instrumentation-document-load

web-vitals

The `web-vitals` package is a library for measuring essential web performance metrics. It provides a simple API to capture metrics like First Contentful Paint (FCP), Largest Contentful Paint (LCP), and Cumulative Layout Shift (CLS). Unlike @opentelemetry/instrumentation-document-load, which focuses on OpenTelemetry standards and spans, `web-vitals` is more focused on Google's Web Vitals metrics.

README

OpenTelemetry Instrumentation Document Load

This module provides automated instrumentation for document load for Web applications.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save @opentelemetry/instrumentation-document-load

Usage

import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { B3Propagator } from '@opentelemetry/propagator-b3';
import { CompositePropagator, W3CTraceContextPropagator } from '@opentelemetry/core';

const provider = new WebTracerProvider();

provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));

provider.register({
  propagator: new CompositePropagator({
    propagators: [
      new B3Propagator(),
      new W3CTraceContextPropagator(),
    ],
  }),
});

registerInstrumentations({
  instrumentations: [
    new DocumentLoadInstrumentation(),
    new XMLHttpRequestInstrumentation({
      ignoreUrls: [/localhost/],
      propagateTraceHeaderCorsUrls: [
        'http://localhost:8090',
      ],
    }),
  ],
});

Optional: Send a trace parent from your server

This instrumentation supports connecting the server side spans for the initial HTML load with the client side span for the load from the browser's timing API. This works by having the server send its parent trace context (trace ID, span ID and trace sampling decision) to the client.

Because the browser does not send a trace context header for the initial page navigation, the server needs to fake a trace context header in a middleware and then send that trace context header back to the client as a meta tag traceparent . The traceparent meta tag should be in the trace context W3C draft format . For example:

  ...
<head>
  <!--
    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 = notsampled).
    '{version}-{traceId}-{spanId}-{sampleDecision}'
  -->
  <meta name="traceparent" content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01">
</head>
<body>
  ...
  <script>
    // and then initialise the WebTracer
    // var webTracer = new WebTracer({ .......
  </script>
</body>

See examples/tracer-web for a short example.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.