@opentelemetry/instrumentation-document-load
TypeScript icon, indicating that this package has built-in type declarations

0.39.0 • Public • Published

OpenTelemetry Instrumentation Document Load

NPM Published Version Apache License

This module provides automatic instrumentation for document load for Web applications, which may be loaded using the @opentelemetry/sdk-trace-web package.

If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-web bundle with @opentelemetry/sdk-trace-web for the most seamless instrumentation experience.

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>

Optional : Add custom attributes to spans if needed

If it is needed to add custom attributes to the document load span,and/or document fetch span and/or resource fetch spans, respective functions to do so needs to be provided as a config to the DocumentLoad Instrumentation as shown below. The attributes will be added to the respective spans before the individual are spans are ended. If the function throws an error , no attributes will be added to the span and the rest of the process continues.

const addCustomAttributesToSpan = (span: Span) => {
  span.setAttribute('<custom.attribute.key>','<custom-attribute-value>');
}
const addCustomAttributesToResourceFetchSpan = (span: Span, resource: PerformanceResourceTiming) => {
  span.setAttribute('<custom.attribute.key>','<custom-attribute-value>');
  span.setAttribute('resource.tcp.duration_ms', resource.connectEnd - resource.connectStart);
}
registerInstrumentations({
  instrumentations: [
    new DocumentLoadInstrumentation({
        applyCustomAttributesOnSpan: {
            documentLoad: addCustomAttributesToSpan,
            resourceFetch: addCustomAttributesToResourceFetchSpan
        }
    })
    ]
})

See examples/tracer-web for a short example.

Document Load Instrumentation Options

The document load instrumentation plugin has few options available to choose from. You can set the following:

Options Type Description
applyCustomAttributesOnSpan.documentLoad DocumentLoadCustomAttributeFunction Function for adding custom attributes to documentLoad spans.
applyCustomAttributesOnSpan.documentFetch DocumentLoadCustomAttributeFunction Function for adding custom attributes to documentFetch spans.
applyCustomAttributesOnSpan.resourceFetch ResourceFetchCustomAttributeFunction Function for adding custom attributes to resourceFetch spans
ignoreNetworkEvents boolean Ignore adding network events as span events for document fetch and resource fetch spans.
ignorePerformancePaintEvents boolean Ignore adding performance resource paint span events to document load spans.

Semantic Conventions

This package uses @opentelemetry/semantic-conventions version 1.22+, which implements Semantic Convention Version 1.7.0

Attributes collected:

Attribute Short Description
http.url Full HTTP request URL in the form scheme://host[:port]/path?query[#fragment]
http.user_agent Value of the HTTP User-Agent header sent by the client

Useful links

License

Apache 2.0 - See LICENSE for more information.

Package Sidebar

Install

npm i @opentelemetry/instrumentation-document-load

Weekly Downloads

117,058

Version

0.39.0

License

Apache-2.0

Unpacked Size

174 kB

Total Files

87

Last publish

Collaborators

  • pichlermarc
  • bogdandrutu
  • dyladan