https://github.com/microsoft/vscode-extension-telemetry
Node module to help VS Code extensions send telemetry using application insights
https://github.com/microsoft/vscode-extension-telemetry
nodejs telemetry vscode
Last synced: 4 months ago
JSON representation
Node module to help VS Code extensions send telemetry using application insights
- Host: GitHub
- URL: https://github.com/microsoft/vscode-extension-telemetry
- Owner: microsoft
- License: other
- Created: 2016-02-05T23:47:17.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2025-05-07T12:49:15.000Z (about 1 year ago)
- Last Synced: 2025-05-11T09:16:52.096Z (about 1 year ago)
- Topics: nodejs, telemetry, vscode
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@vscode/extension-telemetry
- Size: 1.04 MB
- Stars: 133
- Watchers: 33
- Forks: 53
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# [@vscode/extension-telemetry](https://www.npmjs.com/package/@vscode/extension-telemetry)
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](https://code.visualstudio.com/api/extension-guides/telemetry) for more information on using telemetry in your extension.
Follow [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.
# Install
With npm:
`npm install @vscode/extension-telemetry`
With yarn:
`yarn add @vscode/extension-telemetry`
# Usage
## Setup
```javascript
import * as vscode from 'vscode';
import TelemetryReporter from '@vscode/extension-telemetry';
// the connection string
const connectionString = '';
// telemetry reporter
let 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.
```javascript
// send event any time after activation
reporter.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.
```javascript
// Configure property filtering in the constructor
import 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:
```javascript
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://-telemetry.githubusercontent.com/telemetry',
// Common properties - automatically added to all events
commonProperties: {
'common_os': os.platform(),
'common_arch': os.arch(),
'custom_property': 'value'
},
// Static tag overrides - applied to all events (RECOMMENDED for static tags)
tagOverrides: {
'ai.cloud.roleInstance': 'REDACTED',
'ai.session.id': vscode.env.sessionId,
'ai.cloud.role': 'my-service'
}
}
);
```
**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):
```javascript
// Get dynamic tracking ID that changes per event
const trackingId = getTrackingIdFromToken();
// Send event with per-event tag override using the 4th parameter
reporter.sendTelemetryEvent(
'userAction',
{ 'action': 'click' },
{ 'duration': 123 },
{ 'ai.user.id': trackingId } // Overrides user ID for this event only
);
// Error events also support per-event tag overrides
reporter.sendTelemetryErrorEvent(
'errorEvent',
{ 'error': error.message },
{ 'errorCount': 1 },
{ 'ai.user.id': trackingId } // Per-event tag override (4th parameter)
);
```
**Tag Merging Priority** (lowest to highest):
1. Constructor `tagOverrides` (static, set at initialization)
2. Context tags via `setContextTag()` (can be set after construction)
3. **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:
```javascript
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 value
const 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.
```javascript
// Send event without checking telemetry setting
reporter.sendDangerousTelemetryEvent(
'ciPipelineEvent',
{ 'build': 'success' },
{ 'duration': 1234 },
{ 'ai.user.id': trackingId } // Optional tag overrides
);
// Send error event without checking telemetry setting
reporter.sendDangerousTelemetryErrorEvent(
'ciErrorEvent',
{ 'error': 'build failed' },
{ 'errorCount': 1 },
{ 'ai.user.id': trackingId } // Optional tag overrides
);
// Send exception directly to Application Insights exceptions table
// without checking telemetry setting
try {
riskyOperation();
} catch (error) {
reporter.sendDangerousTelemetryException(
error,
{ 'context': 'ci-pipeline' },
{ 'retryCount': 3 },
{ 'ai.user.id': trackingId } // Optional tag overrides
);
}
```
⚠️ **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 Name** `common.extname` - The extension name
- **Extension Version** `common.extversion` - The extension version
- **Machine Identifier** `common.vscodemachineid` - A common machine identifier generated by VS Code
- **Session Identifier** `common.vscodesessionid` - A session identifier generated by VS Code
- **VS Code Commit** `common.vscodecommithash` - A VS Code commit hash
- **VS Code Version** `common.vscodeversion` - The version of VS Code running the extension
- **OS** `common.os` - The OS running VS Code
- **Platform Version** `common.platformversion` - The version of the OS/Platform
- **Product** `common.product` - What Vs code is hosted in, i.e. desktop, github.dev, codespaces.
- **UI Kind** `common.uikind` - Web or Desktop indicating where VS Code is running
- **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).
- **Architecture** `common.nodeArch` - What architecture of node is running. i.e. arm or x86. On the web it will just say `web`.
# License
[MIT](LICENSE)