Merge pull request #2 from gsoft-inc/feat/add-instrumentation

feat: Add instrumentation

.changeset/loud-plums-smell.md

@@ -0,0 +1,5 @@
+---
+"@workleap/honeycomb": major
+---
+
+Initial release.

.gitignore

@@ -1,22 +1,10 @@
-# Logs
-logs
-*.log
-pnpm-debug.log*
-
 node_modules
 dist
-build
-dist-ssr
-*.local
+.pnpm-debug.log*
+.netlify
+.turbo
+.retype
 
-# Editor directories and files
-.idea
+# Mac
 .DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
-
-# npm pack
-*.tgz
+*.pem

CONTRIBUTING.md

@@ -7,7 +7,6 @@ The following documentation is only for the maintainers of this repository.
 - [Installation](#installation)
 - [Develop the lib](#develop-the-lib)
 - [Release the lib](#release-the-lib)
-- [Deploy the sample applications](#deploy-the-sample-applications)
 - [Available commands](#commands)
 - [CI](#ci)
 
@@ -109,20 +108,6 @@ By default, library compilation output will be in it's respective *dist* directo
 
 If you got linting error, most of the time, they can be fixed automatically using `eslint . --fix`, if not, follow the report provided by `pnpm lint`.
 
-## Deploy the sample application
-
-The site for this sample application is hosted on [Netlify](https://www.netlify.com/):
-
-- [host](https://squide-basic-host.netlify.app/) - TBD
-
-To deploy the sample application, open a terminal at the root of the repository and execute the following script:
-
-```bash
-deploy-sample
-```
-
-A prompt with a few questions will appear and then the site will automatically be deployed to production.
-
 ## Commands
 
 From the project root, you have access to many commands. The most important ones are:

README.md

@@ -1,6 +1,15 @@
 # wl-honeycomb-web
 
-TBD
+Shared [Honeycomb](https://www.honeycomb.io/) configuration for web applications at [Workleap](https://workleap.com/).
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
+[![CI](https://github.com/gsoft-inc/wl-honeycomb-web/actions/workflows/ci.yml/badge.svg)](https://github.com/gsoft-inc/wl-honeycomb-web/actions/workflows/ci.yml)
+
+### Packages
+
+| Name | NPM |
+| --- | --- |
+| [@workleap/honeycomb](packages/core/README.md) | [![npm version](https://img.shields.io/npm/v/@workleap/honeycomb)](https://www.npmjs.com/package/@workleap/honeycomb) |
 
 ## Have a question or found an issue?
 

docs/custom-traces.md

@@ -0,0 +1,25 @@
+---
+order: 90
+icon: hash
+---
+
+`@workleap/honeycomb` does not provide a proprietary API for traces. Applications are expected to use the [OpenTelemetry API](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution/#add-custom-instrumentation) to send custom traces to Honeycomb:
+
+```tsx src/Page.tsx
+import { useEffect } from "react";
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("sample");
+
+export function Page() {
+    useEffect(() => {
+        // OK, this is a pretty bad example.
+        const span = tracer.startSpan("sample-span");
+        span.end();
+    }, []);
+
+    return (
+        <div>Hello from a page!</div>
+    );
+}
+```

docs/getting-started.md

@@ -0,0 +1,153 @@
+---
+order: 100
+icon: rocket
+---
+
+# Getting started
+
+To monitor application performance, Workleap has adopted [Honeycomb](https://www.honeycomb.io/), a tool that helps teams manage and analyze telemetry data from distributed systems. Built on OpenTelemetry, Honeycomb provides a [robust API](https://open-telemetry.github.io/opentelemetry-js/) for tracking frontend telemetry.
+
+Honeycomb's in-house [HoneycombWebSDK](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution/) includes great default instrumentation. This package provides a slightly altered default instrumentation which is adapted for Workleap's web application observability requirements. 
+
+## Install the packages
+
+First, open a terminal at the root of the application and install the following packages:
+
++++ pnpm
+```bash
+pnpm add @workleap/honeycomb @honeycombio/opentelemetry-web @opentelemetry/api @opentelemetry/auto-instrumentations-web
+```
++++ yarn
+```bash
+yarn add @workleap/honeycomb @honeycombio/opentelemetry-web @opentelemetry/api @opentelemetry/auto-instrumentations-web
+```
++++ npm
+```bash
+npm install @workleap/honeycomb @honeycombio/opentelemetry-web @opentelemetry/api @opentelemetry/auto-instrumentations-web
+```
++++
+
+!!!warning
+While you can use any package manager to develop an application with Squide, it is highly recommended that you use [PNPM](https://pnpm.io/) as the guides has been developed and tested with PNPM.
+!!!
+
+## Register instrumentation
+
+Then, update the application bootstrapping code to register Honeycomb instrumentation using the [registerHoneycombInstrumentation](./reference/registerHoneycombInstrumentation.md) function:
+
+```tsx !#6-8 index.tsx
+import { registerHoneycombInstrumentation } from "@workleap/honeycomb";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.tsx";
+
+registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
+    endpoint: "https://sample-collector"
+});
+
+const root = createRoot(document.getElementById("root")!);
+
+root.render(
+    <StrictMode>
+        <App />
+    </StrictMode>
+);
+```
+
+!!!warning
+Avoid using `/.+/g,` in production, as it could expose customer data to third parties. Instead, ensure you specify values that accurately matches your application's backend URLs.
+!!!
+
+!!!warning
+We recommend using an [OpenTelemetry collector](https://docs.honeycomb.io/send-data/opentelemetry/collector/) over an ingestion [API key](https://docs.honeycomb.io/get-started/configure/environments/manage-api-keys/#create-api-key), as API keys can expose Workleap to potential attacks.
+!!!
+
+With instrumentation in place, a few traces are now available 👇
+
+### Fetch requests
+
+Individual fetch request performance can be monitored from end to end:
+
+:::align-image-left
+![Fetch instrumentation](./static/honeycomb-http-get.png)
+:::
+
+### Document load
+
+The loading performance of the DOM can be monitored:
+
+:::align-image-left
+![Document load instrumentation](./static/honeycomb-document-load.png)
+:::
+
+### Unmanaged error
+
+When an unmanaged error occurs, it's automatically recorded:
+
+:::align-image-left
+![Recorded error](./static/honeycomb-failing-http-request.png)
+:::
+
+### Real User Monitoring (RUM)
+
+The default instrumentation will automatically track the appropriate metrics to display RUM information:
+
+:::align-image-left
+![Largest Contentful Paint](./static/honeycomb-lcp.png){width=536 height=378}
+:::
+:::align-image-left
+![Cumulative Layout Shift](./static/honeycomb-cls.png){width=536 height=378}
+:::
+:::align-image-left
+![Interaction to Next Paint](./static/honeycomb-inp.png){width=532 height=358}
+:::
+
+## Set custom user attributes
+
+Most application needs to set custom attributes on traces about the current user environment. To help with that, `@workleap/honeycomb` expose the [setGlobalSpanAttribute](./reference/setGlobalSpanAttribute.md) function.
+
+Update your application bootstrapping code to include the `setGlobalSpanAttribute` function:
+
+```tsx !#10 index.tsx
+import { registerHoneycombInstrumentation, setGlobalSpanAttributes } from "@workleap/honeycomb";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.tsx";
+
+registerHoneycombInstrumentation(runtime, "sample", [/.+/g,], {
+    endpoint: "https://sample-collector"
+});
+
+setGlobalSpanAttribute("app.user_id", "123");
+
+const root = createRoot(document.getElementById("root")!);
+
+root.render(
+    <StrictMode>
+        <App />
+    </StrictMode>
+);
+```
+
+Now, every trace recorded after the execution of `setGlobalSpanAttributes` will include the custom attributes `app.user_id`:
+
+:::align-image-left
+![Custom attributes](./static/honeycomb-custom-attributes.png){width=204 height=161}
+:::
+
+## Custrom traces
+
+Have a look at the [custom traces](./custom-traces.md) page.
+
+## Try it :rocket:
+
+Start the application in a development environment using the dev script. Render a page, then navigate to your Honeycomb instance. Go to the "Query" page and type `name = HTTP GET` into the "Where" input. Run the query, select the "Traces" tab at the bottom of the page and view the detail of a trace. You should view information about the request.
+
+### Troubleshoot issues
+
+If you are experiencing issues with this guide:
+
+- Set the [debug](./reference/registerHoneycombInstrumentation.md#debug) predefined option to `true`.
+- Open the [DevTools](https://developer.chrome.com/docs/devtools/) console. You'll see a log entry for every Honeycomb traces.
+    - @`honeycombio/opentelemetry-web: Honeycomb link: https://ui.honeycomb.io/...`
+- Refer to the sample on [GitHub](https://github.com/gsoft-inc/wl-honeycomb-web/tree/main/sample).

docs/reference/default.md

@@ -0,0 +1,18 @@
+---
+order: 80
+icon: gear
+expanded: true
+toc:
+    depth: 2-3
+---
+
+# Reference
+
+## Artefacts
+
+- [Packages](./packages.md)
+
+## API
+
+- [registerHoneycombInstrumentation](./registerHoneycombInstrumentation.md)
+- [setGlobalSpanAttributes](./setGlobalSpanAttributes.md)

docs/reference/packages.md

@@ -0,0 +1,19 @@
+---
+order: 100
+---
+
+# Packages
+
+<style>
+.packages-table th:first-of-type {
+    width: 40% !important;
+}
+
+.packages-table th:nth-of-type(3) {
+    min-width: 120px !important;
+}
+</style>
+
+| Name | Description | NPM | { .packages-table }
+| --- | --- | --- |
+| :icon-mark-github: [@workleap/honeycomb](https://github.com/gsoft-inc/wl-honeycomb-web/tree/main/lib) | Shared Honeycomb configuration for web observability. | [![npm version](https://img.shields.io/npm/v/@workleap/honeycomb)](https://www.npmjs.com/package/@workleap/honeycomb) |