This module provides a consistent way for extensions to report telemetry
over Application Insights. The module respects the user's decision about whether or
not to send telemetry data. See telemetry extension guidelines for more information on using telemetry in your extension.
import * as vscode from 'vscode';import TelemetryReporter from '@vscode/extension-telemetry';// the connection stringconst connectionString = '<your connection string>';// telemetry reporterlet reporter;function activate(context: vscode.ExtensionContext) { // create telemetry reporter on extension activation reporter = new TelemetryReporter(connectionString); // ensure it gets properly disposed. Upon disposal the events will be flushed context.subscriptions.push(reporter);}
Sending Events
Use this method for sending general events to App Insights.
// send event any time after activationreporter.sendTelemetryEvent('sampleEvent', { 'stringProp': 'some string' }, { 'numericMeasure': 123 });
Sending Errors as Events
Use this method for sending error telemetry as traditional events to App Insights.
Note: To filter out sensitive properties (e.g., stack traces), use replacementOptions in the constructor rather than passing properties to drop as a parameter.
// Configure property filtering in the constructorimport TelemetryReporter from '@vscode/extension-telemetry';const reporter = new TelemetryReporter( connectionString, [ // Remove or redact sensitive properties { lookup: /stackProp/, replacementString: '[REDACTED]' }, { lookup: /sensitiveData/ } // Remove entirely if no replacementString ]);// Send error event (properties are automatically filtered based on replacementOptions)reporter.sendTelemetryErrorEvent( 'sampleErrorEvent', { 'stringProp': 'some string', 'stackProp': 'some user stack trace' }, { 'numericMeasure': 123 }
Advanced Features (v1.5.0+)
Custom Endpoints and Configuration
Route telemetry to non-Azure endpoints (e.g., GitHub telemetry) and configure common properties and static tags:
import TelemetryReporter from '@vscode/extension-telemetry';import * as os from 'os';import * as vscode from 'vscode';const reporter = new TelemetryReporter( connectionString, undefined, // replacementOptions undefined, // initializationOptions undefined, // customFetch { // Custom endpoint URL - route to GitHub, Azure, or other services endpointUrl: 'https://<somename>-telemetry.githubusercontent.com/telemetry', // Common properties - automatically added to all events commonProperties: { 'common_os': os.platform(), 'common_arch': os.arch
When to use constructor options:
✅ All values are known at reporter construction time
✅ Values don't change during the reporter's lifetime
✅ This is the recommended approach for most use cases
Per-Event Tag Overrides
For dynamic tags that change per event (e.g., user tracking IDs from authentication tokens):
// Get dynamic tracking ID that changes per eventconst trackingId = getTrackingIdFromToken();// Send event with per-event tag override using the 4th parameterreporter.sendTelemetryEvent( 'userAction', { 'action': 'click' }, { 'duration': 123 }, { 'ai.user.id': trackingId } // Overrides user ID for this event only);// Error events also support per-event tag overridesreporter.sendTelemetryErrorEvent( 'errorEvent', { 'error': error.message }, { 'errorCount': 1 }, { 'ai.user.id': trackingId } // Per-event tag override (4th parameter));
Tag Merging Priority (lowest to highest):
Constructor tagOverrides (static, set at initialization)
Context tags via setContextTag() (can be set after construction)
Per-event tagOverrides (highest priority, dynamic per event)
Runtime Tag Management (Advanced)
For edge cases where tags are not available at construction or need to change at runtime:
const reporter = new TelemetryReporter(connectionString);// Set context tag after construction (e.g., after async initialization)authService.getSession().then(session => { reporter.setContextTag('ai.session.id', session.id);});// Update tag at runtime (e.g., user switches accounts)reporter.setContextTag('ai.user.id', 'user1');// ... later ...reporter.setContextTag('ai.user.id', 'user2');// Read back a context tag valueconst sessionId = reporter.getContextTag('ai.session.id');
When to use setContextTag():
⚠️ Tags are not available when the reporter is constructed
⚠️ Tags need to change at runtime (e.g., user account switching)
⚠️ You need to read tag values back later
Note: For most use cases, prefer constructor tagOverrides over setContextTag() for better immutability and clarity.
Dangerous Methods (Bypass Telemetry Settings)
These methods send telemetry without checking the user's telemetry settings. Only use them in controlled environments such as CI pipelines or during development testing.
⚠️ 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).
Common Properties
Extension Namecommon.extname - The extension name
Extension Versioncommon.extversion - The extension version
Machine Identifiercommon.vscodemachineid - A common machine identifier generated by VS Code
Session Identifiercommon.vscodesessionid - A session identifier generated by VS Code
VS Code Commitcommon.vscodecommithash - A VS Code commit hash
VS Code Versioncommon.vscodeversion - The version of VS Code running the extension
OScommon.os - The OS running VS Code
Platform Versioncommon.platformversion - The version of the OS/Platform
Productcommon.product - What Vs code is hosted in, i.e. desktop, github.dev, codespaces.
UI Kindcommon.uikind - Web or Desktop indicating where VS Code is running
Remote Namecommon.remotename - A name to identify the type of remote connection. other indicates a remote connection not from the 3 main extensions (ssh, docker, wsl).
Architecturecommon.nodeArch - What architecture of node is running. i.e. arm or x86. On the web it will just say web.