BC Telemetry Buddy - VSCode Extension

VSCode extension for querying Business Central telemetry with natural language support and GitHub Copilot integration.

Overview

BC Telemetry Buddy helps you analyze Business Central telemetry data from Application Insights directly within VSCode. The extension works standalone for direct commands, with optional MCP server integration for GitHub Copilot chat features.

Key Capabilities:

✅ Direct Query Execution: Run KQL queries from Command Palette or CodeLens - no additional services required
✅ GitHub Copilot Integration: Optional chat participant (@bc-telemetry-buddy) with 11 specialized tools for systematic telemetry analysis
✅ Guided Setup Wizard: Step-by-step configuration with validation and connection testing
✅ Flexible Configuration: Single .bctb-config.json file with multi-profile support for multiple customers
✅ Smart MCP Management: Automatically uses globally-installed MCP for independent updates (configurable via bctb.mcp.preferGlobal setting)
✅ Usage Telemetry: Anonymous telemetry collection to improve reliability (respects VS Code's telemetry.telemetryLevel setting)
✅ Automatic Migration: Seamless migration from legacy VSCode settings to new file-based configuration

🚀 Quick Start

For New Users

Install from VSCode Marketplace (search for "BC Telemetry Buddy")
Run Setup Wizard: Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → BC Telemetry Buddy: Setup Wizard
Configure your Azure resources through the guided wizard:
- Azure tenant and Application Insights connection
- Authentication method (Azure CLI recommended, Device Code, or Client Credentials)
- Kusto cluster URL (pre-filled with BC telemetry endpoint)
- Connection testing to validate configuration
Start Using Commands:
- BC Telemetry Buddy: Run KQL Query - Execute queries directly
- BC Telemetry Buddy: Save Query - Save to workspace library
- CodeLens in .kql files - Click "▶ Run Query" above queries
(Optional) Install MCP for Chat: If you want to use GitHub Copilot chat features:
- Extension will prompt: "Install MCP Server for Chat?"
- Click "Install" to enable @bc-telemetry-buddy chat participant
- Or run manually: npm install -g bc-telemetry-buddy-mcp

The setup wizard automatically appears on first activation and guides you through complete configuration with validation and testing.

For Existing Users (Upgrading from v0.2.x)

Your settings will migrate automatically! On first launch after upgrade:

Extension detects old bcTelemetryBuddy.* settings
Shows notification: "Migrate to new configuration format?"
Click "Migrate Settings" → creates .bctb-config.json from old settings
Extension works immediately with direct commands
(Optional) Install MCP separately if you want chat features

Nothing breaks - your existing setup continues to work during migration. See Migration Guide for details.

✨ Features

Getting Started

🧙 Setup Wizard: Step-by-step 5-step guided configuration with connection testing, validation, and automatic settings save
🔐 Flexible Authentication: Azure CLI (recommended - uses existing az login), Device Code, or Client Credentials

Discovery & Exploration

📊 Event Catalog: Browse available BC telemetry event IDs (RT0001, RT0005, etc.) with descriptions, frequency, and Learn URLs
🔍 Schema Discovery: Understand customDimensions fields for each event type by sampling recent occurrences
🗺️ Tenant Mapping: Automatically discover company names and map them to Azure tenant IDs for customer queries

Query Execution

🤖 GitHub Copilot Integration: 11 MCP tools enable Copilot to systematically discover → understand → search → execute queries
💬 Intelligent Query Generation: Ask questions in plain English - Copilot uses discovery tools to build accurate KQL
📝 KQL Support: Write and execute KQL queries directly; create .kql files with syntax highlighting
👁️ CodeLens: "▶ Run Query" links appear above queries in .kql files for one-click execution
📋 Rich Results: View query results in formatted tables with row counts, execution timing, and recommendations

Query Management

📚 Query Library: Save queries organized by category; customer-specific queries auto-filed in Companies/[CompanyName]/[Category]/ folders
� Query Search: Search saved queries by keywords to find existing patterns before writing new KQL
💾 Smart Caching: File-based caching with configurable TTL (default 1 hour); manual cache management commands
🧠 Context-Aware: Automatically includes saved workspace queries and external GitHub references for better KQL generation

📋 Commands

Command	Description
BC Telemetry Buddy: Setup Wizard ⭐	Start here! Guided 5-step configuration wizard with validation
BC Telemetry Buddy: Migrate Settings to .bctb-config.json	Migrate legacy VSCode settings to new config file format
BC Telemetry Buddy: Start MCP Server	Manually start the MCP backend (HTTP mode for Command Palette)
BC Telemetry Buddy: Run KQL Query	Execute KQL query with results display
BC Telemetry Buddy: Run KQL From Document	Execute query from current `.kql` file
BC Telemetry Buddy: Clear Cache	Delete all cached query results for fresh data
BC Telemetry Buddy: Show Cache Statistics	Display cache size, entry count, and expiration info
BC Telemetry Buddy: Install Chatmodes	Install GitHub Copilot chat mode definitions for BC Telemetry analysis
BC Telemetry Buddy: Switch Profile	Switch between configured profiles (multi-profile setups)
BC Telemetry Buddy: Create Profile	Create a new configuration profile
BC Telemetry Buddy: Set Default Profile	Set the default profile for workspace
BC Telemetry Buddy: Manage Profiles	Open profile management interface
BC Telemetry Buddy: What's New	Show release notes and what's new
BC Telemetry Buddy: Check for MCP Updates	Check if newer MCP server version is available
BC Telemetry Buddy: Reset Telemetry ID	Reset the anonymous installation ID for usage telemetry

⚙️ Configuration

Setup Wizard (Recommended)

The Setup Wizard handles all configuration automatically with validation and testing. Run it from Command Palette:

BC Telemetry Buddy: Setup Wizard

Wizard creates .bctb-config.json in your workspace root with all necessary settings.

Configuration File (`.bctb-config.json`)

The extension reads configuration from .bctb-config.json in your workspace root. This file is created automatically by the Setup Wizard.

Basic Configuration

{
  "connectionName": "Production BC Telemetry",
  "tenantId": "12345678-1234-1234-1234-123456789abc",
  "authFlow": "azure_cli",
  "applicationInsightsAppId": "your-app-insights-app-id",
  "kustoClusterUrl": "https://ade.applicationinsights.io/subscriptions/<subscription-id>",
  "workspacePath": "${workspaceFolder}",
  "queriesFolder": "queries",
  "cacheEnabled": true,
  "cacheTTLSeconds": 3600,
  "removePII": false
}

Authentication Flows:

azure_cli (recommended): Uses existing az login session - no additional credentials needed
device_code: Browser-based authentication - prompts when needed
client_credentials: Service principal with client ID + secret (use environment variables for secrets)

Client Credentials Authentication

For automation scenarios, use service principal with secrets in environment variables:

{
  "authFlow": "client_credentials",
  "tenantId": "your-tenant-id",
  "clientId": "${BCTB_CLIENT_ID}",
  "clientSecret": "${BCTB_CLIENT_SECRET}",
  "applicationInsightsAppId": "your-app-insights-app-id",
  "kustoClusterUrl": "https://ade.applicationinsights.io/..."
}

Set environment variables:

# Windows PowerShell
$env:BCTB_CLIENT_ID = "your-client-id"
$env:BCTB_CLIENT_SECRET = "your-client-secret"

# Linux/Mac
export BCTB_CLIENT_ID="your-client-id"
export BCTB_CLIENT_SECRET="your-client-secret"

External References (KQL Examples)

Pull example queries from GitHub repos for Copilot context:

{
  "connectionName": "Production",
  "authFlow": "azure_cli",
  "applicationInsightsAppId": "...",
  "kustoClusterUrl": "...",
  "references": [
    {
      "name": "BC Samples",
      "type": "github",
      "url": "https://github.com/microsoft/BCTech/tree/master/samples/AppInsights",
      "enabled": true
    }
  ]
}

Multi-Profile Configuration (Multiple Customers)

If you work with multiple customers, use profiles to switch between them easily:

{
  "profiles": {
    "customer-a-prod": {
      "connectionName": "Customer A Production",
      "authFlow": "azure_cli",
      "applicationInsightsAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "kustoClusterUrl": "https://ade.applicationinsights.io/...",
      "workspacePath": "${workspaceFolder}/customers/customer-a",
      "queriesFolder": "queries"
    },
    "customer-b-prod": {
      "connectionName": "Customer B Production",
      "authFlow": "device_code",
      "applicationInsightsAppId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "kustoClusterUrl": "https://ade.applicationinsights.io/...",
      "workspacePath": "${workspaceFolder}/customers/customer-b",
      "queriesFolder": "queries"
    }
  },
  "defaultProfile": "customer-a-prod",
  "cacheEnabled": true,
  "cacheTTLSeconds": 3600
}

Switch profiles via status bar dropdown or Command Palette: BC Telemetry Buddy: Switch Profile

See complete configuration documentation in the repository README.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Package extension
npm run package

🔧 How It Works

Architecture (v1.0.0+)

The extension uses a dual-path architecture for maximum flexibility:

Path 1: Direct Execution (No MCP)

For all Command Palette commands and CodeLens actions:

VSCode Command → TelemetryService → Azure/Kusto → Results Display

TelemetryService: Built-in service using shared business logic
Authentication: MSAL library (azure_cli, device_code, or client_credentials)
KQL Execution: Direct Kusto API calls
No Dependencies: Works immediately after Setup Wizard
Faster: No HTTP/JSON-RPC overhead

Path 2: Chat Integration (Requires MCP)

For GitHub Copilot chat participant (@bc-telemetry-buddy):

GitHub Copilot Chat → MCP Server → Tools (11 specialized) → Azure/Kusto → Chat Response

MCP Server: Separate process (bc-telemetry-buddy-mcp NPM package)
Tools: Event catalog, schema discovery, query search, execution, etc.
Optional: Only install if you want chat features
Installation: npm install -g bc-telemetry-buddy-mcp

Configuration Discovery

Extension reads .bctb-config.json with this discovery order:

.bctb-config.json in current directory
.bctb-config.json in workspace root (most common)
~/.bctb/config.json in user home directory
Environment variables (fallback)

MCP server (if installed) uses the same config file, ensuring consistency.

Telemetry Workflow

Discovery: Browse event catalog (RT0001, RT0005, etc.) to see available telemetry
Field Analysis: Understand customDimensions structure with sample values
Reuse Patterns: Search saved queries for proven patterns
Execute Query: Run via commands, CodeLens, or chat
Save for Team: Save useful queries to workspace library

Authentication

Azure CLI (recommended): Uses cached credentials from az login - no re-auth needed
Device Code: Browser-based interactive login - prompts when token expires
Client Credentials: Service principal for automation - requires client ID + secret in env vars

Caching & Performance

Query results cached locally in workspace (.vscode/.bctb/cache/)
Default TTL: 1 hour (configurable in .bctb-config.json)
Manual cache management via Command Palette
Cache key = hash(KQL query + parameters)

Context & Intelligent Generation (Chat Only)

Scans workspace queries/ folder for saved KQL patterns
Optionally fetches external reference queries from GitHub repos
Copilot uses discovery tools to understand event structure
Systematic workflow: discover events → analyze fields → search patterns → generate KQL

🔄 Migrating from v0.2.x

What Changed?

v0.2.x (Old - Bundled MCP):

MCP server bundled inside extension
Extension required MCP for all features
Settings scattered across bcTelemetryBuddy.* namespace in VSCode settings
HTTP mode required for all commands

v1.0.0 (New - Independent Architecture):

Extension works standalone (no MCP needed for direct commands)
MCP is a separate optional package (bc-telemetry-buddy-mcp)
Single .bctb-config.json file for configuration
Direct execution via TelemetryService (faster, simpler)
MCP only needed for chat participant

Migration Steps

Automatic Migration (Recommended):

Update extension from Marketplace (v0.3.0+)
Reload VSCode
Extension detects old settings automatically
Click "Migrate Settings" when prompted
Extension creates .bctb-config.json from your old settings
Done! Extension works immediately

Manual Migration:

If you prefer to migrate manually or automatic migration didn't work:

Note your current settings from .vscode/settings.json:

{
  "bcTelemetryBuddy.connectionName": "...",
  "bcTelemetryBuddy.appInsights.appId": "...",
  "bcTelemetryBuddy.kusto.clusterUrl": "...",
  "bcTelemetryBuddy.authFlow": "..."
}

Run Setup Wizard: BC Telemetry Buddy: Setup Wizard
Enter your settings when prompted (wizard validates everything)
Wizard creates .bctb-config.json in workspace root
Delete old bcTelemetryBuddy.* settings from .vscode/settings.json (optional - they're ignored now)

Installing MCP for Chat (Optional)

If you want to use the chat participant (@bc-telemetry-buddy):

Option 1: Extension Prompt

Extension will ask: "Install MCP Server for Chat?"
Click "Install" → extension runs npm install -g bc-telemetry-buddy-mcp

Option 2: Manual Install

npm install -g bc-telemetry-buddy-mcp

Verify Installation:

bctb-mcp --version

The extension will automatically detect the globally-installed MCP and use it for chat features.

Troubleshooting Migration

Q: My queries don't work after upgrading!

Run Setup Wizard to validate configuration
Check .bctb-config.json exists in workspace root
Verify App Insights ID and Kusto URL are correct

Q: Chat participant not working?

MCP server required for chat (install: npm install -g bc-telemetry-buddy-mcp)
Direct commands (Run KQL, Save Query) work without MCP

Q: "Configuration incomplete" errors?

.bctb-config.json missing or invalid
Run Setup Wizard to regenerate configuration
Check file exists and has correct JSON format

Q: Authentication fails?

For azure_cli: Run az login first
For device_code: Follow browser prompts
For client_credentials: Check client ID/secret env vars

Q: Where did my old settings go?

Old settings are ignored (not deleted)
New settings in .bctb-config.json take precedence
Safe to delete old bcTelemetryBuddy.* settings

Q: Can I use both old and new versions?

No - v1.0.0 only reads .bctb-config.json
Downgrading requires restoring old VSCode settings
Recommend staying on v1.0.0 (more stable, faster)

Usage Telemetry

BC Telemetry Buddy collects anonymous usage telemetry to improve the extension. This is separate from the Business Central telemetry data you query.

What's Collected

Extension lifecycle events (activation, deactivation)
Command usage (Run KQL Query, Setup Wizard, Save Query, etc.)
Feature adoption metrics (authentication methods, query types)
Error events with stack traces (for debugging)
Performance metrics (query execution time, MCP startup duration)

What's NOT Collected

Your KQL queries or query results
Customer names, company names, or business data
Personally identifiable information (PII)
Azure credentials or Application Insights connection strings
BC telemetry data you're analyzing

Privacy

All telemetry is anonymized with random installation IDs (stored in VS Code user profile, not workspace)
Installation IDs are per-user, not per-workspace (improves privacy)
Data stored in a separate Azure Application Insights resource
Used exclusively for product improvement and debugging
Follows Microsoft's privacy and data collection practices

Disable Telemetry

BC Telemetry Buddy respects VS Code's global telemetry setting:

{
  "telemetry.telemetryLevel": "off"
}

When VS Code telemetry is disabled, BC Telemetry Buddy collects no usage data.

For more details, see Telemetry Design Documentation.

License

MIT

BC Telemetry Buddy

waldoBC