{"id":11585,"library":"probe.gl","title":"probe.gl Instrumentation and Logging","description":"probe.gl is a robust collection of JavaScript tools designed for console-focused logging, performance instrumentation, benchmarking, and testing across both browser and Node.js environments. The current stable version is 3.6.0. It is developed and maintained as part of the vis.gl open-source visualization suite by Uber, indicating a steady release cadence tied to the evolution of their larger ecosystem. Key differentiators include its 'off by default' design to ensure a minimal performance footprint when not actively used, its lightweight nature, and features like persistent configuration through local storage. It enhances the debugging experience with capabilities such as defeating log cascades (to prevent console flooding) and providing direct source code links from console messages. The library offers a more advanced approach to application insights compared to basic `console.log`.","status":"active","version":"3.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/uber-web/probe.gl","tags":["javascript","profiling","instrumentation","logging","typescript"],"install":[{"cmd":"npm install probe.gl","lang":"bash","label":"npm"},{"cmd":"yarn add probe.gl","lang":"bash","label":"yarn"},{"cmd":"pnpm add probe.gl","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `Probe` object is exported as a default. It needs to be explicitly enabled to start logging and instrumentation activities.","wrong":"import { Probe } from 'probe.gl'; // Probe is a default export, not named.","symbol":"Probe","correct":"import Probe from 'probe.gl';"},{"note":"For dedicated logging functions beyond the methods available directly on the `Probe` instance, import them from the `@probe.gl/log` sub-package.","wrong":"import { log } from 'probe.gl'; // Specific logging utilities are in sub-modules.","symbol":"log","correct":"import { log } from '@probe.gl/log';"},{"note":"Classes like `Timer` for performance measurement and statistics collection are generally found in the `@probe.gl/stats` sub-package.","wrong":"import { Timer } from 'probe.gl'; // Performance classes are typically in sub-modules.","symbol":"Timer","correct":"import { Timer } from '@probe.gl/stats';"},{"note":"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.","symbol":"window.Probe (browser)","correct":"import Probe from 'probe.gl';\nwindow.Probe = Probe;"}],"quickstart":{"code":"import Probe from 'probe.gl';\nimport { log } from '@probe.gl/log';\nimport { Timer } from '@probe.gl/stats';\n\n// 1. Enable Probe and set logging level\n// Probe is 'off by default' to minimize performance impact.\nProbe.enable().setLevel(3); // Enable all features and verbose logging\nProbe.configure({ isPrintEnabled: true }); // Ensure messages are printed to console\n\nconsole.log('Probe.gl initialized. Check browser console for detailed logs.');\n\n// 2. Use basic logging utilities\nlog.log('Application started successfully.');\nlog.warn('A non-critical issue detected.', { code: 101, details: 'Example warning payload' });\nlog.error('Failed to load critical resource!', new Error('Resource not found'));\n\n// 3. Measure performance with a Timer\nconst myTimer = new Timer('ExpensiveOperation');\n\nfunction performExpensiveOperation() {\n  myTimer.start();\n  // Simulate some work\n  let sum = 0;\n  for (let i = 0; i < 1000000; i++) {\n    sum += Math.sqrt(i);\n  }\n  myTimer.end(); // Automatically logs duration if Probe is enabled\n  log.log(`Result of expensive operation: ${sum}`);\n}\n\nperformExpensiveOperation();\n\n// 4. Using the main Probe object for options\nif (Probe.getOption('myFeatureFlag')) {\n  log.log('Custom feature flag \\'myFeatureFlag\\' is enabled.');\n} else {\n  log.log('Custom feature flag \\'myFeatureFlag\\' is disabled, configuring it...');\n  Probe.configure({ myFeatureFlag: true });\n  log.log('Custom feature flag \\'myFeatureFlag\\' is now enabled for subsequent checks.');\n}\n","lang":"typescript","description":"Demonstrates enabling probe.gl, setting log levels, using logging utilities, and basic performance timing with a `Timer`."},"warnings":[{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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';`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import Probe from 'probe.gl';`. If exposing to window for debugging, add `window.Probe = Probe;`.","cause":"`Probe` was not imported correctly as a default export or was not aliased to `window.Probe` in the browser environment.","error":"TypeError: Probe.enable is not a function"},{"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.","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.","error":"Module not found: Can't resolve 'probe.gl'"},{"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.","cause":"The logging level might be too low, or `isPrintEnabled` is false, preventing output to the console.","error":"Logs are not appearing in the console, even after calling Probe.enable()"}],"ecosystem":"npm"}