Skip to content

Commit 91db060

Browse files
eskirkeskirk
authored
Merge pull request #1 from grafana/elliot/documentation
bundler plugin documentation
2 parents 5ecfd08 + d8da257 commit 91db060

File tree

6 files changed

+265
-1
lines changed

6 files changed

+265
-1
lines changed

‎README.md

+119-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,121 @@
11
# Faro JavaScript Bundler Plugins
22

3-
A collection of plugins for various JavaScript bundlers. Used in conjunction with the [Faro Web SDK](https://github.com/grafana/faro-web-sdk) to unlock additional features in [Grafana Cloud Frontend Observability](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/).
3+
A collection of plugins for various JavaScript bundlers. Used in conjunction with the [Faro Web SDK](https://github.com/grafana/faro-web-sdk) to unlock additional features in [Grafana Cloud Frontend Observability](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/).
4+
5+
## Getting started
6+
7+
The Faro JavaScript Bundler Plugins are designed to be used with the [Faro Web SDK](https://github.com/grafana/faro-web-sdk) and [Grafana Cloud Frontend Observability](https://grafana.com/products/cloud/frontend-observability-for-real-user-monitoring/). To use these bundler plugins, you must first have instrumented your JavaScript application with Faro and be sending your telemetry data to a Faro Collector endpoint in Grafana Cloud. Follow the Frontend Observability [quickstart guide](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/quickstart/javascript/) to get started.
8+
9+
Once you have an insrumented JavaScript application sending data to Grafana Cloud, you are ready to get started.
10+
11+
## Installation
12+
13+
To install the Faro JavaScript Bundler Plugins, use the package manager of your choice.
14+
15+
### Webpack
16+
17+
To install the Webpack plugin with `npm`, run:
18+
19+
```bash
20+
npm install @grafana/faro-bundler-plugin-webpack
21+
```
22+
23+
To install the Webpack plugin with `yarn`, run:
24+
25+
```bash
26+
yarn add @grafana/faro-bundler-plugin-webpack
27+
```
28+
29+
### Rollup/Vite
30+
31+
Rollup and Vite are both supported by the same plugin.
32+
33+
To install the Rollup/Vite plugin with `npm`, run:
34+
35+
```bash
36+
npm install @grafana/faro-bundler-plugin-rollup
37+
```
38+
39+
To install the Rollup/Vite plugin with `yarn`, run:
40+
41+
```bash
42+
yarn add @grafana/faro-bundler-plugin-rollup
43+
```
44+
45+
## Obtaining API Key
46+
47+
!! TODO - Add instructions on how to obtain API key !!
48+
49+
## Usage
50+
51+
Details of how to use the plugins with your bundler are provided in the Frontend Observability plugin under the "Web SDK Configuration" tab after clicking into your instrumented app.
52+
53+
That tab includes the necessary configuration for the Faro JavaScript Bundler Plugins, including the `appName`, `appId`, and `endpoint` values that are required for the plugins to work with your app. The details provided below are general instructions for how to use the plugins with your bundler.
54+
55+
### Webpack
56+
57+
To use the Webpack plugin, add the following to your `webpack.config.js`:
58+
59+
```javascript
60+
// other imports
61+
import FaroSourcemapUploaderPlugin from "@grafana/faro-webpack-plugin";
62+
63+
module.exports = {
64+
// other configs
65+
plugins: [
66+
// other plugins
67+
new FaroSourcemapUploaderPlugin({
68+
appName: "$your-app-name",
69+
endpoint: "$your-faro-collector-url",
70+
apiKey: "$your-api-key",
71+
appId: "$your-app-id",
72+
orgId: "$your-org-id",
73+
gzipContents: true,
74+
}),
75+
],
76+
};
77+
```
78+
79+
### Rollup/Vite
80+
81+
To use the Rollup/Vite plugin, add the following to your `rollup.config.js` or `vite.config.js`:
82+
83+
```javascript
84+
// other imports
85+
import faroUploader from '@grafana/faro-bundler-plugin-rollup';
86+
87+
export default defineConfig(({ mode }) => {
88+
return {
89+
// other configs
90+
plugins: [
91+
// other plugins
92+
faroUploader({
93+
appName: "$your-app-name",
94+
endpoint: "$your-faro-collector-url",
95+
apiKey: "$your-api-key",
96+
appId: "$your-app-id",
97+
orgId: "$your-org-id",
98+
gzipContents: true,
99+
}),
100+
],
101+
};
102+
```
103+
104+
### Configuration Options
105+
106+
The following options are available for the Faro JavaScript Bundler Plugins:
107+
108+
- `appName: string` (required): The name of your application. This should match the `appName` value you are using in your Faro Web SDK configuration.
109+
- `endpoint: string` (required): The URL of your Faro Collector endpoint. This value is generated in the Frontend Observability plugin under "Web SDK Configuration".
110+
- `apiKey: string` (required): The API key for your Faro Collector. This value is generated on grafana.com by creating a new scope (details provided in the plugin and in the "Obtaining API Key" section of this document).
111+
- `appId: string` (required): The ID of your application. This should match the `appId` value you are using in your Faro Web SDK configuration.
112+
- `orgId: string` (required): The ID of your organization. This value is provided in the Frontend Observability plugin under "Web SDK Configuration".
113+
- `outputFiles: string[]` (optional): An array of sourcemap files to upload. By default, all sourcemaps are uploaded.
114+
- `bundleId: string` (optional): The ID of the bundle/build. You can specify this value to filter by bundle ID in the Frontend Observability plugin. Otherwise an auto-generated ID will be used.
115+
- `keepSourcemaps: boolean` (optional): Whether to keep the sourcemaps in your generated bundle after uploading. Defaults to `false`.
116+
- `gzipContents: boolean` (optional): Whether to tarball and gzip the contents of the sourcemaps before uploading. Defaults to `true`.
117+
- `verbose: boolean` (optional): Whether to log verbose output during the upload process. Defaults to `false`.
118+
119+
After initial configuration, the Faro JavaScript Bundler Plugins will automatically upload your source maps to Grafana Cloud when you build your application. You can verify that the source maps are being uploaded by "Sourcemaps" tab in the Frontend Observability plugin. From there you are able to see the source maps that have been uploaded.
120+
121+
Once you have completed all the required steps, you are done - the Faro Collector will begin processing your source maps and associating them with your telemetry data. The portions of your stacktraces with source maps that have been uploaded to the Faro Collector will be automatically deobfuscated and displayed in the Frontend Observability plugin when viewing your error data.

‎packages/faro-bundlers-shared/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Faro Sourcemap Upload Plugin Shared Utils
2+
3+
This package contains shared utilities for the Faro sourcemap upload plugins for Webpack, Rollup, and Vite.

‎packages/faro-rollup/README.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Faro Sourcemap Upload Plugin - Rollup/Vite
2+
3+
This plugin uploads sourcemaps to the Faro collector to enable deobfuscation of stack traces in the Grafana Cloud Frontend Observability UI.
4+
5+
## Installation
6+
7+
To install the Faro JavaScript Bundler Plugins for Rollup/Vite, use the package manager of your choice.
8+
9+
To install the Rollup/Vite plugin with `npm`, run:
10+
11+
```bash
12+
npm install @grafana/faro-bundler-plugin-rollup
13+
```
14+
15+
To install the Rollup/Vite plugin with `yarn`, run:
16+
17+
```bash
18+
yarn add @grafana/faro-bundler-plugin-rollup
19+
```
20+
21+
## Usage
22+
23+
Details of how to use the plugins with your bundler are provided in the Frontend Observability plugin under the "Web SDK Configuration" tab after clicking into your instrumented app.
24+
25+
That tab includes the necessary configuration for the Faro JavaScript Bundler Plugins, including the `appName`, `appId`, and `endpoint` values that are required for the plugins to work with your app. The details provided below are general instructions for how to use the plugins with your bundler.
26+
27+
### Rollup/Vite
28+
29+
To use the Rollup/Vite plugin, add the following to your `rollup.config.js` or `vite.config.js`:
30+
31+
```javascript
32+
// other imports
33+
import faroUploader from '@grafana/faro-bundler-plugin-rollup';
34+
35+
export default defineConfig(({ mode }) => {
36+
return {
37+
// other configs
38+
plugins: [
39+
// other plugins
40+
faroUploader({
41+
appName: "$your-app-name",
42+
endpoint: "$your-faro-collector-url",
43+
apiKey: "$your-api-key",
44+
appId: "$your-app-id",
45+
orgId: "$your-org-id",
46+
gzipContents: true,
47+
}),
48+
],
49+
};
50+
```
51+
52+
### Configuration Options
53+
54+
The following options are available for the Faro JavaScript Bundler Plugins:
55+
56+
- `appName: string` (required): The name of your application. This should match the `appName` value you are using in your Faro Web SDK configuration.
57+
- `endpoint: string` (required): The URL of your Faro Collector endpoint. This value is generated in the Frontend Observability plugin under "Web SDK Configuration".
58+
- `apiKey: string` (required): The API key for your Faro Collector. This value is generated on grafana.com by creating a new scope (details provided in the plugin and in the "Obtaining API Key" section of this document).
59+
- `appId: string` (required): The ID of your application. This should match the `appId` value you are using in your Faro Web SDK configuration.
60+
- `orgId: string` (required): The ID of your organization. This value is provided in the Frontend Observability plugin under "Web SDK Configuration".
61+
- `outputFiles: string[]` (optional): An array of sourcemap files to upload. By default, all sourcemaps are uploaded.
62+
- `bundleId: string` (optional): The ID of the bundle/build. You can specify this value to filter by bundle ID in the Frontend Observability plugin. Otherwise an auto-generated ID will be used.
63+
- `keepSourcemaps: boolean` (optional): Whether to keep the sourcemaps in your generated bundle after uploading. Defaults to `false`.
64+
- `gzipContents: boolean` (optional): Whether to tarball and gzip the contents of the sourcemaps before uploading. Defaults to `true`.
65+
- `verbose: boolean` (optional): Whether to log verbose output during the upload process. Defaults to `false`.
66+
67+
After initial configuration, the Faro JavaScript Bundler Plugins will automatically upload your source maps to Grafana Cloud when you build your application. You can verify that the source maps are being uploaded by "Sourcemaps" tab in the Frontend Observability plugin. From there you are able to see the source maps that have been uploaded.
68+
69+
Once you have completed all the required steps, you are done - the Faro Collector will begin processing your source maps and associating them with your telemetry data. The portions of your stacktraces with source maps that have been uploaded to the Faro Collector will be automatically deobfuscated and displayed in the Frontend Observability plugin when viewing your error data.

‎packages/faro-rollup/src/index.ts

+6
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,12 @@ export default function faroUploader(
3232

3333
return {
3434
name: ROLLUP_PLUGIN_NAME,
35+
/**
36+
* Renders a chunk of code and generates a source map with a bundleId code snippet injected at the end.
37+
* @param code The original code of the chunk.
38+
* @param chunk The chunk object containing information about the file.
39+
* @returns An object with the rendered code and the generated source map, or null if the chunk's file extension does not match the patterns.
40+
*/
3541
renderChunk(code, chunk) {
3642
if (chunk.fileName.match(/\.(js|ts|jsx|tsx|mjs|cjs)$/)) {
3743
const newCode = new MagicString(code);

‎packages/faro-webpack/README.md

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Faro Sourcemap Upload Plugin - Webpack
2+
3+
This plugin uploads sourcemaps to the Faro collector to enable deobfuscation of stack traces in the Grafana Cloud Frontend Observability UI.
4+
5+
## Installation
6+
7+
To install the Faro JavaScript Bundler Plugins for Webpack, use the package manager of your choice.
8+
9+
```bash
10+
npm install @grafana/faro-bundler-plugin-webpack
11+
```
12+
13+
To install the Webpack plugin with `yarn`, run:
14+
15+
```bash
16+
yarn add @grafana/faro-bundler-plugin-webpack
17+
```
18+
19+
## Usage
20+
21+
Details of how to use the plugins with your bundler are provided in the Frontend Observability plugin under the "Web SDK Configuration" tab after clicking into your instrumented app.
22+
23+
That tab includes the necessary configuration for the Faro JavaScript Bundler Plugins, including the `appName`, `appId`, and `endpoint` values that are required for the plugins to work with your app. The details provided below are general instructions for how to use the plugins with your bundler.
24+
25+
To use the Webpack plugin, add the following to your `webpack.config.js`:
26+
27+
```javascript
28+
// other imports
29+
import FaroSourcemapUploaderPlugin from "@grafana/faro-webpack-plugin";
30+
31+
module.exports = {
32+
// other configs
33+
plugins: [
34+
// other plugins
35+
new FaroSourcemapUploaderPlugin({
36+
appName: "$your-app-name",
37+
endpoint: "$your-faro-collector-url",
38+
apiKey: "$your-api-key",
39+
appId: "$your-app-id",
40+
orgId: "$your-org-id",
41+
gzipContents: true,
42+
}),
43+
],
44+
};
45+
```
46+
47+
### Configuration Options
48+
49+
The following options are available for the Faro JavaScript Bundler Plugins:
50+
51+
- `appName: string` (required): The name of your application. This should match the `appName` value you are using in your Faro Web SDK configuration.
52+
- `endpoint: string` (required): The URL of your Faro Collector endpoint. This value is generated in the Frontend Observability plugin under "Web SDK Configuration".
53+
- `apiKey: string` (required): The API key for your Faro Collector. This value is generated on grafana.com by creating a new scope (details provided in the plugin and in the "Obtaining API Key" section of this document).
54+
- `appId: string` (required): The ID of your application. This should match the `appId` value you are using in your Faro Web SDK configuration.
55+
- `orgId: string` (required): The ID of your organization. This value is provided in the Frontend Observability plugin under "Web SDK Configuration".
56+
- `outputFiles: string[]` (optional): An array of sourcemap files to upload. By default, all sourcemaps are uploaded.
57+
- `bundleId: string` (optional): The ID of the bundle/build. You can specify this value to filter by bundle ID in the Frontend Observability plugin. Otherwise an auto-generated ID will be used.
58+
- `keepSourcemaps: boolean` (optional): Whether to keep the sourcemaps in your generated bundle after uploading. Defaults to `false`.
59+
- `gzipContents: boolean` (optional): Whether to tarball and gzip the contents of the sourcemaps before uploading. Defaults to `true`.
60+
- `verbose: boolean` (optional): Whether to log verbose output during the upload process. Defaults to `false`.
61+
62+
After initial configuration, the Faro JavaScript Bundler Plugins will automatically upload your source maps to Grafana Cloud when you build your application. You can verify that the source maps are being uploaded by "Sourcemaps" tab in the Frontend Observability plugin. From there you are able to see the source maps that have been uploaded.
63+
64+
Once you have completed all the required steps, you are done - the Faro Collector will begin processing your source maps and associating them with your telemetry data. The portions of your stacktraces with source maps that have been uploaded to the Faro Collector will be automatically deobfuscated and displayed in the Frontend Observability plugin when viewing your error data.

‎packages/faro-webpack/src/index.ts

+4
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ export default class FaroSourcemapUploaderPlugin
4141
this.verbose = options.verbose;
4242
}
4343

44+
/**
45+
* Applies the plugin to the webpack compiler. Applies a BannerPlugin to the generated bundle containing the bundleId code snippet.
46+
* @param compiler The webpack compiler.
47+
*/
4448
apply(compiler: webpack.Compiler): void {
4549
const BannerPlugin = compiler.webpack.BannerPlugin;
4650
const outputPath = compiler.options.output.path;

0 commit comments

Comments
 (0)