Merge branch 'develop' into manual-develop-sync

Author: andreiborza

.cursor/rules/adding-a-new-ai-integration.mdc

@@ -25,6 +25,32 @@ Multi-runtime considerations:
 - Edge (Cloudflare/Vercel): No OTel, processors only or manual wrapping
 ```
 
+**IMPORTANT - Runtime-Specific Placement:**
+
+If an AI SDK only works in a specific runtime, the integration code should live exclusively in that runtime's package. Do NOT add it to `packages/core/` or attempt to make it work in other runtimes where it cannot function.
+
+**Runtime-specific integration structures:**
+
+**Node.js-only SDKs** → `packages/node/`
+
+- Core logic: `packages/node/src/integrations/tracing/{provider}/index.ts`
+- OTel instrumentation: `packages/node/src/integrations/tracing/{provider}/instrumentation.ts`
+- Use when SDK only work with Node.js-specific APIs
+
+**Cloudflare Workers-only SDKs** → `packages/cloudflare/`
+
+- Single file: `packages/cloudflare/src/integrations/tracing/{provider}.ts`
+- Use when SDK only works with Cloudflare Workers APIs or Cloudflare AI
+
+**Browser-only SDKs** → `packages/browser/`
+
+- Core logic: `packages/browser/src/integrations/tracing/{provider}/index.ts`
+- Use when SDK requires browser-specific APIs (DOM, WebAPIs, etc.)
+
+**For all runtime-specific SDKs:** DO NOT create `packages/core/src/tracing/{provider}/` - keep everything in the runtime package.
+
+**Multi-runtime SDKs:** If the SDK works across multiple runtimes (Node.js, browser, edge), follow the standard pattern with shared core logic in `packages/core/` and runtime-specific wrappers/instrumentation in each package where needed.
+
 ---
 
 ## Span Hierarchy
@@ -139,6 +165,10 @@ OpenTelemetry Semantic Convention attribute names. **Always use these constants!
 - `GEN_AI_USAGE_INPUT_TOKENS_ATTRIBUTE` - Token counts
 - `GEN_AI_OPERATION_NAME_ATTRIBUTE` - 'chat', 'embeddings', etc.
 
+**CRITICAL - Attribute Usage:**
+
+Only use attributes explicitly listed in the [Sentry Gen AI Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/). Do NOT create custom attributes or use undocumented ones. If you need a new attribute, it MUST be documented in the conventions first before implementation.
+
 ### `utils.ts`
 
 - `setTokenUsageAttributes()` - Set token usage on span
@@ -213,6 +243,8 @@ OpenTelemetry Semantic Convention attribute names. **Always use these constants!
 
 ## Auto-Instrumentation (Out-of-the-Box Support)
 
+**MANDATORY**
+
 **RULE:** AI SDKs should be auto-enabled in Node.js runtime if possible.
 
 ✅ **Auto-enable if:**
@@ -269,12 +301,26 @@ export type { {Provider}Options } from './integrations/tracing/{provider}';
 export { {provider}Integration } from './integrations/tracing/{provider}';
 ```
 
-**4. Add E2E test** in `packages/node-integration-tests/suites/{provider}/`
+**4. Add E2E tests**
+
+For Node.js integrations, add tests in `dev-packages/node-integration-tests/suites/tracing/{provider}/`:
 
 - Verify spans created automatically (no manual setup)
 - Test `recordInputs` and `recordOutputs` options
 - Test integration can be disabled
 
+For Cloudflare Workers integrations, add tests in `dev-packages/cloudflare-integration-tests/suites/tracing/{provider}`:
+
+- Create a new worker test app with the AI SDK
+- Verify manual instrumentation creates spans correctly
+- Test in actual Cloudflare Workers runtime (use `wrangler dev` or `miniflare`)
+
+For Browser integrations, add tests in `dev-packages/browser-integration-tests/suites/tracing/ai-providers/{provider}/`:
+
+- Create a new test suite with Playwright
+- Verify manual instrumentation creates spans correctly in the browser
+- Test with actual browser runtime
+
 ---
 
 ## Directory Structure
