{"id":15012451,"url":"https://github.com/microsoft/vscode-extension-telemetry","last_synced_at":"2026-02-27T23:49:24.036Z","repository":{"id":38705373,"uuid":"51181395","full_name":"microsoft/vscode-extension-telemetry","owner":"microsoft","description":"Node module to help VS Code extensions send telemetry using application insights","archived":false,"fork":false,"pushed_at":"2025-05-07T12:49:15.000Z","size":1089,"stargazers_count":133,"open_issues_count":7,"forks_count":53,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-05-11T09:16:52.096Z","etag":null,"topics":["nodejs","telemetry","vscode"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@vscode/extension-telemetry","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-02-05T23:47:17.000Z","updated_at":"2025-05-07T11:53:02.000Z","dependencies_parsed_at":"2023-02-19T09:46:15.602Z","dependency_job_id":"ceabc70a-933a-4d18-80c0-f68837590cbc","html_url":"https://github.com/microsoft/vscode-extension-telemetry","commit_stats":{"total_commits":316,"total_committers":31,"mean_commits":"10.193548387096774","dds":"0.45569620253164556","last_synced_commit":"6ae3c8a857353f57fa9d70aa5e1c482062e97f28"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fvscode-extension-telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fvscode-extension-telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fvscode-extension-telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fvscode-extension-telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/vscode-extension-telemetry/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253540833,"owners_count":21924537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nodejs","telemetry","vscode"],"created_at":"2024-09-24T19:42:39.238Z","updated_at":"2026-02-27T23:49:24.012Z","avatar_url":"https://github.com/microsoft.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [@vscode/extension-telemetry](https://www.npmjs.com/package/@vscode/extension-telemetry)\nThis module provides a consistent way for extensions to report telemetry\nover Application Insights. The module respects the user's decision about whether or\nnot to send telemetry data. See [telemetry extension guidelines](https://code.visualstudio.com/api/extension-guides/telemetry) for more information on using telemetry in your extension.\n\nFollow [guide to set up Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/create-workspace-resource) in Azure and get your connection string. Don't worry about hardcoding it, it is not sensitive.\n\n# Install\nWith npm:\n`npm install @vscode/extension-telemetry`\n\nWith yarn:\n`yarn add @vscode/extension-telemetry`\n\n# Usage\n\n## Setup\n```javascript\nimport * as vscode from 'vscode';\nimport TelemetryReporter from '@vscode/extension-telemetry';\n\n// the connection string\nconst connectionString = '\u003cyour connection string\u003e';\n\n// telemetry reporter\nlet reporter;\n\nfunction activate(context: vscode.ExtensionContext) {\n   // create telemetry reporter on extension activation\n   reporter = new TelemetryReporter(connectionString);\n   // ensure it gets properly disposed. Upon disposal the events will be flushed\n   context.subscriptions.push(reporter);\n}\n```\n\n## Sending Events\n\nUse this method for sending general events to App Insights.\n\n```javascript\n// send event any time after activation\nreporter.sendTelemetryEvent('sampleEvent', { 'stringProp': 'some string' }, { 'numericMeasure': 123 });\n```\n\n## Sending Errors as Events\n\nUse this method for sending error telemetry as traditional events to App Insights. \n\n**Note:** To filter out sensitive properties (e.g., stack traces), use `replacementOptions` in the constructor rather than passing properties to drop as a parameter.\n\n```javascript\n// Configure property filtering in the constructor\nimport TelemetryReporter from '@vscode/extension-telemetry';\n\nconst reporter = new TelemetryReporter(\n   connectionString,\n   [\n      // Remove or redact sensitive properties\n      { lookup: /stackProp/, replacementString: '[REDACTED]' },\n      { lookup: /sensitiveData/ }  // Remove entirely if no replacementString\n   ]\n);\n\n// Send error event (properties are automatically filtered based on replacementOptions)\nreporter.sendTelemetryErrorEvent(\n   'sampleErrorEvent',\n   { 'stringProp': 'some string', 'stackProp': 'some user stack trace' },\n   { 'numericMeasure': 123 }\n);\n```\n\n# Advanced Features (v1.5.0+)\n\n## Custom Endpoints and Configuration\n\nRoute telemetry to non-Azure endpoints (e.g., GitHub telemetry) and configure common properties and static tags:\n\n```javascript\nimport TelemetryReporter from '@vscode/extension-telemetry';\nimport * as os from 'os';\nimport * as vscode from 'vscode';\n\nconst reporter = new TelemetryReporter(\n   connectionString,\n   undefined,  // replacementOptions\n   undefined,  // initializationOptions\n   undefined,  // customFetch\n   {\n      // Custom endpoint URL - route to GitHub, Azure, or other services\n      endpointUrl: 'https://\u003csomename\u003e-telemetry.githubusercontent.com/telemetry',\n      \n      // Common properties - automatically added to all events\n      commonProperties: {\n         'common_os': os.platform(),\n         'common_arch': os.arch(),\n         'custom_property': 'value'\n      },\n      \n      // Static tag overrides - applied to all events (RECOMMENDED for static tags)\n      tagOverrides: {\n         'ai.cloud.roleInstance': 'REDACTED',\n         'ai.session.id': vscode.env.sessionId,\n         'ai.cloud.role': 'my-service'\n      }\n   }\n);\n```\n\n**When to use constructor options:**\n- ✅ All values are known at reporter construction time\n- ✅ Values don't change during the reporter's lifetime\n- ✅ **This is the recommended approach for most use cases**\n\n## Per-Event Tag Overrides\n\nFor dynamic tags that change per event (e.g., user tracking IDs from authentication tokens):\n\n```javascript\n// Get dynamic tracking ID that changes per event\nconst trackingId = getTrackingIdFromToken();\n\n// Send event with per-event tag override using the 4th parameter\nreporter.sendTelemetryEvent(\n   'userAction',\n   { 'action': 'click' },\n   { 'duration': 123 },\n   { 'ai.user.id': trackingId }  // Overrides user ID for this event only\n);\n\n// Error events also support per-event tag overrides\nreporter.sendTelemetryErrorEvent(\n   'errorEvent',\n   { 'error': error.message },\n   { 'errorCount': 1 },\n   { 'ai.user.id': trackingId }  // Per-event tag override (4th parameter)\n);\n```\n\n**Tag Merging Priority** (lowest to highest):\n1. Constructor `tagOverrides` (static, set at initialization)\n2. Context tags via `setContextTag()` (can be set after construction)\n3. **Per-event `tagOverrides`** (highest priority, dynamic per event)\n\n## Runtime Tag Management (Advanced)\n\nFor edge cases where tags are not available at construction or need to change at runtime:\n\n```javascript\nconst reporter = new TelemetryReporter(connectionString);\n\n// Set context tag after construction (e.g., after async initialization)\nauthService.getSession().then(session =\u003e {\n   reporter.setContextTag('ai.session.id', session.id);\n});\n\n// Update tag at runtime (e.g., user switches accounts)\nreporter.setContextTag('ai.user.id', 'user1');\n// ... later ...\nreporter.setContextTag('ai.user.id', 'user2');\n\n// Read back a context tag value\nconst sessionId = reporter.getContextTag('ai.session.id');\n```\n\n**When to use `setContextTag()`:**\n- ⚠️ Tags are not available when the reporter is constructed\n- ⚠️ Tags need to change at runtime (e.g., user account switching)\n- ⚠️ You need to read tag values back later\n\n**Note:** For most use cases, prefer constructor `tagOverrides` over `setContextTag()` for better immutability and clarity.\n\n## Dangerous Methods (Bypass Telemetry Settings)\n\nThese methods send telemetry **without checking the user's telemetry settings**. Only use them in controlled environments such as CI pipelines or during development testing.\n\n```javascript\n// Send event without checking telemetry setting\nreporter.sendDangerousTelemetryEvent(\n   'ciPipelineEvent',\n   { 'build': 'success' },\n   { 'duration': 1234 },\n   { 'ai.user.id': trackingId }  // Optional tag overrides\n);\n\n// Send error event without checking telemetry setting\nreporter.sendDangerousTelemetryErrorEvent(\n   'ciErrorEvent',\n   { 'error': 'build failed' },\n   { 'errorCount': 1 },\n   { 'ai.user.id': trackingId }  // Optional tag overrides\n);\n\n// Send exception directly to Application Insights exceptions table\n// without checking telemetry setting\ntry {\n   riskyOperation();\n} catch (error) {\n   reporter.sendDangerousTelemetryException(\n      error,\n      { 'context': 'ci-pipeline' },\n      { 'retryCount': 3 },\n      { 'ai.user.id': trackingId }  // Optional tag overrides\n   );\n}\n```\n\n⚠️ **Warning:** These methods bypass the user's telemetry opt-in preference. Only use them when you have explicit consent or in non-user-facing scenarios (e.g., automated testing, CI/CD pipelines).\n\n# Common Properties\n- **Extension Name** `common.extname` - The extension name\n- **Extension Version** `common.extversion` - The extension version\n- **Machine Identifier** `common.vscodemachineid` - A common machine identifier generated by VS Code\n- **Session Identifier** `common.vscodesessionid` - A session identifier generated by VS Code\n- **VS Code Commit** `common.vscodecommithash` - A VS Code commit hash\n- **VS Code Version** `common.vscodeversion` - The version of VS Code running the extension\n- **OS** `common.os` - The OS running VS Code\n- **Platform Version** `common.platformversion` - The version of the OS/Platform\n- **Product** `common.product` - What Vs code is hosted in, i.e. desktop, github.dev, codespaces.\n- **UI Kind** `common.uikind` - Web or Desktop indicating where VS Code is running\n- **Remote Name** `common.remotename` - A name to identify the type of remote connection. `other` indicates a remote connection not from the 3 main extensions (ssh, docker, wsl).\n- **Architecture** `common.nodeArch` - What architecture of node is running. i.e. arm or x86. On the web it will just say `web`.\n\n# License\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fvscode-extension-telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fvscode-extension-telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fvscode-extension-telemetry/lists"}