[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M711CPFKVFSTFRXR0S5T4S59":3,"skill-same:01M711CPFKVFSTFRXR0S5T4S59":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":48,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M711CPFKVFSTFRXR0S5T4S59","telemetry-best-practices",null,"Reviews and authors telemetry code in this extension. Use when adding, modifying, or reviewing any `callWithTelemetryAndErrorHandling` call, any `context.telemetry.properties`\u002F`measurements` assignment, or any helper that reports stats to telemetry. Ensures no PII\u002FEUII is emitted, that property vs. measurement usage is correct, and that event\u002Fproperty names are consistent.","microsoft\u002Fvscode-cosmosdb","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M711CDNH6JY9J7RZVN19SNNC",200,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Ftelemetry-best-practices\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"best practices","telemetry best practices","telemetry","extension","properties","stats","helper","use","call","correct","event","usage","measurement","context","reports","code","when","pii","reviews","2026-11-10 10:12:30",false,"---\nname: telemetry-best-practices\ndescription: Reviews and authors telemetry code in this extension. Use when adding, modifying, or reviewing any `callWithTelemetryAndErrorHandling` call, any `context.telemetry.properties`\u002F`measurements` assignment, or any helper that reports stats to telemetry. Ensures no PII\u002FEUII is emitted, that property vs. measurement usage is correct, and that event\u002Fproperty names are consistent.\n---\n\n# Telemetry Best Practices\n\nThis extension uses `@microsoft\u002Fvscode-azext-utils` (`callWithTelemetryAndErrorHandling`, `IActionContext.telemetry`) to emit telemetry events. Telemetry is **public** — assume every property and measurement value is shipped to a backend and visible to whoever has access to the dashboards. Treat every new property as a privacy decision.\n\nThese rules apply to **the entire codebase** (extension host, webviews, language services, helper packages), not to any single feature area.\n\n## When to Use This Skill\n\nApply it whenever code:\n\n- Calls `callWithTelemetryAndErrorHandling(...)`, `callWithTelemetryAndErrorHandlingSync(...)`, or registers a command (which wraps the same).\n- Assigns to `context.telemetry.properties.*` or `context.telemetry.measurements.*`.\n- Defines a helper (e.g. `report*Stats`, `track*`, `*Telemetry`) that mutates an `IActionContext`.\n- Adds or renames a telemetry event string (the first argument to `callWithTelemetryAndErrorHandling`).\n\n## Hard Rules — Never Emit PII \u002F EUII\n\nThe following must **never** appear in `telemetry.properties` or `telemetry.measurements`, and never as part of an event name:\n\n- File names, base names, file paths, directory names, workspace names.\n- User IDs, resource names (other than the Azure account name — see below), database names, container\u002Fcollection names, connection strings, hostnames, endpoints, ports.\n- Query text, document contents, schema\u002FDDL contents, error messages containing any of the above, free-form user input, prompts, AI responses.\n- Email addresses, user names, machine names, IP addresses.\n- Deterministic identifiers derived from the above, including hashes, truncated hashes, and normalized hash values.\n  Cryptographic hashes are not inherently reversible, but guessable inputs can be recovered by hashing candidate values,\n  and stable outputs permit correlation across sessions.\n\n**Not PII** (always allowed): the AI model identifiers `modelId`, `modelFamily`, `modelVendor` (vendor-published values from `vscode.LanguageModelChat`), bounded enums you control, durations, counts, and ratios.\n\n### Allowed exceptions: OII identifiers under predefined property names\n\nA small set of Azure identifiers are **OII** (Organization Identifiable Information), not PII, and may be emitted **as-is** — but **only** under the predefined property names listed below. The telemetry pipeline (and `@microsoft\u002Fvscode-azext-utils`) recognizes these names and handles them accordingly (subscription scoping, sanitization of the resource path, organization-tier classification, etc.).\n\n| Key | Type | Notes |\n| --- | --- | --- |\n| `subscriptionId` | `string` | Azure subscription GUID. |\n| `tenantId` | `string` | Azure \u002F Entra tenant GUID. |\n| `resourceId` | `vscode.TelemetryTrustedValue` | Full ARM resource id. Must be wrapped so VS Code's telemetry layer does not re-sanitize the path. |\n| `accountName` | `string` | Azure resource (account) name, e.g. the Cosmos DB account name. |\n\n```ts\ncontext.telemetry.properties.subscriptionId = subscriptionId;\ncontext.telemetry.properties.tenantId = tenantId;\ncontext.telemetry.properties.accountName = account.name;\ncontext.telemetry.properties.resourceId = new vscode.TelemetryTrustedValue(resourceId.rawId);\n```\n\nRules:\n\n- Use **exactly** these key names. Logging the same value under any other key (`subId`, `accountId`, `armId`, `cosmosAccount`, …) bypasses the special handling and counts as PII.\n- `resourceId` must be wrapped in `new vscode.TelemetryTrustedValue(...)`.\n- Do **not** decompose the resource id and emit its parts (`resourceGroup`, `databaseName`, `containerName`, …) under separate properties — only the four keys above are allowed; everything else is PII.\n- `tenantId` is allowed OII, not personal data. Do not remove its predefined telemetry property or explicitly add tenant IDs\n  to `context.valuesToMask`. The library's built-in error sanitization may still redact GUIDs.\n- Still push the other listed values to `context.valuesToMask` so they are redacted from error messages emitted alongside\n  the event.\n\n### Safe alternatives when you need to correlate or categorize\n\n- A **non-persistent, in-memory session id** generated with `crypto.randomUUID()` per session\u002Foperation.\n- A bounded enum (e.g. `'mongo' | 'postgres' | 'sqlserver'`), never a free-form string.\n- A boolean flag (e.g. `hasCustomInstructions`) instead of the actual value.\n\nKeep hashes needed for local storage keys or comparisons local. For cohort selection, report only the boolean selection\nresult, not the underlying machine-ID hash or its normalized numeric value. Reuse existing random session IDs rather than\nadding another identifier when they already provide the required operation correlation.\n\n### Red flags to look for in reviews\n\n| Pattern | Action |\n| --- | --- |\n| `properties.fileName`, `properties.path`, `properties.basename`, `properties.fileBaseName` | Remove. |\n| `properties.error = err.message` (raw) | Remove or replace with a category enum + sanitized code. |\n| `properties.query`, `properties.sql`, `properties.ddl`, `properties.prompt`, `properties.response` | Remove. |\n| `properties.\u003Canything> = someUserInput` | Remove unless it is a validated bounded enum. |\n| OII value (`subscriptionId`, `tenantId`, `resourceId`, `accountName`) emitted under a different key | Rename to the predefined key, or remove. |\n| `resourceId` not wrapped in `vscode.TelemetryTrustedValue` | Wrap it. |\n| Event name containing a user value (e.g. `` `cosmosDB.${dbName}.start` ``) | Replace with a static event name; move the value to a bounded enum property only if safe. |\n\n## `context.valuesToMask` — Defense in Depth, Not a Substitute\n\n`IActionContext.valuesToMask` supplies sensitive strings for sanitization by `@microsoft\u002Fvscode-azext-utils`.\nThe library sanitizes string `telemetry.properties` before emission, using more aggressive masking for keys containing\n`error` or `exception`. Other string properties receive less aggressive masking but still use the registered values.\nNon-error `TelemetryTrustedValue` properties bypass this sanitization, and numeric `telemetry.measurements` are not masked.\nRegistering a raw value does not mask its deterministic derivatives, such as hashes or normalized hash values.\n\nMasks belong to the action context on which they are registered. Nested telemetry calls and separate tRPC invocations\nmust register their own masks before operations that can fail; caller or webview masks are not automatically inherited.\n\nFor NoSQL connections, reuse `maskConnectionTelemetry` to register connection values and every configured credential's\naccount key or managed-identity client ID, including fallback credentials. Entra tenant IDs are allowed OII and are not\nregistered as masks. Add operation-specific masks (such as query text) separately. Explicit client-ID masks avoid relying\nsolely on the sanitizer's GUID detection.\n\nUse it as a **safety net** for sensitive values that your code touches and might end up in a thrown error or log line you don't fully control:\n\n```ts\n\u002F\u002F Extension host: push directly to the action context\ncontext.valuesToMask.push(connectionString);\ncontext.valuesToMask.push(masterKey, endpoint, databaseId, containerId);\ncontext.valuesToMask.push(account.subscription.subscriptionId);\ncontext.valuesToMask.push(userProvidedName); \u002F\u002F database\u002Fcontainer\u002Fresource names entered in a wizard\n\n\u002F\u002F Webview-bridged events: register on the per-webview TelemetryContext instead\ntelemetryContext.addMaskedValue(connectionString);\ntelemetryContext.addMaskedValue([endpoint, databaseId, containerId]);\n```\n\n### Rules\n\n- **Always** push a value to `valuesToMask` as soon as you obtain it if it could end up in an error path. This includes:\n    - Strict secrets that must never appear in telemetry: connection strings, keys, tokens, query text, document contents, partition keys, user-entered names (database, container, resource).\n    - The OII identifiers `subscriptionId`, `resourceId`, and `accountName` — even though they are emitted as-is under their predefined keys, they should still be masked from error messages. Tenant IDs are exempt from explicit masking.\n- This is **defense in depth**, not a license to put a strict secret into telemetry properties.\n  Never do `properties.connectionString = cs` and rely on masking; emit only privacy-safe values by construction.\n- Push **non-empty** strings only. Empty\u002Fwhitespace values match everything and corrupt logs (the central `Telemetry.ts` filter already drops falsy values; do not bypass it).\n- If a value has multiple equivalent forms a user might see (e.g. a partition key with and without a leading `\u002F`), push **all** forms: `context.valuesToMask.push(partitionKey, partitionKey.slice(1));`\n- Wizard `prompt`\u002F`validateInput` steps that capture user input should push the captured value before the step returns. See `CosmosDBContainerNameStep`, `CosmosDBConnectionStringStep`, `CosmosDBPartitionKeyStep` for the pattern.\n- Branch data providers and tree item factories should mask resource ids\u002Fnames at construction time (see `CosmosDBBranchDataProvider`, `AccountInfo`).\n- For values that should be masked across all events emitted by a single webview, register them once on that webview's `TelemetryContext` via `addMaskedValue(value)` (see `src\u002FTelemetry.ts`); the mask list is then applied automatically to every `reportWebviewEvent` \u002F `reportWebviewError` call from that webview.\n\n## Properties vs. Measurements\n\n`telemetry.properties` are **strings**, `telemetry.measurements` are **numbers**. Use them correctly:\n\n- **String \u002F enum \u002F boolean → `properties`**. Stringify booleans (`String(value)`), keep enums short and bounded.\n- **Counts, durations (ms), sizes (chars\u002Fbytes), ratios → `measurements`**. Never put a number in `properties` just because it is convenient.\n- Round ratios\u002Ffloats to a sensible precision; avoid emitting `NaN` or `Infinity` — guard with a check before assignment.\n- Do not emit `null`\u002F`undefined`. Skip the assignment if the value is missing.\n\n## Naming Conventions\n\n- Event names: `cosmosDB.\u003Carea>[.\u003Csubarea>].\u003Caction>` (two to four `camelCase` segments). Keep them **static** — no interpolated user data. Examples currently in use: `cosmosDB.nosql.queryEditor.executeQuery`, `cosmosDB.migration.ddlExtractor.extract`. Match an existing prefix if you are adding to an existing area instead of inventing a new top-level name.\n- Property\u002Fmeasurement keys: `camelCase`, stable across versions. Renaming a key breaks dashboards and queries; prefer adding a new key over renaming.\n- Reuse the same key name across events when the meaning is identical (e.g. `sessionId`, `durationMs`, `errorCategory`).\n\n## Standard Patterns\n\n### 1. Best-effort sub-events: suppress display + don't rethrow\n\n```ts\nawait callWithTelemetryAndErrorHandling('cosmosDB.\u003Carea>.\u003Caction>', async (ctx) => {\n    ctx.errorHandling.suppressDisplay = true;\n    ctx.errorHandling.rethrow = false;\n    \u002F\u002F ... record measurements\u002Fproperties (sync or async) ...\n});\n```\n\nThe callback may be sync or async; keep it `async` whenever the work inside is async. Use this for fire-and-forget instrumentation that must never affect the user-visible flow.\n\n### 2. Rollups via a second `IActionContext`\n\nWhen per-call events would be too chatty, accumulate counters on a longer-lived context's `measurements` and emit a single summary event at the end. Pass that context as an extra parameter (commonly named `phaseContext` \u002F `rollupContext`) to the reporting helper.\n\n### 3. Centralize cross-cutting enrichment\n\nWhen the same set of properties (session id, mode, source type, etc.) appears at many call sites, put it in a single helper (`enrichWithMigrationContext`, `enrichWithQueryEditorContext`, …; `\u003CArea>` is a placeholder for the actual feature name) and call that at the top of every event. Extend the helper instead of duplicating assignments.\n\n### 4. Errors\n\n- Set `properties.errorCategory` to a bounded enum. Reuse values already used in the codebase (`'ai'`, `'infrastructure'` in `migrationTelemetry.ts`) before introducing new ones.\n- Do not put raw `error.message` into properties — it will likely contain user values.\n- Prefer error **codes** over messages. If a message must be retained, ensure it cannot contain user values (paths, names, queries).\n- `ctx.errorHandling.issueProperties` is the data appended to the body of the GitHub issue created when the user clicks **Report an Issue**. It is **not** a sanctioned PII channel — the same PII rules apply. Use it for diagnostic context (model id, error category, sanitized codes) that helps maintainers debug a reported issue.\n\n## Review Checklist\n\nWhen reviewing a diff that touches telemetry, confirm each item:\n\n- [ ] No file names, paths, resource names, IDs, hostnames, queries, or free-form user input in any property\u002Fmeasurement. (Exceptions: OII identifiers `subscriptionId`, `tenantId`, `accountName`, and `resourceId` under those exact key names; `resourceId` wrapped in `vscode.TelemetryTrustedValue`.)\n- [ ] Numbers go to `measurements`, strings\u002Fbooleans\u002Fenums go to `properties`.\n- [ ] Booleans are stringified (`String(value)`).\n- [ ] Floats are rounded; no `NaN`\u002F`Infinity` reach the assignment.\n- [ ] Event name is static (no template interpolation of user values).\n- [ ] Property\u002Fmeasurement keys use existing `camelCase` names where the meaning matches an existing key.\n- [ ] Best-effort sub-events set `suppressDisplay = true` and `rethrow = false`.\n- [ ] Errors are categorized via an enum, not raw messages.\n- [ ] Any sensitive value the action touches (connection strings, keys, tokens, OII identifiers other than tenant IDs, resource\u002Fdatabase\u002Fcontainer names, endpoints, user-entered names, query text, partition keys) is pushed to `context.valuesToMask` as soon as it is obtained.\n- [ ] JSDoc on any new `report*` \u002F `track*` helper explicitly states \"no file contents, paths, or names are emitted\".\n","# Telemetry Best Practices\n\nThis extension uses `@microsoft\u002Fvscode-azext-utils` (`callWithTelemetryAndErrorHandling`, `IActionContext.telemetry`) to emit telemetry events. Telemetry is **public** — assume every property and measurement value is shipped to a backend and visible to whoever has access to the dashboards. Treat every new property as a privacy decision.\n\nThese rules apply to **the entire codebase** (extension host, webviews, language services, helper packages), not to any single feature area.\n\n## When to Use This Skill\n\nApply it whenever code:\n\n- Calls `callWithTelemetryAndErrorHandling(...)`, `callWithTelemetryAndErrorHandlingSync(...)`, or registers a command (which wraps the same).\n- Assigns to `context.telemetry.properties.*` or `context.telemetry.measurements.*`.\n- Defines a helper (e.g. `report*Stats`, `track*`, `*Telemetry`) that mutates an `IActionContext`.\n- Adds or renames a telemetry event string (the first argument to `callWithTelemetryAndErrorHandling`).\n\n## Hard Rules — Never Emit PII \u002F EUII\n\nThe following must **never** appear in `telemetry.properties` or `telemetry.measurements`, and never as part of an event name:\n\n- File names, base names, file paths, directory names, workspace names.\n- User IDs, resource names (other than the Azure account name — see below), database names, container\u002Fcollection names, connection strings, hostnames, endpoints, ports.\n- Query text, document contents, schema\u002FDDL contents, error messages containing any of the above, free-form user input, prompts, AI responses.\n- Email addresses, user names, machine names, IP addresses.\n- Deterministic identifiers derived from the above, including hashes, truncated hashes, and normalized hash values.\n  Cryptographic hashes are not inherently reversible, but guessable inputs can be recovered by hashing candidate values,\n  and stable outputs permit correlation across sessions.\n\n**Not PII** (always allowed): the AI model identifiers `modelId`, `modelFamily`, `modelVendor` (vendor-published values from `vscode.LanguageModelChat`), bounded enums you control, durations, counts, and ratios.\n\n### Allowed exceptions: OII identifiers under predefined property names\n\nA small set of Azure identifiers are **OII** (Organization Identifiable Information), not PII, and may be emitted **as-is** — but **only** under the predefined property names listed below. The telemetry pipeline (and `@microsoft\u002Fvscode-azext-utils`) recognizes these names and handles them accordingly (subscription scoping, sanitization of the resource path, organization-tier classification, etc.).\n\n| Key | Type | Notes |\n| --- | --- | --- |\n| `subscriptionId` | `string` | Azure subscription GUID. |\n| `tenantId` | `string` | Azure \u002F Entra tenant GUID. |\n| `resourceId` | `vscode.TelemetryTrustedValue` | Full ARM resource id. Must be wrapped so VS Code's telemetry layer does not re-sanitize the path. |\n| `accountName` | `string` | Azure resource (account) name, e.g. the Cosmos DB account name. |\n\n```ts\ncontext.telemetry.properties.subscriptionId = subscriptionId;\ncontext.telemetry.properties.tenantId = tenantId;\ncontext.telemetry.properties.accountName = account.name;\ncontext.telemetry.properties.resourceId = new vscode.TelemetryTrustedValue(resourceId.rawId);\n```\n\nRules:\n\n- Use **exactly** these key names. Logging the same value under any other key (`subId`, `accountId`, `armId`, `cosmosAccount`, …) bypasses the special handling and counts as PII.\n- `resourceId` must be wrapped in `new vscode.TelemetryTrustedValue(...)`.\n- Do **not** decompose the resource id and emit its parts (`resourceGroup`, `databaseName`, `containerName`, …) under separate properties — only the four keys above are allowed; everything else is PII.\n- `tenantId` is allowed OII, not personal data. Do not remove its predefined telemetry property or explicitly add tenant IDs\n  to `context.valuesToMask`. The library's built-in error sanitization may still redact GUIDs.\n- Still push the other listed values to `context.valuesToMask` so they are redacted from error messages emitted alongside\n  the event.\n\n### Safe alternatives when you need to correlate or categorize\n\n- A **non-persistent, in-memory session id** generated with `crypto.randomUUID()` per session\u002Foperation.\n- A bounded enum (e.g. `'mongo' | 'postgres' | 'sqlserver'`), never a free-form string.\n- A boolean flag (e.g. `hasCustomInstructions`) instead of the actual value.\n\nKeep hashes needed for local storage keys or comparisons local. For cohort selection, report only the boolean selection\nresult, not the underlying machine-ID hash or its normalized numeric value. Reuse existing random session IDs rather than\nadding another identifier when they already provide the required operation correlation.\n\n### Red flags to look for in reviews\n\n| Pattern | Action |\n| --- | --- |\n| `properties.fileName`, `properties.path`, `properties.basename`, `properties.fileBaseName` | Remove. |\n| `properties.error = err.message` (raw) | Remove or replace with a category enum + sanitized code. |\n| `properties.query`, `properties.sql`, `properties.ddl`, `properties.prompt`, `properties.response` | Remove. |\n| `properties.\u003Canything> = someUserInput` | Remove unless it is a validated bounded enum. |\n| OII value (`subscriptionId`, `tenantId`, `resourceId`, `accountName`) emitted under a different key | Rename to the predefined key, or remove. |\n| `resourceId` not wrapped in `vscode.TelemetryTrustedValue` | Wrap it. |\n| Event name containing a user value (e.g. `` `cosmosDB.${dbName}.start` ``) | Replace with a static event name; move the value to a bounded enum property only if safe. |\n\n## `context.valuesToMask` — Defense in Depth, Not a Substitute\n\n`IActionContext.valuesToMask` supplies sensitive strings for sanitization by `@microsoft\u002Fvscode-azext-utils`.\nThe library sanitizes string `telemetry.properties` before emission, using more aggressive masking for keys containing\n`error` or `exception`. Other string properties receive less aggressive masking but still use the registered values.\nNon-error `TelemetryTrustedValue` properties bypass this sanitization, and numeric `telemetry.measurements` are not masked.\nRegistering a raw value does not mask its deterministic derivatives, such as hashes or normalized hash values.\n\nMasks belong to the action context on which they are registered. Nested telemetry calls and separate tRPC invocations\nmust register their own masks before operations that can fail; caller or webview masks are not automatically inherited.\n\nFor NoSQL connections, reuse `maskConnectionTelemetry` to register connection values and every configured credential's\naccount key or managed-identity client ID, including fallback credentials. Entra tenant IDs are allowed OII and are not\nregistered as masks. Add operation-specific masks (such as query text) separately. Explicit client-ID masks avoid relying\nsolely on the sanitizer's GUID detection.\n\nUse it as a **safety net** for sensitive values that your code touches and might end up in a thrown error or log line you don't fully control:\n\n```ts\n\u002F\u002F Extension host: push directly to the action context\ncontext.valuesToMask.push(connectionString);\ncontext.valuesToMask.push(masterKey, endpoint, databaseId, containerId);\ncontext.valuesToMask.push(account.subscription.subscriptionId);\ncontext.valuesToMask.push(userProvidedName); \u002F\u002F database\u002Fcontainer\u002Fresource names entered in a wizard\n\n\u002F\u002F Webview-bridged events: register on the per-webview TelemetryContext instead\ntelemetryContext.addMaskedValue(connectionString);\ntelemetryContext.addMaskedValue([endpoint, databaseId, containerId]);\n```\n\n### Rules\n\n- **Always** push a value to `valuesToMask` as soon as you obtain it if it could end up in an error path. This includes:\n    - Strict secrets that must never appear in telemetry: connection strings, keys, tokens, query text, document contents, partition keys, user-entered names (database, container, resource).\n    - The OII identifiers `subscriptionId`, `resourceId`, and `accountName` — even though they are emitted as-is under their predefined keys, they should still be masked from error messages. Tenant IDs are exempt from explicit masking.\n- This is **defense in depth**, not a license to put a strict secret into telemetry properties.\n  Never do `properties.connectionString = cs` and rely on masking; emit only privacy-safe values by construction.\n- Push **non-empty** strings only. Empty\u002Fwhitespace values match everything and corrupt logs (the central `Telemetry.ts` filter already drops falsy values; do not bypass it).\n- If a value has multiple equivalent forms a user might see (e.g. a partition key with and without a leading `\u002F`), push **all** forms: `context.valuesToMask.push(partitionKey, partitionKey.slice(1));`\n- Wizard `prompt`\u002F`validateInput` steps that capture user input should push the captured value before the step returns. See `CosmosDBContainerNameStep`, `CosmosDBConnectionStringStep`, `CosmosDBPartitionKeyStep` for the pattern.\n- Branch data providers and tree item factories should mask resource ids\u002Fnames at construction time (see `CosmosDBBranchDataProvider`, `AccountInfo`).\n- For values that should be masked across all events emitted by a single webview, register them once on that webview's `TelemetryContext` via `addMaskedValue(value)` (see `src\u002FTelemetry.ts`); the mask list is then applied automatically to every `reportWebviewEvent` \u002F `reportWebviewError` call from that webview.\n\n## Properties vs. Measurements\n\n`telemetry.properties` are **strings**, `telemetry.measurements` are **numbers**. Use them correctly:\n\n- **String \u002F enum \u002F boolean → `properties`**. Stringify booleans (`String(value)`), keep enums short and bounded.\n- **Counts, durations (ms), sizes (chars\u002Fbytes), ratios → `measurements`**. Never put a number in `properties` just because it is convenient.\n- Round ratios\u002Ffloats to a sensible precision; avoid emitting `NaN` or `Infinity` — guard with a check before assignment.\n- Do not emit `null`\u002F`undefined`. Skip the assignment if the value is missing.\n\n## Naming Conventions\n\n- Event names: `cosmosDB.\u003Carea>[.\u003Csubarea>].\u003Caction>` (two to four `camelCase` segments). Keep them **static** — no interpolated user data. Examples currently in use: `cosmosDB.nosql.queryEditor.executeQuery`, `cosmosDB.migration.ddlExtractor.extract`. Match an existing prefix if you are adding to an existing area instead of inventing a new top-level name.\n- Property\u002Fmeasurement keys: `camelCase`, stable across versions. Renaming a key breaks dashboards and queries; prefer adding a new key over renaming.\n- Reuse the same key name across events when the meaning is identical (e.g. `sessionId`, `durationMs`, `errorCategory`).\n\n## Standard Patterns\n\n### 1. Best-effort sub-events: suppress display + don't rethrow\n\n```ts\nawait callWithTelemetryAndErrorHandling('cosmosDB.\u003Carea>.\u003Caction>', async (ctx) => {\n    ctx.errorHandling.suppressDisplay = true;\n    ctx.errorHandling.rethrow = false;\n    \u002F\u002F ... record measurements\u002Fproperties (sync or async) ...\n});\n```\n\nThe callback may be sync or async; keep it `async` whenever the work inside is async. Use this for fire-and-forget instrumentation that must never affect the user-visible flow.\n\n### 2. Rollups via a second `IActionContext`\n\nWhen per-call events would be too chatty, accumulate counters on a longer-lived context's `measurements` and emit a single summary event at the end. Pass that context as an extra parameter (commonly named `phaseContext` \u002F `rollupContext`) to the reporting helper.\n\n### 3. Centralize cross-cutting enrichment\n\nWhen the same set of properties (session id, mode, source type, etc.) appears at many call sites, put it in a single helper (`enrichWithMigrationContext`, `enrichWithQueryEditorContext`, …; `\u003CArea>` is a placeholder for the actual feature name) and call that at the top of every event. Extend the helper instead of duplicating assignments.\n\n### 4. Errors\n\n- Set `properties.errorCategory` to a bounded enum. Reuse values already used in the codebase (`'ai'`, `'infrastructure'` in `migrationTelemetry.ts`) before introducing new ones.\n- Do not put raw `error.message` into properties — it will likely contain user values.\n- Prefer error **codes** over messages. If a message must be retained, ensure it cannot contain user values (paths, names, queries).\n- `ctx.errorHandling.issueProperties` is the data appended to the body of the GitHub issue created when the user clicks **Report an Issue**. It is **not** a sanctioned PII channel — the same PII rules apply. Use it for diagnostic context (model id, error category, sanitized codes) that helps maintainers debug a reported issue.\n\n## Review Checklist\n\nWhen reviewing a diff that touches telemetry, confirm each item:\n\n- [ ] No file names, paths, resource names, IDs, hostnames, queries, or free-form user input in any property\u002Fmeasurement. (Exceptions: OII identifiers `subscriptionId`, `tenantId`, `accountName`, and `resourceId` under those exact key names; `resourceId` wrapped in `vscode.TelemetryTrustedValue`.)\n- [ ] Numbers go to `measurements`, strings\u002Fbooleans\u002Fenums go to `properties`.\n- [ ] Booleans are stringified (`String(value)`).\n- [ ] Floats are rounded; no `NaN`\u002F`Infinity` reach the assignment.\n- [ ] Event name is static (no template interpolation of user values).\n- [ ] Property\u002Fmeasurement keys use existing `camelCase` names where the meaning matches an existing key.\n- [ ] Best-effort sub-events set `suppressDisplay = true` and `rethrow = false`.\n- [ ] Errors are categorized via an enum, not raw messages.\n- [ ] Any sensitive value the action touches (connection strings, keys, tokens, OII identifiers other than tenant IDs, resource\u002Fdatabase\u002Fcontainer names, endpoints, user-entered names, query text, partition keys) is pushed to `context.valuesToMask` as soon as it is obtained.\n- [ ] JSDoc on any new `report*` \u002F `track*` helper explicitly states \"no file contents, paths, or names are emitted\".\n",{"name":5,"description":7},"main","4d0ccf8e835f0cbf4788732ff7a42930e4b7c6d8",".github\u002Fskills\u002Ftelemetry-best-practices",89,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb","https:\u002F\u002Fmarketplace.visualstudio.com\u002Fitems?itemName=ms-azuretools.vscode-cosmosdb","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-12 02:57:12",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add microsoft\u002Fvscode-cosmosdb --skill telemetry-best-practices",{"tool":59,"command":60},"bunx","bunx skills add microsoft\u002Fvscode-cosmosdb --skill telemetry-best-practices",{"tool":62,"command":63},"pnpm","pnpm dlx skills add microsoft\u002Fvscode-cosmosdb --skill telemetry-best-practices","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Ftelemetry-best-practices\u002FSKILL.md",true,[],[68,98,125,144,171,202],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":79,"publishedAt":38},"01M711DAKP4A0MGZ9GB677588E","cosmosdb-relational-migration","Orchestrate relational database migrations to Azure Cosmos DB for NoSQL from source\ndiscovery through schema conversion, provisioning, and application code migration.\nUse when asked to migrate an RDBMS application, run or resume a\n.cosmosdb-migration project, infer relational DDL from code or other artifacts when\nno DDL is available, verify whether the application language has a supported Cosmos DB\nSDK, execute one migration phase, or remember migration findings, decisions, or a\ngenerated Cosmos DB model for another application, or review migration blockers\nand propose fixes for approval. Requires the\ncosmosdb-best-practices peer Skill.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002Fskills\u002Fcosmosdb-relational-migration\u002FSKILL.md",[74],{"categoryNo":75,"categoryName":76,"taxonomyType":77,"taxonomyTypeDesc":78},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[80,81,82,83,84,85,86,87,88,89,90,35,91,34,92,93,94,95,96,97],"cosmosdb relational migration","relational","migration","orchestrate","code migration","infer","model","db","project","generated","database","migrate","conversion","phase","review","run","database migrations","nosql",{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":107,"publishedAt":38},"01M711D5WVTMXJ79CEWR7YWNW2","cosmosdb-nosql-query-generation","Generate, explain, edit, and fix Azure Cosmos DB for NoSQL (SQL API) queries. Use\nwhenever you need to produce a syntactically correct, safe Cosmos DB NoSQL query — for\nexample when the user asks to generate, write, edit, fix, or explain a Cosmos DB NoSQL\nquery. Provides the NoSQL dialect rules, safety rules, and few-shot examples. Covers\nSELECT\u002FVALUE\u002FDISTINCT\u002FTOP, array-unwind JOINs, subqueries, WHERE\u002FBETWEEN\u002FIN\u002FLIKE,\nGROUP BY and aggregates, ORDER BY and ORDER BY RANK, OFFSET\u002FLIMIT, the full built-in\nfunction reference, and how Cosmos DB NoSQL differs from T-SQL \u002F PostgreSQL \u002F MySQL.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002Fskills\u002Fcosmosdb-nosql-query-generation\u002FSKILL.md",[104],{"categoryNo":105,"categoryName":106,"taxonomyType":77,"taxonomyTypeDesc":78},"01JBSEEDCAT000000000000010","后端与接口",[108,97,109,110,87,111,112,113,35,114,115,116,117,118,119,120,121,122,123,124],"query","cosmosdb nosql query generation","generation","select","aggregates","fix","you","api","mysql","postgresql","top","generate","how","sql","write","safe","edit",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":38},"01M711D2B9HC4SG6TQ22F0DVM4","cosmosdb-nosql-query-editor","Drive the active Azure Cosmos DB for NoSQL Query Editor in VS Code from natural\nlanguage. Use whenever the user asks in natural language to show \u002F find \u002F list \u002F count \u002F\nfilter data \"in this container\", \"in my container\", or in the active Cosmos DB Query\nEditor (for example: \"show me all trucks in this container\", \"find active users\",\n\"count documents by type\"), or to generate, edit, or explain a query for the active\neditor. This skill orchestrates the VS Code Language Model tools that read editor\ncontext, sample the container schema, apply a query, and run it; it delegates all\nCosmos DB NoSQL query-language rules, syntax, functions, and examples to the\ncosmosdb-nosql-query-generation skill.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002Fskills\u002Fcosmosdb-nosql-query-editor\u002FSKILL.md",[],[108,97,132,133,134,86,87,135,136,34,137,138,139,140,119,141,95,142,124,143],"cosmosdb nosql query editor","editor","show","documents","show me","filter","db query","sample","me","active","read","syntax",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":155,"publishedAt":38},"01M711CZ4AKAN8XX4EJSTZSW1T","cosmosdb-data-model-recommendation","Recommend Azure Cosmos DB for NoSQL partition keys from container schemas, query\npatterns, write rates, cardinality, and growth estimates. Use for Data Modeler\nrecommendations or direct Chat requests to choose, compare, score, or explain\npartition keys, including hierarchical and synthetic keys. Reuses the\ncosmosdb-best-practices skill and prefers suitable scenario hints for unchanged defaults.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002Fskills\u002Fcosmosdb-data-model-recommendation\u002FSKILL.md",[150],{"categoryNo":151,"categoryName":152,"taxonomyType":153,"taxonomyTypeDesc":154},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[86,156,157,158,159,160,87,161,162,108,163,164,122,165,166,97,167,168,169,170],"data","data model","recommendation","model recommendation","cosmosdb data model recommendation","partition","choose","synthetic","recommendations","recommend","scenario","direct","patterns","for","cosmos",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":185,"publishedAt":38},"01M711CSNGXF95EMZGJM4CQMMW","cosmosdb-best-practices","Azure Cosmos DB performance optimization and best practices guidelines for NoSQL,\npartitioning, queries, and SDK usage. Use when writing, reviewing, or refactoring\ncode that interacts with Azure Cosmos DB, designing data models, optimizing queries,\nor implementing high-performance database operations.\nUSE FOR: Cosmos DB NoSQL, partition key design, RU optimization, point reads,\ncross-partition queries, SDK singleton, CosmosClient, container modeling,\nchange feed, bulk operations, vector search, full-text search, hierarchical\npartition keys, global distribution, autoscale throughput, indexing policy,\nDO NOT USE FOR: PostgreSQL, MySQL, MongoDB (non-Azure), DynamoDB, Cassandra,\nAzure SQL, Cosmos DB for PostgreSQL (vCore), Cosmos DB for MongoDB vCore, Azure DocumentDB,\ngeneral SQL databases, Redis, Elasticsearch.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002Fskills\u002Fcosmosdb-best-practices\u002FSKILL.md",[177,178,181,184],{"categoryNo":105,"categoryName":106,"taxonomyType":77,"taxonomyTypeDesc":78},{"categoryNo":179,"categoryName":180,"taxonomyType":77,"taxonomyTypeDesc":78},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":182,"categoryName":183,"taxonomyType":153,"taxonomyTypeDesc":154},"01JBSEEDCAT000000000000030","开发工程师",{"categoryNo":151,"categoryName":152,"taxonomyType":153,"taxonomyTypeDesc":154},[19,186,187,188,189,87,190,161,191,192,193,194,195,196,197,198,199,200,201,90],"cosmosdb best practices","bulk","databases","distribution","performance","search","vector","implementing","database operations","design","kit","mongodb","writing","elasticsearch","singleton","high-performance",{"skillNo":203,"name":204,"nameZh":6,"description":205,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":206,"categories":207,"keywords":209,"publishedAt":38},"01M711CK9HG0ZMGQGWN0ZNR70M","backport","Backport changes (current branch, a PR, a branch, or specific commits\u002FSHAs) onto a target branch (typically a release branch like `rel\u002F*`). Use when the user says \"backport this\", \"backport PR ...\", \"cherry-pick to \u003Cbranch>\", or asks to port commits to another branch. Handles stashing uncommitted work, branch creation, cherry-picking with conflict handling, pushing, and opening a PR.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-cosmosdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fbackport\u002FSKILL.md",[208],{"categoryNo":75,"categoryName":76,"taxonomyType":77,"taxonomyTypeDesc":78},[204,210,211,212,213,214,215,26,216,35,217,218,219,220,221,222,223],"branch","conflict","pr","creation","commits","pick","backport pr","with","port","work","changes","release","opening a pr","user"]