README.md

Available on:

| | | | ...or build it yourself!

made with 🧪 by theo.

Features

• Instruments selected webpages to generate logs and traces, sent to an OTLP-compatible of your choosing
• Choose from the available automatic instrumentations (or contribute your own)
  
  
  
  
• Choose where and how you want it to run! Don't worry about the extension tracking every single webpage, use match patterns (ex. https://<your-domain-here>.com/*) to specify the pages it should run on and have access to.
  
  
  
  
• No content-security policy errors! Works around typical CSP limitations by making fetch requests from the background script instead of the webpage
• Propagate b3 and w3c trace context to websites of your choosing (matched by regular expressions)

Browser compatibility

This extension is compatible with all major browsers as of Firefox 128! 🎉

Security considerations

Warning

You probably shouldn't run this extension on webpages you don't trust

Why?

The extension background script exports any Protobuf-encoded OTLP data that it receives from the injected content script that it's able to parse.

While some mitigations are implemented, the data can always be tampered with by any malicious Javascript running in the same context as the content script, and as such the integrity of the data cannot be guaranteed. This may result in minor frustrations like storing a bunch of garbage or worse depending on how your backend decodes Protobuf data.

So, just as a general safety measure, it's probably best if you don't allow the extension to run in untrusted pages (and you should kinda generally avoid running code in untrusted webpages if you aren't already, anyhow).

Can it be fixed?

Probably not in the near future. Unless browsers expose telemetry themselves, there's no way for the instrumentation to both run in an isolated context as well as gather the desired data.

Developing

Clone the repository:

git clone https://github.com/tbrockman/browser-extension-for-opentelemetry

Install dependencies:

pnpm install

Start the OpenTelemetry stack (Grafana + Quickwit + opentelemetry--contrib): ^{(optional if you have your own)}

docker compose up -d

Run the development server:

pnpm dev
# or for targetting a browser other than Chrome (the default)
pnpm dev --target=edge-mv3

Then, open your browser and load the appropriate development build. For example, if you're developing for Chrome, using manifest v3, use: build/chrome-mv3-dev.

Making a production build

Run the following:

pnpm build

or, for targeting a specific browser:

pnpm build:chrome
# or
pnpm build:safari
# or
pnpm build:edge
# or
pnpm build:firefox

Then, follow the same steps as with running the development server, but load the appropriate production build from the build directory, i.e: build/chrome-mv3-prod.

Safari

Safari requires a bit of extra work. After building the extension, run the following commands to convert the extension to a an XCode project:

pnpm convert:safari

Then, build the extension in XCode (using the MacOS target), and enable it in Safari.

Note

Safari requires extensions to be signed before they can be installed. You can either sign the extension yourself, or load it as an unsigned extension after enabling "allow unsigned extensions" in Safari's developer settings.