diff --git a/docs/reference/honeycomb/registerHoneycombInstrumentation.md b/docs/reference/honeycomb/registerHoneycombInstrumentation.md index d3d15ca20..525267429 100644 --- a/docs/reference/honeycomb/registerHoneycombInstrumentation.md +++ b/docs/reference/honeycomb/registerHoneycombInstrumentation.md @@ -21,7 +21,6 @@ registerHoneycombInstrumentation(runtime, serviceName, apiServiceUrls: [string | - `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. - - `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`. - `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). @@ -29,6 +28,7 @@ registerHoneycombInstrumentation(runtime, serviceName, apiServiceUrls: [string | - `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). + - `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 @@ -57,7 +57,7 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { ### Use an API key -!!!info +!!!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. !!! @@ -71,7 +71,11 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { ### Customize backend URLs -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 +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"; @@ -136,16 +140,16 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { To extend or replace the default [@opentelemetry/instrumentation-fetch](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch) options, provide a function that returns an object literal with the desired options. This function will receive an object literal containing the default options, which you can either extend or replace. ```ts !#5-10 -import { registerHoneycombInstrumentation, defaultDefineFetchInstrumentationOptions } from "@squide/firefly-honeycomb"; +import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb"; registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { endpoint: "https://my-collector", - fetchInstrumentation: defaultDefineFetchInstrumentationOptions(defaultOptions => { + fetchInstrumentation: (defaultOptions) => { return { ...defaultOptions, ignoreNetworkEvents: false } - }) + } }); ``` @@ -165,16 +169,16 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { To extend or replace the default [@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, provide a function that returns an object literal with the desired options. This function will receive an object literal containing the default options, which you can either extend or replace. ```ts !#5-10 -import { registerHoneycombInstrumentation, defaultDefineDocumentLoadInstrumentationOptions } from "@squide/firefly-honeycomb"; +import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb"; registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { endpoint: "https://my-collector", - documentLoadInstrumentation: (defaultOptions => { + documentLoadInstrumentation: (defaultOptions) => { return { ...defaultOptions, ignoreNetworkEvents: false } - }) + } }); ``` @@ -198,12 +202,12 @@ import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb"; registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { endpoint: "https://my-collector", - xmlHttpRequestInstrumentation: (defaultOptions => { + xmlHttpRequestInstrumentation: (defaultOptions) => { return { ...defaultOptions, ignoreNetworkEvents: false } - }) + } }); ``` @@ -216,12 +220,12 @@ import { registerHoneycombInstrumentation } from "@squide/firefly-honeycomb"; registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { endpoint: "https://my-collector", - userInteractionInstrumentation: (defaultOptions => { + userInteractionInstrumentation: (defaultOptions) => { return { ...defaultOptions, eventNames: ["submit", "click", "keypress"] } - }) + } }); ``` @@ -231,7 +235,7 @@ registerHoneycombInstrumentation(runtime, "endpoints-sample", [/.+/g,], { We do not guarantee that your configuration transformers won't break after an update. It's your responsibility to keep them up to date with new releases. !!! -The [predefined options](#parameters) are useful to quickly customize the [default configuration](https://github.com/gsoft-inc/wl-web-configs/blob/main/packages/webpack-configs/src/dev.ts) of the [Honeycomb Web SDK](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution), but only covers a subset of the [options](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution/#advanced-configuration). If you need full control over the configuration, you can provide configuration transformer functions through the `transformers` option of the `registerHoneycombInstrumentation` function. Remember, **no locked in** :heart::v:. +The [predefined options](#parameters) are useful to quickly customize the default configuration of the [Honeycomb Web SDK](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution), but only covers a subset of the [options](https://docs.honeycomb.io/send-data/javascript-browser/honeycomb-distribution/#advanced-configuration). If you need full control over the configuration, you can provide configuration transformer functions through the `transformers` option of the `registerHoneycombInstrumentation` function. Remember, **no locked in** :heart::v:. To view the default configuration of `registerHoneycombInstrumentation`, have a look at the [registerHoneycombInstrumentation.ts](https://github.com/gsoft-inc/wl-squide/blob/main/packages/firefly-honeycomb/src/registerHoneycombInstrumentation.ts) file on GitHub.