@algolia/algolia-browser-telemetry

Algolia Telemetry

• Fast - Designed with minimal performance overhead in mind. Tested
• Small - 3.5KB (minified and gzipped) library. Size Limit controls the size.

Browser Support

IE / Edge	Firefox	Chrome	Safari
IE11, Edge	✅	✅	✅

The Telemetry module progressively enhances Algolia's search client. In unsupported environments, it gracefully fallbacks to not adding any instrumentation without impacting the search client itself.

The project is Algolia's effort towards providing our users with security about their search implementation by collecting anonymous telemetry data and giving application owners the necessary monitoring platform so that they can effectively monitor and optimize their search performance. The collected data is in no way personally identifiable or shared with anyone outside of Algolia. In other words, this is not a tracking tool, nor will it ever become one. For a full explanation on what data is collected and what purpose it serves see https://telemetry.algolia.com, where you'll also be able to opt out of telemetry.

Contents

• Browser support
• Usage
  • Basic Example
  • Multiple clients
  • Async Example
• Motivation
  • Customer Benefits
  • Module design

Usage:

To monitor both the errors and telemetry information, the module needs to be initialized at search client initialization time and should only be called once, even when initializing multiple search clients. That is because the module creates side-effects such as creating performance observers and event listeners that allow for data to be reported at convenient times.

Basic use-case:

import algoliasearch from 'algoliasearch'
import createBrowserTelemetry from '@algolia/algolia-browser-telemetry'

const telemetry = createBrowserTelemetry({
  telemetryQueueCapacity?: number, // Optional, default is 12
  errorQueueCapacity?: number, // Optional, default is 4 or 1 full retry cycle
  requester?: Requester, // Optional, default is @algolia/requester-browser-xhr
  reporter?: Reporter, // Optional, use to report data to a custom endpoint - default is algolia's
  applications?: string[] // Optional, indicate which applications are used in the telemetry context
})

const client = algoliasearch(APPLICATION_ID, API_KEY, {
  requester: telemetry
})

// If search UI is conditionally mounted on the page or if the application is as SPA application (like React),
// the cleanup should be taken care of in the useEffect hook.
React.useEffect(() => {
  return () => telemetry.destroy()
}, [telemetry])

Multiple search clients

import algoliasearch from 'algoliasearch'
import createBrowserTelemetry from '@algolia/algolia-browser-telemetry'

const telemetryRequester = createBrowserTelemetry()

const client = algoliasearch(APPLICATION_ID, API_KEY, {
  requester: telemetryRequester
})
const other_client = algoliasearch(APPLICATION_ID, API_KEY, {
  requester: telemetryRequester
})

Async example

⚠️ By loading the module async and detaching it from algoliasearch initialization, you will lose the ability to monitor errors.

If you are worried about adding too much JavaScript to your page or you only care about collecting telemetry information, then the telemetry module will support that use-case too. Once you lazy-load the module, you can instantiate it on the page and it will collect only the telemetry data.

But first, please reconsider; error reporting can have a lot of value, telling you how/when the search was broken or down, if there are users from specific regions that cannot access your service or if you are creating malformed engine params, causing 402 errors... If not, then the following can be achieved by the following pseudo-code example

const telemetry = lazyLoad('@algolia/algolia-browser-telemetry')
  .then(createBrowserTelemetry => createBrowserTelemetry())

Motivation

Similar to many other companies, our service runs on the internet and although we do monitor and probe our server infrastructure, it only gives us a partial view of how our users are experiencing search. The telemetry data will enable us to improve our service on a global scale, prioritize feature development, namely the adoption of new HTTP protocols like QUIC and evaluating the impact of new middlewares (load balancer, caches) to the end-user search experience.

The telemetry module collects information such as latency, response size, and DNS timings as well as reports API errors that the search engine might return so that we can detect downtimes which might not be strictly related to Algolia's infrastructure such as wrongly deleted API keys, bad request parameters, etc...

Customer benefits

We will be exposing some of the metrics that we will be computing from your telemetry data, starting with latency, response size, and the potential errors coming from the engine. We must give you the ability to visualize how your search speed evolves as you make updates to your Algolia index. Our engine is fast by default, but certain configurations and indexing strategies can lead to poor end-user performance, the typical example would be very large record sizes or fetching 1000 hits on page load if there might only 10 be needed. We believe this will encourage users to fine tune settings like hitsPerPage or attributesNotToRetrieve in order to minimize the engine response sizes and create adaptive search experiences.

Telemetry Module design

The telemetry module is built with minimal performance overhead in mind, we worked hard and designed the module in a way where it still reliably collects telemetry data without compromising performance. The module collects data outside of the "critical code path" by using performance observers and queues which process data outside of the main event loop. The module leverages browser micro tasks and requestIdleCallback to collect data - it's design was inspired by the idle-until-urgent pattern.

Example call stack execution: