diff --git a/README.md b/README.md index 21b9eefba..829cf5c13 100644 --- a/README.md +++ b/README.md @@ -350,7 +350,7 @@ This is used to identify the build in logs, metrics and spans. > default: `null` The service of the deployed application, as set in the Datadog browser SDKs.
-This is the canonical place to declare the service once. Plugins that need a service (Live Debugger's symbol table upload, RUM source code context, source map upload, etc.) read it from here unless they're given a more specific override. +This is the canonical place to declare the service once. Plugins that need a service (Live Debugger's symbol upload, RUM source code context, source map upload, etc.) read it from here unless they're given a more specific override. ### `metadata.version` > default: `null` diff --git a/packages/plugins/live-debugger/CONTRIBUTING.md b/packages/plugins/live-debugger/CONTRIBUTING.md index 86a033ba9..e4df8a839 100644 --- a/packages/plugins/live-debugger/CONTRIBUTING.md +++ b/packages/plugins/live-debugger/CONTRIBUTING.md @@ -6,7 +6,7 @@ Developer notes for the Live Debugger plugin. - [Development workflow](#development-workflow) -- [Symbol table](#symbol-table) +- [Symbols](#symbols) - [Consumer build canary](#consumer-build-canary) - [Fresh checkouts and CI](#fresh-checkouts-and-ci) - [Excalidraw target](#excalidraw-target) @@ -45,27 +45,27 @@ Generated code should keep the dormant runtime path small: call `$dd_probes(func When adding or changing `liveDebugger` configuration, update [`src/types.ts`](./src/types.ts), [`src/validate.ts`](./src/validate.ts), [`src/validate.test.ts`](./src/validate.test.ts), and the consumer-facing [`README.md`](./README.md). -## Symbol table +## Symbols -The plugin lists the instrumented functions that ship in a build and uploads them to Datadog's Symbol Database. Each entry has the function ID, a display name, the path relative to the git repository root, and the original line range. The code lives in [`src/symbol-table`](./src/symbol-table). +The plugin collects the symbols of the instrumented functions that ship in a build and uploads them to Datadog's Symbol Database. Each function has its ID, a display name, the path relative to the git repository root, and the original line range. The code lives in [`src/symbol-table`](./src/symbol-table). -The upload is on by default, and the README lists [what it needs](./README.md#symbol-upload). When it can't happen, the table isn't generated either, so the build does no extra work. To inspect the table, set `DD_LIVE_DEBUGGER_SYMBOL_TABLE_PATH` to a file path: the plugin then also writes the table there, in the format of the upload's file part. +The upload is on by default, and the README lists [what it needs](./README.md#symbol-upload). When it can't happen, the symbols aren't collected either, so the build does no extra work. To inspect the symbols, set `DD_LIVE_DEBUGGER_SYMBOLS_PATH` to a file path: the plugin then also writes them there, in the format of the upload's file part. ```bash -DD_LIVE_DEBUGGER_SYMBOL_TABLE_PATH=/tmp/symbol-table.json yarn build +DD_LIVE_DEBUGGER_SYMBOLS_PATH=/tmp/live-debugger-symbols.json yarn build ``` -The dump is never written inside the bundler's output directory, and neither generation nor upload ever fails the build: problems are logged as warnings. +The dump is never written inside the bundler's output directory, and neither collecting nor uploading the symbols ever fails the build: problems are logged as warnings. How it works: - After a one-off build, outside watch mode and dev servers, the plugin scans the text of every emitted JavaScript chunk, without parsing it. It doesn't use the transform hook, which doesn't run for modules restored from a persistent cache and doesn't know which functions tree-shaking removes. - Every instrumented function has exactly one `$dd_probes('')` call at the start of its body and one `$dd_throw(` call at its end. The scan pairs them like brackets, which also gives each function's parent. - The transform anchors the `$dd_probes` call to the original body's opening brace, which gives the start line through the chunk's final source map. The end line is the last mapped position up to the `$dd_throw` call: for block bodies that's the closing brace. The code appended after an arrow function's expression body has no mapping, and minifiers leave some tokens unmapped, so the closest mapped token before it is used instead. -- The path and display name come from the function ID. Query strings are removed, Yarn PnP virtual paths and symlinks are resolved, and the path is made relative to the git root. Without a git repository, the table is skipped. +- The path and display name come from the function ID. Query strings are removed, Yarn PnP virtual paths and symlinks are resolved, and the path is made relative to the git root. Without a git repository, no symbols are collected. - Each chunk's debug ID is read from the runtime bootstrap, when debug IDs are enabled, to record which chunks contain each file. -When changing instrumentation output, keep exactly one `$dd_probes` call at the start and one `$dd_throw` call at the end of every instrumented function, anchored to the body's braces. [`src/symbolTable.integration.test.ts`](./src/symbolTable.integration.test.ts) checks the table on every bundler. +When changing instrumentation output, keep exactly one `$dd_probes` call at the start and one `$dd_throw` call at the end of every instrumented function, anchored to the body's braces. [`src/symbolTable.integration.test.ts`](./src/symbolTable.integration.test.ts) checks the symbols on every bundler. Known limitations: diff --git a/packages/plugins/live-debugger/src/constants.ts b/packages/plugins/live-debugger/src/constants.ts index 1f4c2a854..aa3151df9 100644 --- a/packages/plugins/live-debugger/src/constants.ts +++ b/packages/plugins/live-debugger/src/constants.ts @@ -20,7 +20,7 @@ export const FUNCTION_ID_SEPARATOR = ';'; export const ANONYMOUS_FUNCTION_NAME = ''; // Path where an opt-in debug dump of the symbol table is written. -export const SYMBOL_TABLE_PATH_ENV = 'DD_LIVE_DEBUGGER_SYMBOL_TABLE_PATH'; +export const SYMBOL_TABLE_PATH_ENV = 'DD_LIVE_DEBUGGER_SYMBOLS_PATH'; // Intake that the symbol table is uploaded to. export const SYMBOL_TABLE_INTAKE_SUBDOMAIN = 'debugger-intake'; diff --git a/packages/plugins/live-debugger/src/symbol-table/index.ts b/packages/plugins/live-debugger/src/symbol-table/index.ts index d4c99da0a..1f86a3f1d 100644 --- a/packages/plugins/live-debugger/src/symbol-table/index.ts +++ b/packages/plugins/live-debugger/src/symbol-table/index.ts @@ -201,7 +201,7 @@ export const getSymbolTableHooks = ( return; } - const timer = log.time('upload symbol table'); + const timer = log.time('upload symbols'); try { await uploadSymbolTable( payload, @@ -229,7 +229,7 @@ export const getSymbolTableHooks = ( // Wait for the injection plugin to finish rewriting esbuild's output. await context.artifactsReady; - const timer = log.time('generate symbol table'); + const timer = log.time('collect symbols'); let table: SymbolTable | undefined; let payload: SymbolTablePayload | undefined; try { diff --git a/packages/plugins/live-debugger/src/symbol-table/upload.ts b/packages/plugins/live-debugger/src/symbol-table/upload.ts index 02e32e1d8..4d79e4fdc 100644 --- a/packages/plugins/live-debugger/src/symbol-table/upload.ts +++ b/packages/plugins/live-debugger/src/symbol-table/upload.ts @@ -209,7 +209,7 @@ export const uploadSymbolTable = async ( getData: () => getPartData(part, context, payload, uploadId), onRetry: (error, attempt) => { log.debug( - `Retrying the upload of symbol table part ${part.batchNum} (attempt ${attempt}): ${error.message}`, + `Retrying part ${part.batchNum} of the symbol upload (attempt ${attempt}): ${error.message}`, ); }, });