Skip to content

README.md

Latest commit

 

History

History
239 lines (178 loc) · 9.78 KB

README.md

File metadata and controls

239 lines (178 loc) · 9.78 KB
Raw

@microsoft/opentelemetry-browser

Status Milestone License: MIT

Microsoft OpenTelemetry distribution for browser applications — one import, one call, page views, exceptions, fetch/XHR tracing and manual telemetry across Azure Monitor and OTLP-compatible backends.

This is the browser sibling of the Microsoft distributions for Node.js and Python.

Not published yet. This repository currently holds the implementation plan and a working proof of concept. The package name is provisional and the beta is targeted for 9 October. Everything below describes the surface being built — see planning/.

Getting Started

Prerequisites

Install the package

npm install @microsoft/opentelemetry-browser

Quick start

Call useMicrosoftOpenTelemetry() as early as possible in your application entry point, before the code you want instrumented runs.

Azure Monitor:

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry-browser";

useMicrosoftOpenTelemetry({
  azureMonitor: {
    connectionString: "InstrumentationKey=...;IngestionEndpoint=...",
  },
});

OTLP:

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry-browser";

useMicrosoftOpenTelemetry({
  otlp: {
    endpoint: "https://collector.example.com:4318",
  },
});

That's it — page views, SPA soft navigations, unhandled errors and promise rejections, and fetch/XHR spans with W3C trace context are collected automatically, with session.id and document context on both signals.

Manual telemetry

Use the standard upstream OpenTelemetry APIs. The distribution never asks you to learn a proprietary telemetry API, so instrumented code stays valid OpenTelemetry.

import { trace } from "@opentelemetry/api";
import { logs } from "@opentelemetry/api-logs";

const tracer = trace.getTracer("my-app", "1.0.0");
const span = tracer.startSpan("checkout");
span.setAttribute("cart.item_count", 3);
span.end();

logs.getLogger("my-app", "1.0.0").emit({
  eventName: "app.checkout_started",
  attributes: { "cart.item_count": 3 },
});

Browser occurrences are log records carrying a top-level eventName; spans are reserved for operations with real duration and backend correlation. See §2 of the plan.

Flush and shutdown

Telemetry is batched and flushed automatically on pagehide and visibilitychange. The handle returned by useMicrosoftOpenTelemetry() lets you do it explicitly:

const telemetry = useMicrosoftOpenTelemetry({ /* ... */ });

await telemetry.forceFlush();
await telemetry.shutdown();

Configuration

MicrosoftOpenTelemetryBrowserOptions

Option Type Default Description
azureMonitor AzureMonitorOptions — Azure Monitor destination. When provided, Azure Monitor export is enabled
otlp OtlpOptions — OTLP/HTTP destination for traces and logs
resource Resource default resource OpenTelemetry Resource. Add browserDetector or userAgentDetector to attach browser attributes
samplingRatio number 1.0 Ratio of traces to sample (0.0–1.0)
instrumentationOptions InstrumentationOptions see below Toggle built-in instrumentations
spanProcessors SpanProcessor[] — Additional upstream span processors
logRecordProcessors LogRecordProcessor[] — Additional upstream log record processors
propagator TextMapPropagator W3C Trace Context + Baggage Context propagator
propagateToUrls (string | RegExp)[] same origin Allow list for outbound traceparent injection
session SessionOptions 30 min timeout Session ID generation, storage, timeout and renewal

Configuration is validated and normalized into an immutable snapshot before any global is registered or any browser API is patched. Upstream types are passed through rather than re-modelled.

azureMonitor options

Option Type Default Description
connectionString string — Application Insights connection string, including sovereign clouds
disableBeacon boolean false Disable the sendBeacon fallback used on page unload

otlp options

Option Type Default Description
endpoint string — Base OTLP/HTTP endpoint
headers Record<string, string> — Additional headers on export requests

instrumentationOptions

Instrumentations are named by the occurrence they capture, not by the package that produces them, and each is individually enableable and individually importable — so an events-only consumer never pays for the tracing SDK and vice versa.

useMicrosoftOpenTelemetry({
  azureMonitor: { connectionString: "..." },
  instrumentationOptions: {
    pageView: { enabled: true },
    exception: { enabled: true },
    fetch: { enabled: false },
    xmlHttpRequest: { enabled: false },
  },
});

Bundle size

Bundle size is the binding constraint for a browser distribution, so it is measured on every build rather than argued about. From poc/SIZE_REPORT.md, gzipped:

Layer Gzip
OpenTelemetry API only (trace + logs) 3.70 KB
+ SDK (providers, batch processors, W3C propagators) 19.56 KB
+ multi-instance bridge 21.29 KB
+ all 9 instrumentations and both OTLP exporters 41.50 KB

For comparison, Application Insights v3 ships 71.3 KB gzipped and Splunk's OpenTelemetry browser distribution 140.5 KB. The per-package deltas, and why per-package numbers must never be summed, are in poc/SIZE_REPORT.md, regenerated by npm run size.

Supported environments

Runtime Support
ES2022+ browsers (current Chrome, Edge, Firefox, Safari) Full distribution
ES2015 to pre-ES2020 browsers Capability-detecting loader, planned
Pre-ES2015 browsers Not supported; separate no-op package, planned

The package is ESM-only with an exports map and no main/module fields. Not shipping ES5 is the single largest bundle-size lever available, so legacy runtimes are handled by a loader rather than by downleveling the main bundle.

Contributing

See CONTRIBUTING.md for development setup and pull request guidance.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the pull request appropriately. You only need to do this once across repositories using this CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com.

Data Collection

As this SDK is designed to enable applications to perform data collection which is sent to Microsoft collection endpoints, the following notice identifies our privacy statement.

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Telemetry collection starts only when an application initializes the SDK and configures an exporter. Omit optional entries from instrumentations to disable them, and set pageView.enabled to false to disable automatic page-view collection. Call shutdown() on the returned handle to stop collection and export. See PRIVACY.md for additional guidance for applications that use this SDK.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third parties' policies.

Reporting Security Issues

See SECURITY.md for information on reporting vulnerabilities.

License

MIT