probe.gl Instrumentation and Logging

Common errors

• TypeError: Probe.enable is not a function

  cause `Probe` was not imported correctly as a default export or was not aliased to `window.Probe` in the browser environment.
  fix Ensure you are using `import Probe from 'probe.gl';`. If exposing to window for debugging, add `window.Probe = Probe;`.

• Module not found: Can't resolve 'probe.gl'

  cause This typically indicates an issue with module resolution, often related to attempting to `require()` an ESM-only package in a CommonJS context or a misconfigured bundler.
  fix Verify your project's module resolution settings. For Node.js, ensure you're running in an ESM context (`'type': 'module'` in `package.json` or `.mjs` files). For bundlers, check `resolve` configurations.

• Logs are not appearing in the console, even after calling Probe.enable()

  cause The logging level might be too low, or `isPrintEnabled` is false, preventing output to the console.
  fix Ensure `Probe.setLevel(level)` is called with a sufficiently high level (e.g., `Probe.setLevel(3)` for verbose logs). Also, confirm `Probe.configure({ isPrintEnabled: true })` to allow console output. Check browser local storage for persistent probe.gl configurations that might override current settings.

Warnings

• gotcha probe.gl is 'off by default' to ensure a minimal performance footprint. If you don't explicitly call `Probe.enable()`, no logging or instrumentation will occur.
  Fix: Always call `Probe.enable()` early in your application's lifecycle, typically after import. You can also configure specific options via `Probe.configure()` and `Probe.setLevel()`.
• breaking As with many libraries transitioning in the JavaScript ecosystem, `probe.gl` (especially in major version 3.x) has likely solidified its move to ES Modules (ESM). Direct `require()` statements for CommonJS might lead to issues in modern setups, particularly in browser-first environments or Node.js projects configured for ESM.
  Fix: Prefer ES Module `import` syntax (`import Probe from 'probe.gl';`) for all modern JavaScript projects. Ensure your build system (Webpack, Rollup, Parcel) or Node.js environment is configured to handle ESM correctly.
• gotcha Configuration settings for `probe.gl` are persistent across browser sessions because they are stored in local storage. This can lead to unexpected behavior if you debug with certain settings and then forget to reset them.
  Fix: Be mindful of `Probe.configure()` and `Probe.enable()` calls. If debugging, consider a reset method (e.g., `localStorage.removeItem('probe.gl:config')` or a custom application setting) or explicitly setting desired options at application start.
• gotcha Specific utilities like `log` or `Timer` are often found in dedicated sub-packages (e.g., `@probe.gl/log`, `@probe.gl/stats`) rather than directly exported from the root `probe.gl` package. Importing from the root for these specific functions will result in `undefined` or module not found errors.
  Fix: Always check the documentation or the package structure for the correct import path for specific tools. Use `import { log } from '@probe.gl/log';` instead of `import { log } from 'probe.gl';`.

Install

• npm install probe.gl npm
• yarn add probe.gl yarn
• pnpm add probe.gl pnpm

Imports

• Probe
  wrong:

  import { Probe } from 'probe.gl'; // Probe is a default export, not named.

  correct:

  import Probe from 'probe.gl';

  The primary `Probe` object is exported as a default. It needs to be explicitly enabled to start logging and instrumentation activities.
• log
  wrong:

  import { log } from 'probe.gl'; // Specific logging utilities are in sub-modules.

  correct:

  import { log } from '@probe.gl/log';

  For dedicated logging functions beyond the methods available directly on the `Probe` instance, import them from the `@probe.gl/log` sub-package.
• Timer
  wrong:

  import { Timer } from 'probe.gl'; // Performance classes are typically in sub-modules.

  correct:

  import { Timer } from '@probe.gl/stats';

  Classes like `Timer` for performance measurement and statistics collection are generally found in the `@probe.gl/stats` sub-package.
• window.Probe (browser)

  import Probe from 'probe.gl';
  window.Probe = Probe;

  In browser environments, it's a common pattern to expose the `Probe` instance globally (e.g., to `window.Probe`) for easier access during debugging in the developer console.

Quickstart

Demonstrates enabling probe.gl, setting log levels, using logging utilities, and basic performance timing with a `Timer`.

import Probe from 'probe.gl';
import { log } from '@probe.gl/log';
import { Timer } from '@probe.gl/stats';

// 1. Enable Probe and set logging level
// Probe is 'off by default' to minimize performance impact.
Probe.enable().setLevel(3); // Enable all features and verbose logging
Probe.configure({ isPrintEnabled: true }); // Ensure messages are printed to console

console.log('Probe.gl initialized. Check browser console for detailed logs.');

// 2. Use basic logging utilities
log.log('Application started successfully.');
log.warn('A non-critical issue detected.', { code: 101, details: 'Example warning payload' });
log.error('Failed to load critical resource!', new Error('Resource not found'));

// 3. Measure performance with a Timer
const myTimer = new Timer('ExpensiveOperation');

function performExpensiveOperation() {
  myTimer.start();
  // Simulate some work
  let sum = 0;
  for (let i = 0; i < 1000000; i++) {
    sum += Math.sqrt(i);
  }
  myTimer.end(); // Automatically logs duration if Probe is enabled
  log.log(`Result of expensive operation: ${sum}`);
}

performExpensiveOperation();

// 4. Using the main Probe object for options
if (Probe.getOption('myFeatureFlag')) {
  log.log('Custom feature flag \'myFeatureFlag\' is enabled.');
} else {
  log.log('Custom feature flag \'myFeatureFlag\' is disabled, configuring it...');
  Probe.configure({ myFeatureFlag: true });
  log.log('Custom feature flag \'myFeatureFlag\' is now enabled for subsequent checks.');
}