@@ -307,15 +353,17 @@ packages/
 
 ## Key Best Practices
 
-1. **Respect `sendDefaultPii`** for recordInputs/recordOutputs
-2. **Use semantic attributes** from `gen-ai-attributes.ts` (never hardcode)
-3. **Set Sentry origin**: `SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN = 'auto.ai.openai'` (use provider name: `openai`, `anthropic`, `vercelai`, etc. - only alphanumerics, `_`, and `.` allowed)
-4. **Truncate large data**: Use helper functions from `utils.ts`
-5. **Correct span operations**: `gen_ai.invoke_agent` for parent, `gen_ai.chat` for children
-6. **Streaming**: Use `startSpanManual()`, accumulate state, call `span.end()`
-7. **Token accumulation**: Direct on child spans, accumulate on parent from children
-8. **Performance**: Use `callWhenPatched()` for Pattern 1
-9. **LangChain**: Check `_INTERNAL_shouldSkipAiProviderWrapping()` in Pattern 2
+1. **Auto-instrumentation is mandatory** - All integrations MUST auto-detect and instrument automatically in Node.js runtime
+2. **Runtime-specific placement** - If SDK only works in one runtime, code lives only in that package
+3. **Respect `sendDefaultPii`** for recordInputs/recordOutputs
+4. **Use semantic attributes** from `gen-ai-attributes.ts` (never hardcode) - Only use attributes from [Sentry Gen AI Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/)
+5. **Set Sentry origin**: `SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN = 'auto.ai.openai'` (use provider name: `openai`, `anthropic`, `vercelai`, etc. - only alphanumerics, `_`, and `.` allowed)
+6. **Truncate large data**: Use helper functions from `utils.ts`
+7. **Correct span operations**: `gen_ai.invoke_agent` for parent, `gen_ai.chat` for children
+8. **Streaming**: Use `startSpanManual()`, accumulate state, call `span.end()`
+9. **Token accumulation**: Direct on child spans, accumulate on parent from children
+10. **Performance**: Use `callWhenPatched()` for Pattern 1
+11. **LangChain**: Check `_INTERNAL_shouldSkipAiProviderWrapping()` in Pattern 2
 
 ---
 
@@ -329,16 +377,20 @@ packages/
 
 ## Auto-Instrumentation Checklist
 
-- [ ] Added to `getAutoPerformanceIntegrations()` in correct order
-- [ ] Added to `getOpenTelemetryInstrumentationToPreload()`
-- [ ] Exported from `packages/node/src/index.ts`
-- [ ] **If browser-compatible:** Exported from `packages/browser/src/index.ts`
-- [ ] Added E2E test in `packages/node-integration-tests/suites/{provider}/`
-- [ ] E2E test verifies auto-instrumentation
+- [ ] If runtime-specific, placed code only in that runtime's package
+- [ ] Added to `getAutoPerformanceIntegrations()` in correct order (Node.js)
+- [ ] Added to `getOpenTelemetryInstrumentationToPreload()` (Node.js with OTel)
+- [ ] Exported from appropriate package index (`packages/node/src/index.ts`, `packages/cloudflare/src/index.ts`, etc.)
+- [ ] Added E2E tests:
+  - [ ] Node.js: `dev-packages/node-integration-tests/suites/tracing/{provider}/`
+  - [ ] Cloudflare: `dev-packages/cloudflare-integration-tests/suites/tracing/{provider}/`
+  - [ ] Browser: `dev-packages/browser-integration-tests/suites/tracing/ai-providers/{provider}/`
+- [ ] E2E test verifies auto-instrumentation (no manual setup required)
+- [ ] Only used attributes from [Sentry Gen AI Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/)
 - [ ] JSDoc says "enabled by default" or "not enabled by default"
 - [ ] Documented how to disable (if auto-enabled)
 - [ ] Documented limitations clearly
-- [ ] Verified OTel only patches when package imported
+- [ ] Verified OTel only patches when package imported (Node.js)
 
 ---
 

.cursor/rules/sdk_development.mdc

