@safaricom-mxl/web-sdk 0.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,119 @@
+# Contributor Code of Conduct
+
+## Our Pledge
+
+We as mmxlers, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+ServiceAvailability@Safaricom.co.ke. 
+
+All complaints will be reviewed and investigated promptly and fairly. 
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 2. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 3. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thank you for participating in this project!
+
+This document provides some basic guidelines for contributing to this repository. To propose improvements, feel free to
+submit a pull request or open an issue.
+
+## Requirements
+
+Before code can be accepted all contributors must read the [**code of conduct**](./CODE_OF_CONDUCT.md)
+and complete our Individual Contributor License Agreement (CLA).**](https://forms.gle/SjXadmUcVwh6NrU68)
+
+Our code of conduct applies to all platforms and venues related to this project; please follow it in all your
+interactions with the project and its participants.
+
+## Pull Requests
+
+If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request.
+
+When submitting code, please make every effort to follow existing conventions and style in order to keep the code as
+readable as possible.
+
+For more details on how to setup your environment and implement changes please see our [development guide](./DEVELOPING.md).
+
+## Reporting issues
+
+If you have any trouble to start contributing, please [contact us directly](mailto:ServiceAvailability@Safaricom.co.ke) or reach out in
+our [Community Slack](https://mxl.apps.ocpthikadev01.safaricom.net/community). Finally, feel free to open a [new issue](https://gitlab.safaricom.co.ke/mxl/apm/mxl-web-sdk/-/issues/new).

package/DATA_EXPORT.md

@@ -0,0 +1,29 @@
+# SDK Data Export
+
+## When is data sent?
+
+Telemetry data for Spans and Logs are exported from the SDK independently. Spans are sent as a batch whenever a session
+ends, this is managed by the [MXLSessionBatchedSpanProcessor](./src/processors/MXLSessionBatchedSpanProcessor/MXLSessionBatchedSpanProcessor.ts).
+Logs are also batched but can be sent throughout a session, this is managed by a [BatchLogRecordProcessor](https://github.com/open-telemetry/opentelemetry-js/blob/experimental/v0.57.0/experimental/packages/sdk-logs/src/platform/browser/export/BatchLogRecordProcessor.ts).
+
+## How is data sent?
+
+Data from the SDK is sent to MXL using a CORS HTTP POST request. The data is gzip compressed and encoded as
+[OTLP JSON Protobuf](https://opentelemetry.io/docs/specs/otlp/#json-protobuf-encoding). We make use of the
+[keepalive property](https://developer.mozilla.org/en-US/docs/Web/API/Request/keepalive) of the browser's Fetch API to
+help ensure the transmission of data even if the page has been closed. If possible we will attempt to retry request
+failures following an exponential backoff. See [FetchTransport](./src/transport/FetchTransport/FetchTransport.ts) and
+[RetryingTransport](src/transport/RetryingTransport/RetryingTransport.ts) for more details. 
+
+> [!NOTE]
+> The Fetch API's `keepalive` property is supported by all modern browsers, however it was a relatively recent addition
+> to Firefox and may not exist on some older versions of that browser in particular. Refer to this [Browser compatibility chart](https://developer.mozilla.org/en-US/docs/Web/API/Request/keepalive#browser_compatibility)
+> for more details.
+
+## What happens with custom export?
+
+If you [provide your own custom exporter](./README.md#custom-exporters) then batching of spans and logs are managed by a
+[BatchLogRecordProcessor](https://github.com/open-telemetry/opentelemetry-js/blob/experimental/v0.57.0/experimental/packages/sdk-logs/src/platform/browser/export/BatchLogRecordProcessor.ts)
+and [BatchSpanProcessor](https://github.com/open-telemetry/opentelemetry-js/blob/v1.30.0/packages/opentelemetry-sdk-trace-base/src/platform/browser/export/BatchSpanProcessor.ts)
+respectively.
+

package/DEVELOPING.md

@@ -0,0 +1,152 @@
+# Safaricom MXL Web SDK Development Guide
+
+## Setup
+
+```sh
+git clone https://gitlab.safaricom.co.ke/mxl/apm/mxl-web-sdk.git
+cd mxl-web-sdk
+npm install
+```
+
+## Development
+
+To start developing with automatic rebuilding and hot reloading:
+
+```sh
+npm run dev
+```
+
+This command will:
+
+- Automatically watch and rebuild the SDK when files change
+- Start the demo application with hot reloading enabled
+- Open your browser to `http://localhost:5173`
+
+## Repo Layout
+
+The code within `src/` is divided as follows:
+
+- `api-*/`
+  - High-level APIs that expose the SDK's functionality. By default these
+    interfaces are backed by no-op implementations so that instrumentations and
+    application code that rely on them continue to function in the absence of an
+    initialized SDK.
+- `managers/`
+  - Classes that provide concrete implementations of the interfaces defined in
+    `api-*/`
+- `exporters/`
+  - Serializes telemetry into payloads for sending data to MXL
+- `instrumentations/`
+  - Responsible for producing telemetry signals. Should be loosely coupled with
+    the SDK and only assume functionality provided by high-level APIs (which may
+    be no-ops if the SDK has not been initialized). Should allow themselves to
+    be turned off at any point.
+- `processors/`
+  - Hooks into the creation and finalization of telemetry signals in order to do
+    some additional processing. This can be appending attributes, batching
+    before sending to an exporter, applying limits, etc.
+- `resources/`
+  - Controls which attributes are included in the Resource object attached to
+    each payload.
+- `sdk/`
+  - Main entry point for initializing the SDK
+- `transport/`
+  - Low-level facilities for controlling the actual sending of data and
+    error-handling
+
+## Testing
+
+We use Mocha (test runner), Playwright (browser launcher), Chai (assertion
+library) and web-test-runner (general framework that ties everything else
+together).
+
+Run tests with:
+
+```sh
+npm run sdk:test
+```
+
+For debugging, you can run tests in a browser to set breakpoints, open the dev
+console, etc. with:
+
+```sh
+npm run sdk:test:manual
+```
+
+Manual mode as well as other debugging options can also be reached from watch
+mode:
+
+```sh
+npm run sdk:test:watch
+```
+
+## Integration Testing
+
+Run the integration tests and build all prerequisites with:
+
+```bash
+npm run sdk:compile
+npm run sdk:test:integration
+```
+
+To update golden files replace the last command with:
+
+```bash
+npm run sdk:test:integration:update-golden
+```
+
+## Publishing
+
+To release a new version of the SDK:
+
+1. Manually run the
+   [Bump packages version](https://gitlab.safaricom.co.ke/mxl/apm/mxl-web-sdk/-/pipelines)
+   action against the `main` branch
+2. Once the action completes a new PR containing the version bump and changelog
+   for the next version of the SDK will be created. Review and merge this PR.
+3. Once the PR is merged a new Github release will be created as a draft. Edit
+   the draft and publish it, this will trigger a publish of the updated SDK
+   packages to NPM.
+
+Note: the level of the version bump (major, minor, patch) is determined by the
+type of changes made to the SDK since the last release. You can see the
+requirements for each type of bump in our
+[release-drafter config -> autolabeler](./.github/release-drafter.yml)
+
+The release version will be generated based on the content of the pull requests
+merged since the last release. We use
+https://github.com/release-drafter/release-drafter to generate new releases and
+https://commitlint.js.org/ to make sure PRs follow our commit convention
+
+### Unpublishing
+
+If a mistake occurs during the publishing process you can remove a specific version from npm within 72 hours using
+
+```shell
+npm unpublish @safaricom-mxl/<package-name>@<version>
+```
+
+Or through their UI, see [Unpublishing a single version of a package](https://docs.npmjs.com/unpublishing-packages-from-the-registry#unpublishing-a-single-version-of-a-package)
+
+NOTE: We should only take this option in cases where there are security concerns since we want to consider release
+artifacts as immutable.
+
+### Deprecating
+
+If we find a critical issue in an already released version then we should mark that version as deprecated. This can be
+done using:
+
+```shell
+npm deprecate @safaricom-mxl/<package>@<version> "some message explaining deprecation"
+```
+
+Once a patch version has been released we should also purge jsdelivr's cache so that the CDN begins to serve the fixed
+version immediately. That can be done by supplying a list of URLs to purge in their [online tool](https://www.jsdelivr.com/tools/purge).
+
+If for example the deprecated version was `@safaricom-mxl/web-sdk@1.2.3` then we should supply a list for all its version
+aliases, e.g.:
+
+- https://cdn.jsdelivr.net/npm/@safaricom-mxl/web-sdk
+- https://cdn.jsdelivr.net/npm/@safaricom-mxl/web-sdk@latest
+- https://cdn.jsdelivr.net/npm/@safaricom-mxl/web-sdk@1
+- https://cdn.jsdelivr.net/npm/@safaricom-mxl/web-sdk@1.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/REACT.md

@@ -0,0 +1,143 @@
+# Instrumenting a React app with the MXL Web SDK
+
+You can use any of the MXL Web SDK features in your React application. However, we provide some additional automatic 
+instrumentation to make it easier to instrument some common React libraries and patterns.
+
+> [!TIP]
+> Make sure you call `initSDK` before your React App is mounted, this will ensure that the SDK is ready to capture traces and logs from the start of your app's lifecycle.
+
+## React Router
+
+To instrument React Router, add the React Router navigation instrumentation when you init the MXL Web SDK.
+
+```typescript
+import { initSDK } from '@safaricom-mxl/web-sdk';
+import { createReactRouterNavigationInstrumentation } from '@safaricom-mxl/web-sdk/react-instrumentation';
+
+initSDK({
+  // ...Other configs
+  instrumentations: [
+    createReactRouterNavigationInstrumentation(),
+  ],
+})
+```
+
+### React Router V4/V5
+
+If you're using React Router V4 or V5, you can use the `withMXLRoutingLegacy` higher-order component (HOC) to wrap your `Route` components. This will automatically track route changes. `MXLRoute` needs to be surrounded by a `<Switch>` component to properly capture the current path.
+
+```typescript jsx
+import { withMXLRoutingLegacy } from '@safaricom-mxl/web-sdk/react-instrumentation';
+import { Route, Router, Switch } from 'react-router-dom';
+
+const MXLRoute = withMXLRoutingLegacy(Route);
+
+const App = () => {
+  return (
+    <Router>
+      <Switch>
+        <MXLRoute path="/home" component={Home} />
+        <MXLRoute path="/about" component={About} />
+        <MXLRoute path="/contact" component={Contact} />
+      </Switch>
+    </Router>
+  );
+}
+```
+
+### React Router V6+ in declarative mode
+
+If you're using React Router V6 or later, you can use the `withMXLRouting` higher-order component (HOC) to wrap your `Routes` components. This will automatically track route changes. 
+
+```typescript jsx
+import { withMXLRouting } from '@safaricom-mxl/web-sdk/react-instrumentation';
+import { Route, Routes, BrowserRouter } from 'react-router-dom';
+
+const MXLRoutes = withMXLRouting(Routes);
+
+const App = () => {
+  return (
+    <BrowserRouter>
+      <MXLRoutes>
+        <Route path="/home" element={<Home />} />
+        <Route path="/about" element={<About />} />
+        <Route path="/contact" element={<Contact />} />
+      </MXLRoutes>
+    </BrowserRouter>
+  )
+}
+```
+
+### React Router V6+ in data mode
+
+When using data mode in React Router, you can listen to browser changes using `listenToRouterChanges` to automatically track route changes.
+
+```typescript jsx
+import { listenToRouterChanges } from '@safaricom-mxl/web-sdk/react-instrumentation';
+import {
+  createBrowserRouter,
+  RouterProvider,
+  matchRoutes,
+} from 'react-router-dom';
+import { useEffect } from 'react';
+
+const router = createBrowserRouter([
+  {
+    path: '/home',
+    element: <Home />,
+  },
+  {
+    path: '/about',
+    element: <About />,
+  },
+  {
+    path: '/contact',
+    element: <Contact />,
+  }
+]);
+
+const App = () => {
+  useEffect(() => {
+    // It's important that `listenToRouterChanges` is called on a useEffect so it starts tracking routes once the App is mounted.
+    // Otherwise some early telemetry can be missed if this gets initialized too early.
+    // Return the cleanup function to stop listening to route changes when the component unmount.
+    return listenToRouterChanges({
+      router,
+      // Use `matchRoutes` from React Router to match the current route.
+      routesMatcher: matchRoutes,
+    });
+    // Set an empty dependency array to run this effect only once.
+  }, []);
+
+  return (
+    <RouterProvider router={router} />
+  )
+}
+```
+
+### Configuration
+
+You can configure the React Router instrumentation by passing options to the `createReactRouterNavigationInstrumentation` function.
+For now, the only option available is `shouldCleanupPathOptionsFromRouteName`.
+If set to `true`, the instrumentation will remove path options from the route name, e.g. it will convert `/order/:orderState(pending|shipped|delivered)` to `/order/:orderState`.
+
+## Error Boundary
+
+To capture rendering errors in your React components, you can use the `MXLErrorBoundary` component. This component will automatically capture errors that on any of its children components render and send them to MXL.
+
+```typescript jsx
+import { MXLErrorBoundary } from '@safaricom-mxl/web-sdk/react-instrumentation';
+
+const App = () => {
+  return (
+    <MXLErrorBoundary fallback={() => <YourFallbackComponent />}>
+      <>
+        {/* Your app components go here */}
+        <Home />
+        <About />
+        <Contact />
+      </>
+    </MXLErrorBoundary>
+  );
+}
+```