📝 [RUM-16097] Add migration skills for v4→v5 and v5→v6 SDK upgrades#4640
📝 [RUM-16097] Add migration skills for v4→v5 and v5→v6 SDK upgrades#4640mormubis wants to merge 5 commits into
Conversation
mormubis
force-pushed
the
adlrb/migration-skills-v4-v5-v5-v6
branch
from
0ace371 to
760725f
Compare
Bundles Sizes Evolution
🚀 CPU Performance
🧠 Memory Performance
|
🎉 All green!🧪 All tests passed 🎯 Code Coverage (details) 🔗 Commit SHA: cafcecc | Docs | Datadog PR Page | Give us feedback! |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 760725f96a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| | Option | Action | | ||
| | -------------------------------- | ---------------------------------------- | | ||
| | `sendLogsAfterSessionExpiration` | Delete. Logs are tied to sessions in v6. | |
There was a problem hiding this comment.
For projects that used sendLogsAfterSessionExpiration, this rationale is backwards: logs are not tied to active sessions after this migration. The SDK already sends logs without a session id when the session expires (see packages/logs/src/boot/startLogs.spec.ts:167), and the changelog notes that behavior was added in v5.19.0 before the v6 option removal. Leaving this as-is can cause the migration skill to incorrectly tell users that v6 drops post-expiration logs instead of simply removing the now-unneeded option.
Useful? React with 👍 / 👎.
mormubis
force-pushed
the
adlrb/migration-skills-v4-v5-v5-v6
branch
from
a9cdc3e to
7d3ae15
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: af32d7c51a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| Search: `grep -rn "forwardErrorsToLogs" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.html"` | ||
|
|
||
| **RUM source errors from caught exceptions**: In v6, `console.error(errorObject)` with `forwardErrorsToLogs: true` implicitly created both a Logs event and a RUM `error::source` event. In v7 these are decoupled — `console.error` only produces a Logs event. If the error is caught and never re-thrown, RUM never sees it. |
There was a problem hiding this comment.
In apps that initialize RUM, this v7 guidance is backwards: RUM still subscribes to buffered console.error entries and turns them into RUM errors (packages/core/src/domain/bufferedData.ts wires all console APIs, and packages/rum-core/src/domain/error/errorCollection.ts forwards BufferedDataType.CONSOLE with ConsoleApiName.error). Telling users that “RUM never sees it” and to add datadogRum.addError(err) for every caught exception logged with console.error can create duplicate RUM errors in exactly those catch-block scenarios.
Useful? React with 👍 / 👎.
| | Change | Impact | Action if needed | | ||
| | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `defaultPrivacyLevel` defaults to `"mask-user-input"` (was `"mask"`) | Less restrictive masking out of the box. Only user input is masked. | Set `defaultPrivacyLevel: "mask"` to preserve full masking. | | ||
| | `enablePrivacyForActionName` defaults to `true` | Action names are normalized: derived from DOM text and lowercased. `"Add to Cart"` in v6 becomes `"add to cart"` in v7. May also mask names based on privacy level. | Set `enablePrivacyForActionName: false` to preserve original casing and text. Use the [Datadog build plugin](https://github.com/DataDog/build-plugins) for annotation-based control. | |
There was a problem hiding this comment.
For v7 action names, I don’t see a lowercasing step in the inspected action-name path: getActionNameFromElement() returns attribute/text content after masking and whitespace normalization, and the current specs preserve casing such as Foo bar and Custom Action. This row will make migrations overreact for case-sensitive monitors by recommending enablePrivacyForActionName: false or lowercase query updates even when only the tree-walker/privacy behavior changed.
Useful? React with 👍 / 👎.
| | `datadoghq-browser-agent.com/us1/v4/datadog-logs.js` | `datadoghq-browser-agent.com/us1/v5/datadog-logs.js` | | ||
| | `datadoghq-browser-agent.com/us1/v4/datadog-rum-slim.js` | `datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js` | | ||
|
|
||
| Replace `us1` with your site: `eu1`, `us3`, `us5`, `ap1`, `ap2`. For US1-FED, the pattern is flat: `datadog-rum-v5.js` (no site prefix). |
There was a problem hiding this comment.
AP2 should not be offered as a v4→v5 CDN replacement site: the repository changelog only adds AP2 deployment/types in the v6 line, so following this instruction for an AP2 setup would generate /ap2/v5/... script URLs for a datacenter that v5 did not support. This is especially easy to hit because the same step tells users to mechanically replace us1 with one of the listed sites.
Useful? React with 👍 / 👎.
| 1. Update the wrapper so `startDurationVital` receives a `vitalKey` option and returns nothing. | ||
| 2. Find all callers that capture the wrapper's return value and update them to pass the vital name string directly to the stop call: |
There was a problem hiding this comment.
For wrappers that start multiple simultaneous durations with the same name, replacing the captured v6 reference with only the vital name loses the per-instance key. The v7 implementation keys active duration vitals by options.vitalKey ?? name and a second start for the same key replaces the first one, so this migration advice can cause overlapping timings such as parallel checkout_flow operations to overwrite each other instead of stopping independently. The wrapper migration should generate and pass a stable vitalKey for each instance, not just pass the name string to stop.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cafcecc76c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // v7 | ||
| DD_LOGS.init({ | ||
| forwardErrorsToLogs: true, // unchanged — still forwards unhandled errors | ||
| forwardConsoleLogs: ['error'], // new — restores console.error forwarding |
There was a problem hiding this comment.
When a v6 config already has forwardConsoleLogs set, for example to forward warn or info, copying this v7 example replaces the array with only ['error'] and stops forwarding the previously configured console levels. The surrounding guidance says to add error, so the example should preserve existing entries rather than demonstrate a replacement that drops them.
Useful? React with 👍 / 👎.
1 participant
Motivation
Benoit shipped the v6→v7 migration skill in #4486. We need equivalent skills for v4→v5 and v5→v6 so they can serve as the single source of truth for migration guides and feed the
hidden_promptsent tocode-gen-api.Changes
Two new skill files following the same structure as the existing v6→v7 skill. Content sourced from the official upgrade guide and the CHANGELOG, then cross-referenced to make sure nothing was missed.
Test instructions
These are markdown files consumed by AI coding assistants. No runtime behavior to test.
Checklist