@@ -34,6 +34,8 @@ You are working on the Sentry JavaScript SDK, a critical production SDK used by
 
 - `yarn lint` - Run ESLint and Prettier checks
 - `yarn fix` - Auto-fix linting and formatting issues
+- `yarn format:check` - Check file formatting only
+- `yarn format` - Auto-fix formatting issues
 - `yarn lint:es-compatibility` - Check ES compatibility
 
 ## Git Flow Branching Strategy

.editorconfig

@@ -8,4 +8,4 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 [*.md]
-trim_trailing_whitespace = false
+trim_trailing_whitespace = false

.github/workflows/build.yml

@@ -339,7 +339,7 @@ jobs:
         id: install_dependencies
 
       - name: Check file formatting
-        run: yarn lint:prettier
+        run: yarn format:check
 
   job_circular_dep_check:
     name: Circular Dependency Check
@@ -987,7 +987,7 @@ jobs:
         with:
           node-version-file: 'dev-packages/e2e-tests/test-applications/${{ matrix.test-application }}/package.json'
       - name: Set up Bun
-        if: matrix.test-application == 'node-exports-test-app'
+        if: contains(fromJSON('["node-exports-test-app","nextjs-16-bun"]'), matrix.test-application)
         uses: oven-sh/setup-bun@v2
       - name: Set up AWS SAM
         if: matrix.test-application == 'aws-serverless'

.oxfmtrc.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "arrowParens": "avoid",
+  "printWidth": 120,
+  "proseWrap": "always",
+  "singleQuote": true,
+  "trailingComma": "all",
+  "experimentalSortPackageJson": false,
+  "ignorePatterns": [
+    "packages/browser/test/loader.js",
+    "packages/replay-worker/examples/worker.min.js",
+    "dev-packages/browser-integration-tests/fixtures",
+    "**/test.ts-snapshots/**",
+    "/.nx/cache",
+    "/.nx/workspace-data",
+    "dev-packages/**/*.html",
+    "dev-packages/**/*.hbs",
+    "packages/ember/**/*.hbs",
+    "packages/ember/**/*.html"
+  ],
+  "overrides": [
+    {
+      "files": ["*.md", "*.mdc"],
+      "options": {
+        "proseWrap": "preserve"
+      }
+    }
+  ]
+}

.prettierignore

@@ -2,7 +2,7 @@
   // See http://go.microsoft.com/fwlink/?LinkId=827846
   // for the documentation about the extensions.json format
   "recommendations": [
-    "esbenp.prettier-vscode",
+    "oxc.oxc-vscode",
     "dbaeumer.vscode-eslint",
     "augustocdias.tasks-shell-input",
     "denoland.vscode-deno"

.vscode/extensions.json

@@ -11,10 +11,10 @@
   },
   "typescript.tsdk": "./node_modules/typescript/lib",
   "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "oxc.oxc-vscode"
   },
   "[css]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "oxc.oxc-vscode"
   },
   "yaml.schemas": {
     "https://json.schemastore.org/github-workflow.json": ".github/workflows/**.yml"
@@ -25,8 +25,8 @@
     }
   ],
   "deno.enablePaths": ["packages/deno/test"],
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.defaultFormatter": "oxc.oxc-vscode",
   "[typescript]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "oxc.oxc-vscode"
   }
 }

.vscode/settings.json

@@ -31,8 +31,10 @@ You are working on the Sentry JavaScript SDK, a critical production SDK used by
 
 ### Linting and Formatting
 
-- `yarn lint` - Run ESLint and Prettier checks
+- `yarn lint` - Run ESLint and Oxfmt checks
 - `yarn fix` - Auto-fix linting and formatting issues
+- `yarn format:check` - Check file formatting only
+- `yarn format` - Auto-fix formatting issues
 - `yarn lint:es-compatibility` - Check ES compatibility
 
 ## Git Flow Branching Strategy

CLAUDE.md

@@ -12,7 +12,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@sentry/browser": "10.39.0",
     "rollup": "^4.0.0",
     "vite": "^5.0.0",