feat: Integrate @workleap/honeycomb

.changeset/wild-buttons-swim.md

@@ -0,0 +1,5 @@
+---
+"@squide/firefly-honeycomb": patch
+---
+
+This package is now a wrapper around `@workleap/honeycomb`.

docs/guides/setup-honeycomb.md

@@ -60,8 +60,8 @@ await bootstrap(runtime, {
 });
 
 // Register Honeycomb instrumentation.
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector"
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector"
 });
 
 const root = createRoot(document.getElementById("root")!);

docs/reference/honeycomb/registerHoneycombInstrumentation.md

@@ -5,7 +5,11 @@ toc:
 
 # registerHoneycombInstrumentation
 
-Initializes an instance of [Honeycomb Web SDK](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution) and registers custom instrumentation to monitor the performance of a Squide application.
+Initialize an instance of [Honeycomb Web SDK](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution) and registers custom instrumentation to monitor the performance of a Squide application.
+
+!!!info
+This function serves as a wrapper around the [@workleap/honeycomb](https://www.npmjs.com/package/@workleap/honeycomb) library. Before using it, read the documentation for the [registerHoneycombInstrumentation](https://gsoft-inc.github.io/wl-honeycomb-web/reference/registerhoneycombinstrumentation) function provided by `@workleap/honeycomb`.
+!!!
 
 ## Reference
 
@@ -19,39 +23,67 @@ registerHoneycombInstrumentation(runtime, serviceName, apiServiceUrls: [string |
 - `serviceName`: Honeycomb application service name.
 - `apiServiceUrls`: A `RegExp` or `string` that matches the URLs of the application's backend services. If unsure, use the temporary regex `/.+/g,` to match all URLs.
 - `options`: An optional object literal of options:
-    - `endpoint`: An optional URL to an [OpenTelemetry collector](https://docs.honeycomb.io/send-data/opentelemetry/collector/). Either `endpoint` or `apiKey` option must be provided.
-    - `apiKey`: An optional Honeycomb ingestion [API key](https://docs.honeycomb.io/get-started/configure/environments/manage-api-keys/#create-api-key). Either `endpoint` or `apiKey` option must be provided.
-    - `instrumentations`: An optional array of [instrumentation](https://opentelemetry.io/docs/languages/js/instrumentation/) instances.
-    - `spanProcessors`: An optional array of [span processor](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution/#custom-span-processing) instances.
-    - `fetchInstrumentation`: An optional object literal accepting any [@opentelemetry/instrumentation-fetch](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch#fetch-instrumentation-options) options or `false` to disable instrumentation for [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
-    - `xmlHttpRequestInstrumentation`: An optional object literal accepting any [@opentelemetry/instrumentation-xml-http-request](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-xml-http-request#xhr-instrumentation-options) options. [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) instrumentation is disabled by default.
-    - `documentLoadInstrumentation`: An optional object literal accepting any [@opentelemetry/instrumentation-document-load](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/web/opentelemetry-instrumentation-document-load#document-load-instrumentation-options) options or `false` to disable instrumentation for [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
-    - `userInteractionInstrumentation`: An optional object literal accepting any [@opentelemetry/instrumentation-user-interaction](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/web/opentelemetry-instrumentation-user-interaction) options. User interactions instrumentation is disabled by default.
-    - `transformers`: An optional array of [configuration transformers](#configuration-transformers).
+    - Accepts most of the predefined options of the [registerHoneycombInstrumentation](https://gsoft-inc.github.io/wl-honeycomb-web/reference/registerhoneycombinstrumentation) function provided by `@workleap/honeycomb`.
     - `debug`: An optional `boolean` value indicating whether or not to log debug information to the console. `true` by default when the [runtime](../runtime/runtime-class.md) mode is set to `development`.
 
 ### Returns
 
 Nothing
 
-### Default instrumentation
+## Usage
 
-The `registerHoneycombInstrumentation` function registers the following OpenTelemetry instrumentations by default:
+### Register instrumentation
 
-- [@opentelemetry/instrumentation-fetch](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch)
-- [@opentelemetry/instrumentation-document-load](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/web/opentelemetry-instrumentation-document-load)
+```ts !#6-8
+import { FireflyRuntime } from "@squide/firefly";
+import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-For more details, refer to the [registerHoneycombInstrumentation.ts](https://github.com/gsoft-inc/wl-squide/blob/main/packages/firefly-honeycomb/src/registerHoneycombInstrumentation.ts) file on GitHub.
+const runtime = new FireflyRuntime();
 
-## Usage
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector"
+});
+```
 
-### Register instrumentation
+### Use an API key
+
+!!!warning
+Prefer 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.
+!!!
+
+```ts !#4
+import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
+
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    apiKey: "xyz123"
+});
+```
+
+### Customize backend URLs
+
+!!!warning
+Avoid using `/.+/g,` in production as it could expose customer data to third parties.
+!!!
+
+Specify values for the `apiServiceUrls` argument that matches your application's backend URLs. For example, if your backend services are hosted at `https://workleap.com/api`:
+
+```ts !#5
+import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
+
+registerHoneycombInstrumentation(
+    runtime, "squide-sample", 
+    [/https:\/\/workleap.com\/api\.*/], 
+    { endpoint: "https://squide-collector" }
+);
+```
+
+<!-- ### Register instrumentation
 
 ```ts
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector"
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector"
 });
 ```
 
@@ -64,12 +96,12 @@ Prefer using an [OpenTelemetry collector](https://docs.honeycomb.io/send-data/op
 ```ts !#4
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
     apiKey: "xyz123"
 });
-```
+``` -->
 
-### Customize backend URLs
+<!-- ### Customize backend URLs
 
 !!!warning
 Avoid using `/.+/g,` in production as it could expose customer data to third parties.
@@ -81,9 +113,9 @@ Specify values for the `apiServiceUrls` argument that matches your application's
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
 registerHoneycombInstrumentation(
-    runtime, "endpoints-sample", 
+    runtime, "squide-sample", 
     [/https:\/\/workleap.com\/api\.*/], 
-    { endpoint: "https://my-collector" }
+    { endpoint: "https://squide-collector" }
 );
 ```
 
@@ -93,8 +125,8 @@ registerHoneycombInstrumentation(
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 import { LongTaskInstrumentation } from "@opentelemetry/instrumentation-long-task";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     instrumentations: [
         new LongTaskInstrumentation()
     ]
@@ -127,8 +159,8 @@ export class CustomSpanProcessor implements SpanProcessor {
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 import { CustomSpanProcessor } from "./CustomSpanProcessor.ts";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     spanProcessors: [
         new CustomSpanProcessor()
     ]
@@ -142,8 +174,8 @@ To extend or replace the default [@opentelemetry/instrumentation-fetch](https://
 ```ts !#5-10
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     fetchInstrumentation: (defaultOptions) => {
         return {
             ...defaultOptions,
@@ -158,8 +190,8 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
 ```ts !#5
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     fetchInstrumentation: false
 });
 ```
@@ -171,8 +203,8 @@ To extend or replace the default [@opentelemetry/instrumentation-document-load](
 ```ts !#5-10
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     documentLoadInstrumentation: (defaultOptions) => {
         return {
             ...defaultOptions,
@@ -187,8 +219,8 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
 ```ts !#5
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     documentLoadInstrumentation: false
 });
 ```
@@ -200,8 +232,8 @@ By default, [@opentelemetry/instrumentation-xml-http-request](https://github.com
 ```ts !#5-10
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     xmlHttpRequestInstrumentation: (defaultOptions) => {
         return {
             ...defaultOptions,
@@ -218,8 +250,8 @@ By default, [@opentelemetryinstrumentation-user-interaction](https://github.com/
 ```ts !#5-10
 import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb";
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     userInteractionInstrumentation: (defaultOptions) => {
         return {
             ...defaultOptions,
@@ -254,8 +286,8 @@ const skipOptionsValidationTransformer: HoneycombSdkOptionsTransformer = config
     return config;
 }
 
-registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], {
-    endpoint: "https://my-collector",
+registerHoneycombInstrumentation(runtime, "squide-sample", [/.+/g,], {
+    endpoint: "https://squide-collector",
     transformers: [skipOptionsValidationTransformer]
 });
 ```
@@ -274,5 +306,5 @@ const skipOptionsValidationTransformer: HoneycombSdkOptionsTransformer = (config
 
     return config;
 }
-```
+``` -->
 

docs/reference/honeycomb/setGlobalSpanAttributes.md

@@ -7,6 +7,10 @@ toc:
 
 Set global attributes to be included in all Honeycomb Web traces.
 
+!!!info
+This function serves as a wrapper around the [@workleap/honeycomb](https://www.npmjs.com/package/@workleap/honeycomb) library. Before using it, read the documentation for the [setGlobalSpanAttributes](https://gsoft-inc.github.io/wl-honeycomb-web/reference/setglobalspanattributes/) function provided by `@workleap/honeycomb`.
+!!!
+
 ## Reference
 
 ```ts

packages/firefly-honeycomb/jest.config.ts

@@ -6,7 +6,7 @@ import { compilerOptions } from "./tsconfig.json";
 const config: Config = {
     testEnvironment: "jsdom",
     transformIgnorePatterns: [
-        "node_modules/(?!.pnpm|memoize|mimic-function)"
+        "node_modules/(?!.pnpm|memoize|mimic-function|@workleap/honeycomb)"
     ],
     transform: {
         "^.+\\.(js|ts|tsx)$": ["@swc/jest", swcConfig as Record<string, unknown>]

packages/firefly-honeycomb/package.json

@@ -36,11 +36,7 @@
         "@opentelemetry/auto-instrumentations-web": "*"
     },
     "devDependencies": {
-        "@opentelemetry/instrumentation": "*",
-        "@opentelemetry/instrumentation-document-load": "*",
         "@opentelemetry/instrumentation-fetch": "*",
-        "@opentelemetry/instrumentation-user-interaction": "*",
-        "@opentelemetry/instrumentation-xml-http-request": "*",
         "@opentelemetry/sdk-trace-web": "*",
         "@swc/core": "1.8.0",
         "@swc/jest": "0.2.37",
@@ -59,6 +55,7 @@
     },
     "dependencies": {
         "@squide/firefly": "workspace:*",
+        "@workleap/honeycomb": "1.0.0",
         "uuid": "11.0.2"
     },
     "sideEffects": false,

packages/firefly-honeycomb/src/activeSpan.ts

@@ -94,15 +94,41 @@ export function popActiveSpan(span: ActiveSpan) {
     }
 }
 
+// // This function should only be used by tests.
+// export function __setLocalModuleRegistry(registry: ModuleRegistry) {
+//     localModuleRegistry = registry as LocalModuleRegistry;
+// }
+
+// // This function should only be used by tests.
+// export function __clearLocalModuleRegistry() {
+//     localModuleRegistry = undefined;
+// }
+
+let mock: FetchCustomAttributeFunction | undefined;
+
+// This function should only be used by tests.
+export function __setActiveSpanMock(fct: FetchCustomAttributeFunction) {
+    mock = fct;
+}
+
+// This function should only be used by tests.
+export function __clearActiveSpanMock() {
+    mock = undefined;
+}
+
 export function createApplyCustomAttributesOnFetchSpanFunction(logger: RuntimeLogger) {
+    if (mock) {
+        return mock;
+    }
+
     const fct: FetchCustomAttributeFunction = (span, request, result) => {
         const activeSpan = getActiveSpan();
 
         if (activeSpan) {
             const context = activeSpan.instance.spanContext();
 
             if (context) {
-                logger.debug("[honeycomb] Found a context to apply to the following fetch request: ", context, request, result);
+                logger.debug("[squide] Found a Honeycomb context to apply to the following fetch request: ", context, request, result);
 
                 span.setAttribute("trace.trace_id", context.traceId);
                 span.setAttribute("trace.parent_id", context.spanId);