BC Telemetry Buddy - VSCode Extension

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

🚀 Quick Start

1. Install from VSCode Marketplace (search for "BC Telemetry Buddy")
2. Run Setup Wizard: Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → BC Telemetry Buddy: Setup Wizard
3. 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
4. Query with Copilot:

   @workspace Show me all errors from BC in the last 24 hours
   @workspace What are the slowest operations this week?
   

5. Or use Command Palette: BC Telemetry Buddy: Run KQL Query

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

✨ Features

• 🧙 Setup Wizard: Step-by-step guided configuration with connection testing and validation
• 🔐 Flexible Authentication: Azure CLI (uses existing az login), Device Code, or Client Credentials
• 📊 Event Catalog & Schema Discovery: Browse available telemetry events and understand their customDimensions structure before querying
• 🤖 GitHub Copilot Integration: MCP tools enable Copilot to query telemetry, discover events, and generate KQL from natural language
• 💬 Natural Language Queries: Ask questions in plain English - backend matches patterns from saved queries to generate 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
• 📚 Query Library: Save queries organized by category; customer-specific queries auto-filed in Companies/[CompanyName]/ folders
• 🗺️ Tenant Mapping: Define friendly company names that map to Azure tenant IDs for customer queries
• 💾 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
• 📋 Rich Results: View query results in formatted tables with row counts and execution timing

📋 Commands

⚙️ 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

Manual Configuration

For manual configuration or to review settings, add to your workspace .vscode/settings.json:

Required Settings

{
  "bctb.mcp.connectionName": "Production BC Telemetry",
  "bctb.mcp.tenantId": "12345678-1234-1234-1234-123456789abc",
  "bctb.mcp.applicationInsights.appId": "your-app-insights-app-id",
  "bctb.mcp.kusto.clusterUrl": "https://ade.applicationinsights.io/subscriptions/<subscription-id>",
  "bctb.mcp.authFlow": "azure_cli"
}

Authentication Flows:

• azure_cli (recommended): Uses existing az login session - no additional credentials needed
• device_code: Browser-based authentication - prompts each time MCP starts
• client_credentials: Service principal with client ID + secret (secret stored in environment variable, not settings.json)

Optional Settings

{
  "bctb.queries.folder": "queries",
  "bctb.mcp.cache.enabled": true,
  "bctb.mcp.cache.ttlSeconds": 3600,
  "bctb.mcp.sanitize.removePII": false,
  "bctb.mcp.port": 52345
}

Tenant Mapping (Customer Queries)

Define friendly company names for customer-specific queries:

{
  "bctb.mcp.references": [
    {
      "name": "Contoso Corp",
      "type": "tenant-mapping",
      "tenantId": "contoso-tenant-id"
    }
  ]
}

When saving queries that filter on tenant/company, they're automatically organized:

queries/Companies/Contoso Corp/Errors/login-failures.kql

External References (KQL Examples)

Pull example queries from GitHub repos:

{
  "bctb.mcp.references": [
    {
      "name": "BC Samples",
      "type": "github",
      "url": "https://github.com/microsoft/BCTech/tree/master/samples/AppInsights",
      "enabled": true
    }
  ]
}

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

This extension manages an MCP (Model Context Protocol) backend server that:

MCP Server Modes

1. STDIO Mode (Copilot Integration): Automatically managed by VSCode for GitHub Copilot integration. The MCP server exposes tools that Copilot can call to query telemetry, discover events, and generate KQL.

2. HTTP Mode (Command Palette): Manually started via "Start MCP Server" command for direct queries through Command Palette commands.

Telemetry Workflow

1. Discovery First: Use Event Catalog to see what telemetry events exist (RT0001, RT0005, etc.)
2. Understand Schema: Check Event Schema to see available customDimensions fields for each event
3. Reuse Patterns: Search saved queries for proven patterns before writing new KQL
4. Execute Query: Run queries via Copilot, Command Palette, or CodeLens links in .kql files
5. Save for Team: Save useful queries to workspace library for team reuse

Authentication

• Authenticates to Azure using MSAL (Microsoft Authentication Library)
• Azure CLI: Uses cached credentials from az login (no additional auth required)
• Device Code: Interactive browser-based login (prompts each time)
• Client Credentials: Service principal for automation (requires client ID + secret)

Caching & Performance

• Query results cached locally in .vscode/.bctb/cache/ as JSON files
• Default TTL: 1 hour (configurable via bctb.mcp.cache.ttlSeconds)
• Manual cache management: Clear all caches or view statistics via Command Palette

Context & Auto-Generation

• Scans workspace queries/ folder for saved KQL patterns
• Optionally fetches external reference queries from GitHub repos
• When you ask natural language questions, backend matches patterns from saved queries to generate accurate KQL
• Copilot automatically uses MCP tools for systematic discovery → understanding → execution workflow

License

MIT