BC Telemetry Buddy - User Guide

May 8, 2026 · View on GitHub

Welcome to BC Telemetry Buddy, your intelligent companion for querying Business Central telemetry data directly from Visual Studio Code with GitHub Copilot and data-driven discovery tools.

🆕 What's New in v3.2.x

Community Knowledge Base (v3.2.0 / MCP v3.3.0+)

✅ Community Knowledge Base

Two-layer KB: community articles fetched from GitHub + optional local articles
Browse and filter KB articles directly from VSCode via BC Telemetry Buddy: Manage Knowledge Base
Per-article exclude checkboxes; disable/enable community KB entirely
KB status bar item shows live article count
MCP tools get_knowledge / save_knowledge let agents check proven KQL patterns before writing from scratch
Community contributions create a pre-filled GitHub issue (no fork required)

✅ Knowledge Base in Setup Wizard

"📚 Knowledge Base" quick-launch button on completion step

✅ Show Diagnostics command

BC Telemetry Buddy: Show Diagnostics generates a full diagnostic report (extension version, config state, MCP health) with one-click copy-to-clipboard

Previous highlights

✅ Extension Works Standalone

All Command Palette commands work without MCP server
MCP only needed for GitHub Copilot chat features

✅ Simplified Configuration

Single .bctb-config.json file replaces VSCode settings
Easier to share configurations across team

✅ Multi-Profile Support

Manage multiple customers/environments in one workspace
Quick profile switching via status bar dropdown

✅ MCP Optional for Chat

Chat participant (@bc-telemetry-buddy) requires separate MCP server
Install via: npm install -g bc-telemetry-buddy-mcp
Direct commands don't need MCP at all

See MIGRATION.md for migration details.

What is BC Telemetry Buddy?
Prerequisites
Installation
First-Time Setup
Authentication
Using the Extension
Querying Telemetry
Saving Queries
External References
GitHub Copilot Integration
Advanced Configuration
Migrating from v0.2.x
Troubleshooting
FAQ
Agentic Monitoring (Preview)

What is BC Telemetry Buddy?

BC Telemetry Buddy is a VSCode extension that makes it easy to query and analyze Business Central telemetry data from Application Insights.

For the current published versions and per-release notes, see packages/extension/CHANGELOG.md and packages/mcp/CHANGELOG.md.

Core Features

🔍 Direct KQL Execution: Write and run KQL queries instantly (no MCP needed)
💾 Query Library: Save and organize queries by category/customer
👁️ CodeLens Integration: Click "▶ Run Query" above queries in .kql files
📋 Rich Results Display: View formatted tables with row counts and timing
💡 Smart Caching: File-based caching with configurable TTL (default 1 hour)
🔐 Flexible Auth: VS Code (easiest, recommended), Azure CLI, Device Code, or Client Credentials
📊 Query Search: Find existing queries by keywords before writing new ones
🤖 GitHub Copilot Chat: Use @bc-telemetry-buddy participant for natural language queries (requires MCP)
📊 Event Catalog: Browse available BC telemetry events via MCP tools
🔎 Schema Discovery: Understand field structure automatically
🔄 Multi-Profile Support: Manage multiple customers with easy profile switching
📊 Profile Status Bar: See current profile and switch with one click

Architecture

Extension can execute queries directly via built-in TelemetryService (no MCP needed for Command Palette)
MCP optional, only required for GitHub Copilot chat features
Configuration in .bctb-config.json (workspace root)
MCP published as standalone NPM package: bc-telemetry-buddy-mcp
Supports both stdio (Copilot) and HTTP (Command Palette) modes
Community Knowledge Base with get_knowledge / save_knowledge MCP tools

Prerequisites

Before installing BC Telemetry Buddy, ensure you have:

Required

Visual Studio Code 1.96.0 or later
Node.js 18.0.0 or later
npm 9.0.0 or later
Azure Application Insights access for your Business Central environment
Azure tenant with permissions to authenticate

Optional (for GitHub Copilot Chat Integration)

GitHub Copilot subscription (for intelligent query generation with discovery tools)
MCP Server (bc-telemetry-buddy-mcp) - Setup Wizard can install this for you
Azure service principal (for unattended/automated scenarios)

Note: All Command Palette features work without MCP. MCP is only needed for the @bc-telemetry-buddy chat participant.

Installation

From VSCode Marketplace

Open Visual Studio Code
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Search for "BC Telemetry Buddy"
Click Install
Reload VSCode when prompted

From VSIX File

Download the .vsix file from the releases page
Open VSCode
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Click the ... menu → Install from VSIX...
Select the downloaded file
Reload VSCode

First-Time Setup

After installation, you have two options to configure BC Telemetry Buddy:

Option 1: Setup Wizard (Recommended) ⭐

The Setup Wizard provides a guided, 5-step process with validation and testing:

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run: BC Telemetry Buddy: Setup Wizard
Follow the steps:
- Step 1 - MCP & Workspace Check:
  - Wizard verifies you have a workspace folder open
  - Shows MCP server status (installed/not installed)
  - Offers to install or update MCP if needed (for Copilot Chat features)
  - You can skip MCP installation and use Command Palette features only
- Step 2 - Azure Configuration: Enter your tenant ID, Application Insights App ID, and Kusto cluster URL
- Step 3 - Authentication: Choose authentication method (Azure CLI recommended)
- Step 4 - Connection Testing: Wizard validates settings and runs a test query
- Step 5 - Complete: Settings are saved automatically, quick-start tips displayed
- Optional: Check "Install agents" to create .github/agents/*.agent.md files for enhanced Copilot Chat integration

Benefits: No manual JSON editing, one-click MCP installation, validation before saving, connection testing, clear error messages.

Option 2: Manual Configuration

If you prefer manual configuration or need to review/edit settings:

1. Open Workspace Settings

Open your workspace's .vscode/settings.json file (or create it if it doesn't exist).

2. Add Required Settings

Add the following configuration (replace placeholders with your actual values):

{
  "bctb.mcp.connectionName": "MyBC-Production",
  "bctb.mcp.tenantId": "your-azure-tenant-id",
  "bctb.mcp.authFlow": "device_code",
  "bctb.mcp.applicationInsights.appId": "your-app-insights-id",
  "bctb.mcp.kusto.clusterUrl": "https://your-cluster.kusto.windows.net",
  "bctb.mcp.port": 52345,
  "bctb.mcp.cache.enabled": true,
  "bctb.mcp.cache.ttlSeconds": 3600
}

3. Add to .gitignore (Recommended)

BC Telemetry Buddy creates these files in your workspace that should not be committed to version control:

# BC Telemetry Buddy generated files
.bctb-config.json           # Configuration file (may contain sensitive data)
.vscode/.bctb/              # Cache directory

Why ignore these files?

.bctb-config.json - May contain tenant IDs and environment-specific settings
.vscode/.bctb/ - Cache files that are regenerated automatically

Note: If you want to share configuration across your team, you can commit .bctb-config.json after removing any sensitive values and using placeholders. The extension stores the anonymous telemetry installation ID in VS Code's global storage (user profile), not in workspace files.

4. Get Your Application Insights Details

To find your Application Insights details:

Go to the Azure Portal (https://portal.azure.com)
Navigate to your Application Insights resource
Copy the Application ID from the Overview page
For Kusto cluster URL, use the BC telemetry endpoint:
- Default: https://ade.applicationinsights.io/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/microsoft.insights/components/{app-insights-name}
- You can find this in the Application Insights resource under "API Access"

Note: The Setup Wizard pre-fills the Kusto cluster URL format for you.

5. Install MCP Server (Optional)

What is MCP? The Model Context Protocol (MCP) server enables GitHub Copilot Chat integration. It's not required for Command Palette features like running queries, saving queries, or viewing results.

When do you need MCP?

Using @bc-telemetry-buddy chat participant in Copilot Chat
Natural language query generation
Event catalog discovery via chat
Advanced Copilot-powered features

Installation Options:

Option A: Via Setup Wizard (Recommended)

Run BC Telemetry Buddy: Setup Wizard from Command Palette
In Step 1, check the MCP status
Click "Install MCP" or "Update MCP" button if shown
Wait for installation to complete (~30 seconds)
MCP is now ready for Copilot Chat

Option B: Manual Installation

npm install -g bc-telemetry-buddy-mcp

Option C: First-Run Notification

If MCP is not installed, you'll see a notification on first use
Click "Open Setup Wizard" to install MCP
Or dismiss and install later when needed

Verification: Check MCP status anytime via Command Palette:

BC Telemetry Buddy: Setup Wizard

Step 1 shows: ✓ Installed (version X.Y.Z) or ✗ Not installed

The extension will:

Validate your settings
Start the MCP backend server
Show a confirmation message when ready
Display the server status in the Status Bar

Multi-Root Workspace Support

⚠️ BC Telemetry Buddy does NOT support multi-root workspaces.

Single-Root Workspaces (Supported)

BC Telemetry Buddy works with single-root workspaces only (one folder open). Settings are saved to .vscode/settings.json in the workspace folder.

Multi-Root Workspaces (Not Supported)

If you have multiple folders open in a multi-root workspace (.code-workspace file), the Setup Wizard will display an error and prevent configuration.

Why?

The MCP server requires settings to be stored in a folder's .vscode/settings.json file
Multi-root workspaces use workspace files (.code-workspace) which are not supported
This ensures clear, predictable configuration without ambiguity about which settings apply

Need different telemetry connections for different projects?

Open each project as a separate single-root workspace:

Close the multi-root workspace
Open each project individually (File → Open Folder)
Configure each workspace independently with its own telemetry connection
Switch between workspaces as needed

Example - Correct Setup:

❌ DON'T: Multi-root workspace
MyMultiRootWorkspace.code-workspace
├── ProjectA/
└── ProjectB/

✅ DO: Separate single-root workspaces
Workspace 1: C:\Projects\ProjectA\ (with .vscode/settings.json)
Workspace 2: C:\Projects\ProjectB\ (with .vscode/settings.json)

Authentication

BC Telemetry Buddy supports four authentication methods:

VS Code Integrated (Easiest - Recommended) ✨

Best for: Users who belong to a single Azure tenant

How it works:

Select "VS Code" as your authentication method in the Setup Wizard
VS Code prompts you to sign in with your Microsoft account (if not already signed in)
Tokens are managed automatically by VS Code - no installation or configuration needed

Benefits:

✅ Zero Prerequisites - No Azure CLI installation or other tools needed
✅ Built into VS Code - Uses VS Code's native Microsoft authentication
✅ Automatic Token Refresh - VS Code handles token expiration seamlessly
✅ Single Sign-On - Uses your existing Microsoft account
✅ Most Secure - Credentials never stored in files, managed by VS Code
✅ Perfect for Beginners - Just click and authenticate

To configure:

{
  "authFlow": "vscode_auth"
}

Note: No additional configuration needed - VS Code handles everything automatically.

⚠️ Important for Guest Users:

If you are a guest user in multiple Azure tenants, VS Code authentication may authenticate against your home tenant instead of the configured tenant. This is a limitation of VS Code's built-in Microsoft authentication provider, which doesn't support tenant-specific authority URLs.

Solution for guest users: Use Azure CLI or Device Code authentication instead, both of which support tenant-specific authentication through the authority URL (https://login.microsoftonline.com/{tenant-id}).

Azure CLI (Recommended for Guest Users)

Best for: Users who already have Azure CLI installed, and guest users in multiple tenants

How it works:

Login with Azure CLI, specifying the tenant: az login --tenant {tenant-id}
The MCP server uses your existing Azure CLI credentials automatically
No additional configuration needed - just set authFlow to azure_cli

Benefits:

✅ No Azure app registration required
✅ No device code prompts every time
✅ Uses your existing Azure session
✅ Works for all Azure resources you have access to
✅ Supports tenant-specific authentication - perfect for guest users

To configure:

{
  "authFlow": "azure_cli",
  "tenantId": "your-tenant-id"
}

For guest users:

# Login to the specific tenant you want to query
az login --tenant 557836c7-47a0-4a3a-af9b-f5af2dacc8b0

# Verify you're in the correct tenant
az account show

Note: You don't need to specify clientId or clientSecret when using Azure CLI auth. The tenantId is optional but recommended for documentation purposes.

Device Code Flow (Alternative for Guest Users)

Best for: When Azure CLI is not available, or for explicit browser-based auth. Also works for guest users.

How it works:

The MCP server initiates device code authentication
You'll see a notification with a code and URL
Open the URL in your browser
Enter the code and sign in with your Azure account
Grant permissions when prompted
Return to VSCode — you're authenticated!

Benefits:

✅ No Azure app registration required
✅ Supports tenant-specific authentication via authority URL
✅ Works for guest users when tenantId is configured

For guest users: Device Code flow uses the tenant-specific authority URL (https://login.microsoftonline.com/{tenant-id}) automatically when you specify tenantId in your configuration.

To configure:

{
  "bctb.mcp.authFlow": "device_code",
  "bctb.mcp.tenantId": "your-azure-tenant-id"
}

Client Credentials Flow

Best for: Service accounts, CI/CD pipelines, unattended scenarios, automation

How it works:

Create an Azure service principal with Application Insights read permissions
Configure the client ID and secret
The MCP server authenticates automatically on startup

To configure:

{
  "bctb.mcp.authFlow": "client_credentials",
  "bctb.mcp.tenantId": "your-azure-tenant-id",
  "bctb.mcp.clientId": "your-service-principal-client-id",
  "bctb.mcp.clientSecret": "your-client-secret"
}

⚠️ Security Note: For client credentials, consider using environment variables instead of storing secrets in settings:

{
  "bctb.mcp.clientId": "${env:BCTB_CLIENT_ID}",
  "bctb.mcp.clientSecret": "${env:BCTB_CLIENT_SECRET}"
}

Using the Extension

BC Telemetry Buddy provides several commands accessible from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Available Commands

Command	Description
`BC Telemetry Buddy: Setup Wizard`	Guided 5-step configuration wizard with validation
`BC Telemetry Buddy: Migrate Settings`	Migrate from old settings format to `.bctb-config.json`
`BC Telemetry Buddy: Start MCP Server`	Start the MCP backend server for chat features
`BC Telemetry Buddy: Run KQL Query`	Execute a KQL query directly (prompts for input)
`BC Telemetry Buddy: Run KQL From Document`	Execute query from current `.kql` file
`BC Telemetry Buddy: Install Agents`	Install agent definitions for GitHub Copilot
`BC Telemetry Buddy: Clear Cache`	Clear cached query results
`BC Telemetry Buddy: Show Cache Statistics`	View cache usage stats
`BC Telemetry Buddy: Switch Profile`	Switch between configured profiles
`BC Telemetry Buddy: Refresh Profile Status Bar`	Manually refresh profile status bar display
`BC Telemetry Buddy: Create Profile`	Create a new profile
`BC Telemetry Buddy: Set Default Profile`	Choose which profile loads on startup
`BC Telemetry Buddy: Manage Profiles`	Visual interface for all profile operations
`BC Telemetry Buddy: Manage Knowledge Base`	Browse and manage community / local KB articles
`BC Telemetry Buddy: Show Diagnostics`	Generate diagnostic report (version, config, MCP health)

Querying Telemetry

Using GitHub Copilot (Recommended) ⭐

GitHub Copilot provides the best experience with BC Telemetry Buddy through a systematic discovery workflow:

Open GitHub Copilot Chat (Ctrl+Alt+I / Cmd+Alt+I)

Type your question in plain English:

@workspace Show me all errors in the last 24 hours

Copilot automatically follows this workflow:
- Step 1 - Discover Events: Calls bctb_get_event_catalog to find relevant event IDs (e.g., RT0010 for errors)
- Step 2 - Understand Schema: Calls bctb_get_event_schema to see available customDimensions fields
- Step 3 - Check Saved Queries: Searches workspace queries for similar patterns
- Step 4 - Execute Query: Generates KQL and calls bctb_query_telemetry to run it
- Step 5 - Display Results: Shows formatted results with recommendations

For customer-specific queries, Copilot adds a step:

@workspace Show me errors for customer Contoso in the last 24 hours

Copilot calls bctb_get_tenant_mapping to map "Contoso" to its Azure tenant ID
Then proceeds with the workflow above, filtering by aadTenantId

Example queries:

"What are the slowest database operations today?"
"Show me failed web service calls in the last hour"
"How many sessions started in the past week for customer Fabrikam?"
"Which reports are causing the most timeouts?"
"What telemetry events are firing most frequently?"

Using KQL Directly

If you know KQL, you can query directly:

Via GitHub Copilot:

@workspace Run this KQL: requests | where success == false | take 10

Via Command Palette:

Run BC Telemetry Buddy: Run KQL Query
Enter your KQL query in the input box
View results in a rich webview with tables, charts, and recommendations

Via CodeLens in .kql files:

Create or open a .kql file in your workspace
Write your KQL query
Click the "▶ Run Query" CodeLens link that appears above the query
View results in the webview

Discovering Available Events

Before querying, you can discover what telemetry events exist:

Via Copilot:

@workspace What telemetry events are available?
@workspace Show me the schema for event RT0005

Manual Discovery: The extension exposes these tools to Copilot:

Event Catalog (bctb_get_event_catalog): Lists recent BC telemetry event IDs with descriptions, frequency, and Learn URLs
Event Schema (bctb_get_event_schema): Shows available customDimensions fields for a specific event ID

This helps you understand:

What events are firing in your environment
What data each event contains (customDimensions fields)
How frequently events occur
Microsoft Learn documentation for each event type

Working with Customers (Tenant Mapping)

BC Telemetry Buddy includes powerful features for managing multi-customer environments:

Automatic Company Discovery

When you query telemetry, the extension can discover all companies/customers in your Application Insights:

Via Copilot:

@workspace What companies do I have telemetry for?

Copilot calls bctb_get_tenant_mapping which:

Scans recent telemetry (default: last 10 days)
Extracts unique company names and their Azure tenant IDs
Returns a mapping table for easy reference

Customer-Specific Queries

When asking about a specific customer:

@workspace Show me errors for customer Contoso in the last week

Copilot automatically:

Calls bctb_get_tenant_mapping to find Contoso's tenant ID
Generates KQL with: | where tostring(customDimensions.aadTenantId) == "{tenant-id}"
Executes the query and returns customer-specific results

Saving Customer Queries

When you save a query that filters by tenant/company, it's automatically organized:

Generic queries → queries/[Category]/[QueryName].kql
Customer queries → queries/Companies/[CompanyName]/[Category]/[QueryName].kql

This keeps customer-specific queries isolated and easy to find.

External References

Improve query generation by configuring external KQL sources:

Adding References

In your .vscode/settings.json:

{
  "bctb.mcp.references": [
    {
      "name": "BC Telemetry Samples",
      "type": "github",
      "url": "https://github.com/microsoft/BCTech/tree/master/samples/AppInsights",
      "enabled": true
    },
    {
      "name": "Waldo's Blog",
      "type": "web",
      "url": "https://www.waldo.be/category/dynamics-nav-business-central/",
      "enabled": true
    }
  ]
}

Reference Types

github: Fetches KQL examples from GitHub repositories
web: Fetches KQL from blog posts and documentation (v2 feature)

How It Works

When Copilot generates KQL queries:

Copilot analyzes your question and determines which discovery tools to use
MCP searches your saved .kql files for similar patterns
MCP fetches and searches configured external references
All matching examples are returned to Copilot as context
Copilot generates the final KQL using the most relevant examples and discovered field structure

Benefits:

Better query accuracy with more context
Learn from community examples
Leverage official Microsoft samples
Share knowledge across your team

Knowledge Base

BC Telemetry Buddy includes a two-layer Community Knowledge Base that ships curated KQL patterns and investigation playbooks. Agents automatically check the KB before writing KQL from scratch, reducing wasted tokens and delivering more accurate queries.

Layers

Layer	Source	Description
Community	GitHub (`/knowledge-base/`)	Curated articles maintained by the BC community. Fetched at startup, cached for offline use.
Local	`{workspace}/.vscode/.bctb/knowledge/`	Your team's private patterns — never shared.

Browsing the Knowledge Base

Open Command Palette and run BC Telemetry Buddy: Manage Knowledge Base to:

Browse all articles (community + local) with category and source filters
Free-text search matching title, tags, and event IDs
Exclude individual community articles per workspace
Disable or re-enable community KB entirely

A status bar item $(book) KB: N articles shows the live article count.

Searching the KB from Copilot Chat

The get_knowledge MCP tool lets agents search the KB before writing KQL:

@workspace What patterns exist for investigating lock timeouts?
@workspace Check the KB for RT0012 event patterns

Contributing Back

If you discover a useful investigation pattern, the save_knowledge tool (agent-driven) can:

Save locally (target: local) — writes to your workspace knowledge folder
Contribute to community (target: community) — opens a pre-filled GitHub issue; no fork or branch required

Knowledge Base Configuration

Optional knowledgeBase block in .bctb-config.json:

{
  "knowledgeBase": {
    "enabled": true,
    "source": "all",
    "exclude": [],
    "autoRefresh": true,
    "cacheOnly": false,
    "githubToken": ""
  }
}

Field	Default	Description
`enabled`	`true`	Enable/disable community KB entirely
`source`	`"all"`	`"community"`, `"local"`, or `"all"`
`exclude`	`[]`	Array of article file names to skip
`autoRefresh`	`true`	Fetch latest community articles on startup
`cacheOnly`	`false`	Use only cached articles (no network calls)
`githubToken`	`""`	Optional PAT (`public_repo` scope) needed only if you hit GitHub rate limits

GitHub Copilot Integration

BC Telemetry Buddy provides multiple ways to interact with GitHub Copilot:

1. Chat Participant: `@bc-telemetry-buddy`

Use the chat participant for expert BC telemetry analysis with MCP tool integration:

@bc-telemetry-buddy show me all errors from the last 24 hours
@bc-telemetry-buddy analyze performance for customer Contoso

Slash Commands (informational - no tool execution):

/patterns - Common KQL patterns and best practices
/events - BC event types and categories
/errors - Error analysis techniques
/performance - Performance analysis guidance
/customer - Customer-specific analysis workflow
/explain - Explain concepts or provide examples

The chat participant automatically distinguishes between:

Information requests (slash commands, "what is", "explain") → Provides knowledge directly
Data requests ("show me", "analyze", customer queries) → Executes MCP tools immediately

2. Agent: `#BCTelemetryBuddy` (Optional Enhanced Mode)

Activate agent for comprehensive BC telemetry expert guidance:

#BCTelemetryBuddy show me all errors from last 24 hours
#BCTelemetryBuddy analyze performance issues for Contoso

Installation Options:

Option 1: Check "Install agents" in Setup Wizard Step 5 (automatic)
Option 2: Run command BC Telemetry Buddy: Install Agents from Command Palette (manual)

After installation, reload VS Code to activate. Agent files are created at .github/agents/*.agent.md.

Agent vs Chat Participant:

Chat Participant (@bc-telemetry-buddy): Per-message expert assistance, executes MCP tools on demand
Agent (#BCTelemetryBuddy): Entire conversation context with expert guidance, KQL patterns, systematic workflow

Customization: You can edit .github/agents/*.agent.md files to customize:

YAML frontmatter: description, tools array
Markdown content: System instructions, patterns, workflows
Reload VS Code after changes

3. Workspace Agent: `@workspace`

Use @workspace for general queries that follow systematic discovery workflow:

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

Available MCP Tools

BC Telemetry Buddy exposes 11 MCP tools to GitHub Copilot (accessible via all three methods above):

Available Tools

Tool	Description	When Copilot Uses It
Discovery Tools ⭐
`bctb_get_event_catalog`	List BC telemetry events with descriptions, frequency, and Learn URLs. Optional `includeCommonFields` analyzes customDimensions field prevalence across events	When you ask questions like "what events are available" or "show me common fields across events"
`bctb_get_event_field_samples`	Analyze customDimensions structure for a specific event ID - returns field names, types, occurrence rates, sample values	Before writing queries for a specific event to discover exact field structure
`bctb_get_event_schema`	Get detailed schema information for a specific event ID	After discovering relevant events, to understand patterns and related events
`bctb_get_categories`	Get available event categories (Lifecycle, Performance, Security, Error, Integration, Configuration, Custom)	To understand event categorization and filter by category
`bctb_get_tenant_mapping`	Map company names to Azure tenant IDs and environment names	When you mention a specific customer/company name in your query
Query Execution
`bctb_query_telemetry`	Execute KQL queries against telemetry (use discovery tools first for best results)	For every telemetry query (after using discovery tools to understand structure)
Query Library
`bctb_get_saved_queries`	List saved queries (with optional tag filtering)	To find existing patterns before generating new queries
`bctb_search_queries`	Search saved queries by keywords	When your question matches common patterns (errors, slow, login, etc.)
`bctb_save_query`	Save a successful query for future reference	When you ask to save a query or Copilot recommends saving
`bctb_get_external_queries`	Fetch KQL examples from configured external references (GitHub repos, blogs)	For additional context when generating queries
Analysis & Recommendations
`bctb_get_recommendations`	Analyze results and provide actionable insights	After query execution, to suggest next steps or optimizations
Knowledge Base
`get_knowledge`	Search community + local KB articles by `eventId`, `category`, `tags`, or free-text `search`. Returns proven KQL patterns.	Before writing KQL from scratch — check existing patterns first
`save_knowledge`	Save an investigation pattern locally or contribute it to the community (creates a GitHub issue).	When a successful investigation yields reusable patterns

Usage Examples

Query telemetry:

@workspace Show me all page view events from the last hour

List saved queries:

@workspace What saved queries do I have for performance analysis?

Save a query:

@workspace Save this query as "Error Summary" with tags: errors, monitoring

Get recommendations:

@workspace Analyze these errors and recommend fixes

Discovery-First Workflow (Recommended) ⭐

Version 1.0.0 introduces a data-driven discovery approach instead of unreliable natural language translation. Here's the recommended workflow:

1. Discover available events:

@workspace What error events are available in the last 7 days?

Copilot uses get_event_catalog with status="error" to show actual events in your data.

2. Analyze field structure for a specific event:

@workspace Show me the field structure for event RT0005

Copilot uses get_event_field_samples to discover:

All customDimensions field names
Data types (string, number, boolean, datetime, JSON)
Occurrence rates (% of events with each field)
Sample values for each field
Ready-to-use KQL template

3. Write precise KQL query:

@workspace Query RT0005 events where executionTimeInMs > 1000

Copilot uses discovered fields to generate accurate KQL with correct field names.

4. Analyze common fields across multiple events:

@workspace Show me common fields across all error events

Copilot uses get_event_catalog with includeCommonFields=true to categorize fields by prevalence:

Universal fields (80%+ prevalence): Safe for cross-event queries
Common fields (50-79%): Frequently available
Occasional fields (20-49%): Event-type specific
Rare fields (<20%): Highly specific

Benefits of this approach:

✅ No guessing about field names or structure
✅ Accurate queries based on real telemetry data
✅ Discover event-specific vs. universal fields
✅ Works with any BC version, custom events, partner extensions
✅ Adapts automatically as your telemetry evolves

Context Awareness

Copilot automatically uses:

✅ Your saved .kql queries
✅ Configured external references (GitHub, docs)
✅ Query execution history (cached results)
✅ Workspace-specific settings

This context helps Copilot generate more accurate, relevant KQL queries.

Advanced Configuration

Multi-Profile Management

BC Telemetry Buddy supports managing multiple customers/environments in a single workspace through profile management.

Creating and Managing Profiles

Create a new profile:

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run: BC Telemetry Buddy: Create Profile
Or: BC Telemetry Buddy: Manage Profiles (visual wizard)

Available commands:

BC Telemetry Buddy: Create Profile - Create a new profile from scratch
BC Telemetry Buddy: Switch Profile - Switch between configured profiles
BC Telemetry Buddy: Set Default Profile - Choose which profile loads on startup
BC Telemetry Buddy: Manage Profiles - Visual interface for all profile operations (create, edit, delete)

Profiles are stored in .bctb-config.json in your workspace root.

Understanding Profile Switching

What does "Switch Profile" do?

When you switch profiles via the status bar dropdown or BC Telemetry Buddy: Switch Profile command:

✅ Affects Extension Commands:

BC Telemetry Buddy: Run KQL Query
BC Telemetry Buddy: Run KQL From Document
CodeLens "▶ Run Query" in .kql files
Status bar queries
All direct query execution through the extension

✅ Also affects Chat Participant / MCP Server:

When you switch profiles, the MCP server is notified and switches its active connection
@bc-telemetry-buddy chat queries will run against the newly selected profile
Chat can also use the switch_profile tool to switch profiles dynamically based on your question
Use list_profiles in chat to see all available profiles and which one is active

Example Scenario:

Extension current profile: CustomerA (via status bar)
You switch to CustomerB via status bar or Switch Profile command

Result:
- Extension commands (Run KQL Query) use CustomerB credentials
- Chat (@bc-telemetry-buddy) also uses CustomerB credentials
- Both stay in sync automatically

Dynamic profile switching in chat:

Chat can also switch profiles on the fly using the switch_profile tool
If you ask "show me errors for CustomerB", chat can call switch_profile to switch before querying
Use list_profiles to see all available profiles and the currently active one

When to switch profiles:

You're switching focus to a different customer/environment
You want Run KQL Query to use different credentials
You want CodeLens queries to execute against different data
The status bar shows which profile extension commands will use

Profile inheritance: Profiles can inherit common settings from a base profile to reduce duplication. See .bctb-config.json schema for details.

Profile Configuration Example

{
  "defaultProfile": "CustomerA",
  "profiles": {
    "CustomerA": {
      "workspacePath": "${workspaceFolder}",
      "queriesFolder": "queries/CustomerA",
      "connectionName": "CustomerA-Production",
      "authFlow": "azure_cli",
      "tenantId": "customer-a-tenant-id",
      "applicationInsightsAppId": "app-id-a",
      "kustoClusterUrl": "https://ade.applicationinsights.io/...",
      "references": [
        {
          "name": "BC Telemetry Samples",
          "type": "github",
          "url": "https://github.com/microsoft/BCTech/tree/master/samples/AppInsights",
          "enabled": true
        }
      ]
    },
    "CustomerB": {
      "workspacePath": "${workspaceFolder}",
      "queriesFolder": "queries/CustomerB",
      "connectionName": "CustomerB-Test",
      "authFlow": "device_code",
      "tenantId": "customer-b-tenant-id",
      "applicationInsightsAppId": "app-id-b",
      "kustoClusterUrl": "https://ade.applicationinsights.io/..."
    }
  }
}

Caching

Control query result caching:

{
  "bctb.mcp.cache.enabled": true,
  "bctb.mcp.cache.ttlSeconds": 3600  // 1 hour
}

Cache is stored in .vscode/.bctb/cache/ (automatically excluded from git).

PII Sanitization

Enable optional PII redaction (opt-in):

{
  "bctb.mcp.sanitize.removePII": true
}

When enabled, the MCP will redact:

Email addresses
IP addresses (partial)
GUIDs (partial)
Common PII patterns

⚠️ Note: Business Central telemetry should not contain PII, but this provides an extra safety layer.

Retry Configuration

Configure how many times Copilot retries failed queries:

{
  "bctb.agent.maxRetries": 3
}

Multiple Workspaces

Each workspace can have its own configuration:

Workspace A (Production): Points to production Application Insights
Workspace B (Test): Points to test environment
Workspace C (Customer): Points to customer's tenant

Just configure different settings in each workspace's .vscode/settings.json.

Custom Port

If port 52345 is already in use:

{
  "bctb.mcp.port": 52346,
  "bctb.mcp.url": "http://localhost:52346"
}

Settings Reference

All extension settings with their types, defaults, and descriptions:

Profile Settings

Setting	Type	Default	Description
`bctb.currentProfile`	string	(none)	Name of the currently active profile (resource scope)

MCP Connection Settings

Setting	Type	Default	Description
`bctb.mcp.connectionName`	string	""	Display name for this connection
`bctb.mcp.tenantId`	string	""	Azure Active Directory tenant ID
`bctb.mcp.clientId`	string	""	Service principal client ID (for client_credentials flow)
`bctb.mcp.authFlow`	enum	"device_code"	Authentication method: `azure_cli`, `device_code`, or `client_credentials`
`bctb.mcp.applicationInsights.appId`	string	""	Application Insights application ID
`bctb.mcp.kusto.clusterUrl`	string	""	Kusto cluster URL (e.g., https://ade.applicationinsights.io/...)
`bctb.mcp.port`	number	52345	Port for MCP server HTTP endpoint
`bctb.mcp.url`	string	"http://localhost:52345"	Full URL for MCP server
`bctb.mcp.preferGlobal`	boolean	false	Prefer globally-installed MCP server over bundled version

Cache Settings

Setting	Type	Default	Description
`bctb.mcp.cache.enabled`	boolean	true	Enable query result caching
`bctb.mcp.cache.ttlSeconds`	number	3600	Cache time-to-live in seconds (default: 1 hour)

Security Settings

Setting	Type	Default	Description
`bctb.mcp.sanitize.removePII`	boolean	false	Enable optional PII redaction (email, IP, GUID)

Query Settings

Setting	Type	Default	Description
`bctb.queries.folder`	string	"queries"	Workspace folder path for saved queries

Agent Settings

Setting	Type	Default	Description
`bctb.agent.maxRetries`	number	3	Maximum retry attempts for failed queries in Copilot chat

External References Settings

Setting	Type	Default	Description
`bctb.mcp.references`	array	[]	External GitHub repositories for query examples (array of reference objects)

Reference Object Schema:

{
  "name": "string",        // Display name for the reference
  "type": "github",        // Only "github" supported currently
  "url": "string",         // GitHub repo URL
  "enabled": true/false    // Enable/disable this reference
}

Example Complete Configuration:

{
  "bctb.currentProfile": "CustomerA",
  "bctb.mcp.connectionName": "CustomerA Production",
  "bctb.mcp.tenantId": "12345678-1234-1234-1234-123456789abc",
  "bctb.mcp.authFlow": "azure_cli",
  "bctb.mcp.applicationInsights.appId": "your-app-insights-id",
  "bctb.mcp.kusto.clusterUrl": "https://ade.applicationinsights.io/subscriptions/...",
  "bctb.mcp.port": 52345,
  "bctb.mcp.url": "http://localhost:52345",
  "bctb.mcp.preferGlobal": false,
  "bctb.mcp.cache.enabled": true,
  "bctb.mcp.cache.ttlSeconds": 3600,
  "bctb.mcp.sanitize.removePII": false,
  "bctb.queries.folder": "queries",
  "bctb.agent.maxRetries": 3,
  "bctb.mcp.references": [
    {
      "name": "BC Telemetry Samples",
      "type": "github",
      "url": "https://github.com/microsoft/BCTech/tree/master/samples/AppInsights",
      "enabled": true
    }
  ]
}

Troubleshooting

Automatic MCP Updates

Keep your MCP up to date automatically!

The extension checks for MCP updates in the background:

Automatic checks: Every 24 hours (silent, won't interrupt work)
Smart notifications: Only notifies once per day when updates are available
Manual check: Run BC Telemetry Buddy: Check for MCP Updates from Command Palette
One-click update: Click "Update Now" in the notification to install the latest version
View changes: Click "View Changes" to see what's new on npm

Manual Update:

npm install -g bc-telemetry-buddy-mcp@latest

MCP Server Won't Start

Symptoms: Error when running "Start MCP Server" command

Solutions:

Check that Node.js 18+ is installed: node --version
Verify workspace settings are configured correctly
Check if port 52345 is available (or configure a different port)
Check the Output panel (View → Output → "BC Telemetry Buddy")

Authentication Failed

Symptoms: "Authentication required" error when querying

Solutions:

For device_code flow:

Run BC Telemetry Buddy: Start MCP Server again
Complete the device code authentication in your browser
Ensure you have permissions to access Application Insights

For client_credentials flow:

Verify client ID and secret are correct
Check service principal has "Reader" role on Application Insights
Confirm tenant ID is correct

No Results Returned

Symptoms: Query executes but returns empty results

Solutions:

Check if your Application Insights has data for the time range
Verify the KQL query syntax is correct
Try a simpler query first: requests | take 10
Check if you have permissions to read telemetry data

Copilot Doesn't Use Saved Queries

Symptoms: Generated queries ignore saved examples

Solutions:

Ensure queries are saved in .vscode/bctb/queries/ folder
Check query files follow the correct format (with comment headers)
Verify MCP server is running
Try using discovery tools first (get_event_catalog, get_event_field_samples) to understand available events and fields

External References Not Working

Symptoms: GitHub references not being fetched

Solutions:

Check internet connectivity
Verify GitHub URLs are correct and public
Check rate limiting (60 requests/hour for unauthenticated)
Look for errors in Output panel

Using with Other MCP Clients

BC Telemetry Buddy's MCP server is independent and can be used with any MCP-compatible client, not just the VSCode extension.

Supported MCP Clients

VSCode Extension (this extension) - Full integration with GitHub Copilot
Claude Desktop - Anthropic's desktop app with MCP support
Other MCP Clients - Any tool that supports the Model Context Protocol

Configuration for Claude Desktop / Other MCP Clients

To use BC Telemetry Buddy MCP server with Claude Desktop or other standalone MCP clients:

1. Install the Package

npm install -g bc-telemetry-buddy-mcp

2. Configure Environment Variables

Add the following to your MCP client's configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "bc-telemetry-buddy": {
      "command": "node",
      "args": ["/path/to/bctb-mcp/dist/launcher.js"],
      "env": {
        "BCTB_WORKSPACE_PATH": "/path/to/your/workspace",
        "BCTB_TENANT_ID": "your-azure-tenant-id",
        "BCTB_APP_INSIGHTS_ID": "your-app-insights-id",
        "BCTB_KUSTO_URL": "https://ade.applicationinsights.io/subscriptions/...",
        "BCTB_AUTH_FLOW": "azure_cli",
        "BCTB_CACHE_ENABLED": "true",
        "BCTB_CACHE_TTL": "3600",
        "BCTB_REMOVE_PII": "false"
      }
    }
  }
}

3. Authentication Options

Azure CLI (Recommended for standalone use):

Set BCTB_AUTH_FLOW=azure_cli
Run az login before starting your MCP client
Uses your existing Azure CLI session

Device Code Flow:

Set BCTB_AUTH_FLOW=device_code
Follow device code prompt when MCP server starts
No Azure app registration required

Client Credentials:

Set BCTB_AUTH_FLOW=client_credentials
Requires BCTB_CLIENT_ID and BCTB_CLIENT_SECRET
Best for automated/unattended scenarios

4. Available Tools

The MCP server exposes these tools to your client:

query_telemetry - Execute KQL queries
get_event_catalog - Discover available events
get_event_field_samples - Analyze event field structure
get_saved_queries - Access saved query library
save_query - Save new queries
search_queries - Find queries by tags/keywords
get_external_queries - Retrieve reference queries
And more...

Differences from VSCode Extension

When using with standalone MCP clients:

Available:

✅ All query and discovery tools
✅ Authentication flows
✅ Caching and performance features
✅ Saved queries and external references

Not Available:

❌ Setup Wizard UI (manual configuration required)
❌ CodeLens integration
❌ Results webview
❌ Command Palette commands

Graceful Degradation

The MCP server will start successfully even in workspaces without BC Telemetry Buddy configuration. If configuration is incomplete, you'll receive helpful error messages when attempting to query:

BC Telemetry Buddy MCP server configuration is incomplete.
- If using VSCode: Run "BC Telemetry Buddy: Setup Wizard" from Command Palette
- If using Claude Desktop or other MCP clients: Configure environment variables in your MCP settings

This allows the extension to be installed globally without causing startup failures in non-BC workspaces.

Migrating from v0.2.x

If you're upgrading from BC Telemetry Buddy v0.2.x, this section explains what changed and how to migrate smoothly.

What Changed in v1.2.10?

Aspect	v0.2.x (Old)	v1.2.10 (New)
MCP Server	Bundled with extension	Separate optional package
Direct Commands	Required MCP running	Built-in TelemetryService
Configuration	Scattered VSCode settings (`bcTelemetryBuddy.*`)	Single `.bctb-config.json` file
Chat Features	Bundled automatically	Requires `npm install -g bc-telemetry-buddy-mcp`
Performance	HTTP mode required	Direct execution (faster)
Setup	MCP auto-start on commands	Extension ready after Setup Wizard

Migration Path

Automatic Migration (Recommended)

When you first launch v1.2.10 with existing v0.2.x settings:

Detection: Extension detects old bcTelemetryBuddy.* settings in .vscode/settings.json
Notification: Shows prompt: "Migrate to new configuration format?"
One-Click Migration: Click "Migrate Settings"
Automatic Conversion: Extension creates .bctb-config.json with your settings
Immediate Use: All commands work right away
Optional MCP: Install later if you want chat features

What Gets Migrated:

✅ Connection name
✅ Tenant ID
✅ Application Insights App ID
✅ Kusto cluster URL
✅ Auth flow settings
✅ Cache configuration
✅ Query folder location
✅ PII sanitization settings
✅ External references

What Happens to Old Settings:

Old settings remain in .vscode/settings.json (not deleted)
Extension ignores old settings (reads .bctb-config.json instead)
Safe to delete old settings manually after migration

Manual Migration

If automatic migration didn't work or you prefer manual setup:

Note Your Current Settings

Check .vscode/settings.json for your configuration:

{
  "bcTelemetryBuddy.connectionName": "Production",
  "bcTelemetryBuddy.appInsights.appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "bcTelemetryBuddy.kusto.clusterUrl": "https://ade.applicationinsights.io/...",
  "bcTelemetryBuddy.authFlow": "azure_cli"
}

Run Setup Wizard
- Command Palette → BC Telemetry Buddy: Setup Wizard
- Enter your settings when prompted
- Wizard validates and creates .bctb-config.json

Verify Configuration

Check .bctb-config.json in workspace root:

{
  "connectionName": "Production",
  "authFlow": "azure_cli",
  "applicationInsightsAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "kustoClusterUrl": "https://ade.applicationinsights.io/...",
  "workspacePath": "${workspaceFolder}",
  "queriesFolder": "queries",
  "cacheEnabled": true,
  "cacheTTLSeconds": 3600
}

Test Direct Commands
- Run: BC Telemetry Buddy: Run KQL Query
- Should work immediately without installing MCP
(Optional) Clean Up Old Settings
- Remove bcTelemetryBuddy.* entries from .vscode/settings.json
- Extension no longer reads these

Installing MCP for Chat Features

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

Option 1: Extension Prompt

Use any command that would benefit from chat
Extension shows: "Install MCP Server for chat features?"
Click "Install"
Extension runs npm install -g bc-telemetry-buddy-mcp in background
Shows completion notification

Option 2: Manual Install

# Install globally
npm install -g bc-telemetry-buddy-mcp

# Verify installation
bctb-mcp --version

Verify Chat Works

Open GitHub Copilot Chat
Type: @bc-telemetry-buddy show me the event catalog
Copilot should respond with BC telemetry events

Troubleshooting Migration

Q: Migration notification doesn't appear?

Check if .bctb-config.json already exists (migration skipped)
Manually run: BC Telemetry Buddy: Migrate Settings
Or use Setup Wizard to create fresh config

Q: Commands don't work after migration?

Verify .bctb-config.json exists in workspace root
Check file has valid JSON (no syntax errors)
Run Setup Wizard to validate configuration
Check Output panel for error messages

Q: Chat participant not found after installing MCP?

Reload VSCode window: Developer: Reload Window
Verify MCP installed: bctb-mcp --version in terminal
Check extension detected MCP: Look for "Using globally-installed MCP" in Output

Q: Can I use both v0.2.x and v1.2.10 configurations?

No - v1.2.10 only reads .bctb-config.json
Old bcTelemetryBuddy.* settings ignored
Choose one version and stick with it

Q: How do I rollback to v0.2.x?

Uninstall v1.2.10 from Extensions
Install v0.2.x from Marketplace (may need to download VSIX)
Restore .vscode/settings.json with old settings
Delete .bctb-config.json (optional, v0.2.x ignores it)

Q: My saved queries still work after migration?

Yes! Query folder location migrated automatically
Queries remain in same location (queries/ by default)
No changes needed to existing .kql files

Telemetry & Privacy

BC Telemetry Buddy includes usage telemetry to help improve the extension. This section explains what data is collected, how it's used, and how to control it.

What is Usage Telemetry?

Usage telemetry tracks how you use the extension (e.g., which commands you run, errors encountered). This is completely separate from Business Central telemetry data querying - we never collect your BC telemetry data or query results.

What Data is Collected?

Collected:

Extension version and installation ID (pseudonymous, user-resettable)
Command invocations (e.g., "Run KQL Query", "Clear Cache")
Feature usage (e.g., profile switching, query saving)
Performance metrics (query execution time, dependency calls)
Error information (sanitized error messages, stack traces from extension code only)
VS Code telemetry level setting

Never Collected:

Your Business Central telemetry data or query results
Kusto queries or KQL code you write
Personal information (names, emails, IP addresses)
File paths containing usernames
Azure credentials, connection strings, or secrets
Workspace-specific data (customer names, project names)

Data Sanitization

All telemetry data is automatically sanitized:

File paths: Replaced with <user-path> or <repo> placeholders
Credentials: Connection strings, passwords, tokens redacted as <redacted>
Email addresses: Replaced with <email> placeholder
IP addresses: Replaced with <ip> placeholder
GUIDs: Replaced with <guid> placeholder (except installation IDs)
Stack traces: Only extension code included, third-party code excluded

Each installation is assigned a pseudonymous installation ID (a random UUID) to track sessions without identifying you personally. This ID:

Is stored in VS Code's global storage (in your user profile, not in workspace files)
Can be reset anytime by running "BC Telemetry Buddy: Reset Telemetry ID" command
Does not contain personal information
Is user-wide (not workspace-specific)

VS Code Telemetry Levels

Usage telemetry respects your VS Code telemetry setting (telemetry.telemetryLevel):

Level	What's Tracked
off	Nothing (telemetry completely disabled)
crash	Only unhandled exceptions/crashes
error	Only errors and exceptions
all	All events, errors, and usage data (default)

To change your VS Code telemetry level:

Open Settings (Ctrl+, or Cmd+,)
Search for telemetry.telemetryLevel
Choose your preferred level

How to Disable Usage Telemetry

Method 1: VS Code Telemetry Settings (Recommended)

Open Settings (Ctrl+,)
Search for telemetry.telemetryLevel
Set to "off"

Method 2: Per-Workspace Configuration Add to your .bctb-config.json:

{
  "telemetry": {
    "enabled": false
  }
}

Method 3: Environment Variable Set AI_CONNECTION_STRING to empty (removes telemetry endpoint):

# In .env file or environment
AI_CONNECTION_STRING=

Reset Your Installation ID

You can reset your pseudonymous installation ID at any time:

Command Palette:

Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Run "BC Telemetry Buddy: Reset Telemetry ID"
Confirm the reset

This generates a new anonymous ID, disassociating future telemetry from your previous sessions.

Rate Limiting (Cost Protection)

Telemetry has built-in rate limits to prevent runaway costs:

Extension: Max 1000 events/session, 100 events/minute
MCP: Max 2000 events/session, 200 events/minute
Identical errors: Max 10 per session (then throttled with cooldown)

Where is Data Sent?

Usage telemetry data is sent to Azure Application Insights (West Europe region), operated by the extension author. Data is:

Stored in Azure Application Insights (Microsoft-managed)
Retained for 90 days
Used only for improving BC Telemetry Buddy
Not shared with third parties
Not used for marketing or tracking

BC Telemetry Buddy is GDPR-compliant:

Right to reset ID: Run "Reset Telemetry ID" command anytime
Right to opt-out: Disable telemetry via VS Code settings
Data minimization: Only pseudonymous, sanitized data collected
Purpose limitation: Data used only for extension improvement
Data retention: 90 days maximum in Azure Application Insights

Open Source Transparency

All telemetry code is open source and auditable:

Telemetry implementation: packages/shared/src/usageTelemetry.ts
Sanitization logic: packages/shared/src/usageTelemetryUtils.ts
Extension integration: packages/extension/src/services/extensionTelemetry.ts
MCP integration: packages/mcp/src/mcpTelemetry.ts

View the code: GitHub Repository

Questions About Telemetry?

If you have concerns or questions about usage telemetry:

Open an issue: GitHub Issues
Start a discussion: GitHub Discussions

FAQ

Do I need GitHub Copilot to use this extension?

No! You can use the extension without Copilot by:

Running BC Telemetry Buddy: Run KQL Query command to execute KQL directly
Writing KQL queries directly in saved .kql files and using CodeLens to run them
Using the extension's commands to query and save queries

However, Copilot integration provides the best experience for intelligent query generation with automatic discovery workflows and contextual assistance.

Will this work with GitHub Copilot Free?

Yes! BC Telemetry Buddy uses your existing GitHub Copilot license (Free, Pro, or Enterprise). No additional costs.

Can I use this with multiple Business Central environments?

Yes! Each VSCode workspace can connect to a different Application Insights instance. Create separate workspace folders for each environment.

Are my queries and telemetry data sent to OpenAI?

When using GitHub Copilot with BC Telemetry Buddy:

Your questions to Copilot are sent to Copilot's LLM
Saved query metadata (comments, descriptions) is sent as context
External reference content (KQL examples) is sent as context
Discovered event/field information (from discovery tools) is sent as context
Raw telemetry data is NOT sent to the LLM (only query results summary if you ask for analysis)

The MCP backend runs locally and only sends what's necessary for query generation.

Can I commit my `.kql` files to git?

Yes! Saved queries (.kql files) are designed to be committed and shared with your team. They:

Should NOT contain PII or sensitive data
Provide valuable knowledge base for your team
Help everyone generate better queries

Do NOT commit:

.vscode/.bctb/cache/ (cached results)
.vscode/.bctb/references-cache/ (external references cache)
Workspace settings with secrets

How do I update the extension?

VSCode will automatically notify you when updates are available. You can also:

Go to Extensions
Find "BC Telemetry Buddy"
Click Update if available

How do I uninstall?

Go to Extensions
Find "BC Telemetry Buddy"
Click Uninstall
Optionally delete .vscode/bctb/ folder from your workspace

Where can I get help?

📖 Documentation: GitHub Repository
🐛 Report Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Agentic Monitoring (Preview)

Note: Agentic Monitoring is currently a preview feature. APIs and behavior may change in future releases.

BC Telemetry Buddy MCP includes a built-in agent runtime for autonomous, scheduled telemetry monitoring. Agents run via CI/CD pipelines (GitHub Actions, Azure DevOps) or locally, query telemetry with LLM reasoning, track issues across runs, and take actions like sending Teams notifications or triggering pipelines — all without manual intervention.

What an Agent Is

An agent = instruction (natural language) + accumulated state + MCP tools + LLM reasoning

You write a plain-text instruction.md describing what to monitor: which events, what thresholds, when to escalate. The agent does the rest — it calls MCP tools, interprets results, and takes action based on your instruction.

Overview

Concept	Description
instruction.md	Plain-text file describing what the agent monitors and how it escalates
state.json	Agent memory — accumulated findings, active issues, recent run summaries
runs/	Audit trail — one `.json` + `.md` file per run
LLM Provider	Azure OpenAI (default) or Anthropic/Claude — processes instructions and calls tools
Actions	Teams webhook, SMTP email, Graph API email, generic webhook, Azure DevOps pipeline

Prerequisites for Agentic Monitoring (Preview)

In addition to the standard BCTB prerequisites, you need:

BC Telemetry Buddy MCP installed globally: npm install -g bc-telemetry-buddy-mcp
Azure OpenAI deployment (GPT-4o recommended) OR Anthropic API key
Workspace — a directory (Git repo) containing .bctb-config.json with an agents section

Quick Start

1. Add the Agents Section to Your Config

Add an agents section to your .bctb-config.json:

{
  "profiles": { ... },
  "defaultProfile": "default",
  "agents": {
    "llm": {
      "provider": "azure-openai",
      "endpoint": "https://your-resource.openai.azure.com",
      "deployment": "gpt-4o",
      "apiVersion": "2024-10-21"
    },
    "defaults": {
      "maxToolCalls": 20,
      "contextWindowRuns": 5,
      "toolScope": "read-only"
    },
    "actions": {
      "teams-webhook": {
        "url": "https://your-teams-webhook-url"
      }
    }
  }
}

Secrets via environment variables: Never store API keys in the config file. Use:

AZURE_OPENAI_KEY — Azure OpenAI API key

ANTHROPIC_API_KEY — Anthropic API key (if using Anthropic)

TEAMS_WEBHOOK_URL — Override Teams webhook URL

SMTP_PASSWORD — SMTP relay password

GRAPH_CLIENT_SECRET — Microsoft Graph client secret

DEVOPS_PAT — Azure DevOps Personal Access Token

2. Create Your First Agent

bctb-mcp agent start "Monitor BC error rates. Alert on Teams when errors exceed 100/hour or increase by 200% vs previous runs." --name error-monitor

This creates:

agents/error-monitor/instruction.md — your instruction
agents/error-monitor/state.json — initial empty state
agents/error-monitor/runs/ — empty audit trail directory

3. Run the Agent

export AZURE_OPENAI_KEY=your-key-here
bctb-mcp agent run error-monitor --once

Output:

Running agent: error-monitor...

✓ Run #1 completed in 12.3s
  Tool calls: 4
  Tokens: 2847 (2341 prompt + 506 completion)
  Findings: First run. Error rate baseline: 23/hour across 5 event types. No thresholds exceeded.

4. Check State & Run Log

# View current state
cat agents/error-monitor/state.json

# View run history
bctb-mcp agent history error-monitor

CLI Commands

Command	Description
`bctb-mcp agent start <instruction> --name <name>`	Create a new agent
`bctb-mcp agent run <name> --once`	Run one monitoring pass
`bctb-mcp agent run-all --once`	Run all active agents
`bctb-mcp agent list`	List all agents with status
`bctb-mcp agent history <name> [--limit N]`	Show run history
`bctb-mcp agent pause <name>`	Pause an agent (skipped by `run-all`)
`bctb-mcp agent resume <name>`	Resume a paused agent

All commands support --config <path> to point to a specific config file, and --profile <name> to select a config profile.

Writing Effective Agent Instructions

The instruction is everything. Write it like you're explaining the task to a knowledgeable colleague:

Monitor AppSource validation telemetry for my extensions.

Check for validation failures (RT0005 events with error status),
categorize by extension name and failure type.

If failures persist across 3 consecutive checks, post to the Teams channel.
If failures persist across 6 consecutive checks, send an email to the dev lead.

Focus on the last 2 hours of data each run.
Ignore test tenants (any tenant with "test" or "sandbox" in the company name).

Best practices:

Be specific about BC event IDs when you know them (RT0005, LC0010, RT0006, etc.)
Define thresholds clearly: "exceeds 100", "p95 > 5 seconds", "increased by 200%"
Describe escalation steps: "If X for N consecutive checks, do Y"
Describe what to ignore (test tenants, known-noisy events)
Keep it under 500 words — the LLM processes it on every run

Example Agent Instructions (Ready to Use)

The MCP package ships with four fully-documented templates you can copy directly:

Template	Use Case	Location
AppSource Validation	ISVs watching for extension install/update failures	`templates/agents/appsource-validation/`
Performance Monitor	Track page load p95, report execution, AL method timing	`templates/agents/performance-monitoring/`
Error Rate Monitor	Catch-all error rate monitoring with dynamic event discovery	`templates/agents/error-rate-monitoring/`
Post-Deployment Watch	Short-lived regression monitor after deployments	`templates/agents/post-deployment-check/`

To use a template:

# Copy the template to your workspace
cp -r "$(npm root -g)/bc-telemetry-buddy-mcp/templates/agents/performance-monitoring" agents/

# Run it
bctb-mcp agent run performance-monitoring --once

Running Agents on a Schedule (CI/CD)

Agents are designed to run in CI/CD pipelines. Each run queries telemetry, updates state, and the pipeline commits the updated state back to the repository.

GitHub Actions

Copy node_modules/bc-telemetry-buddy-mcp/templates/github-actions/telemetry-agent.yml to .github/workflows/:

name: Telemetry Monitoring Agents

on:
  schedule:
    - cron: "0 * * * *"         # Hourly
  workflow_dispatch:              # Also allow manual runs

permissions:
  contents: write                 # Required to commit updated agent state

jobs:
  run-agents:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20" }
      - run: npm install -g bc-telemetry-buddy-mcp
      - run: bctb-mcp agent run-all --once
        env:
          BCTB_AUTH_FLOW: client_credentials
          BCTB_CLIENT_ID: ${{ secrets.BCTB_CLIENT_ID }}
          BCTB_CLIENT_SECRET: ${{ secrets.BCTB_CLIENT_SECRET }}
          AZURE_OPENAI_KEY: ${{ secrets.AZURE_OPENAI_KEY }}
          # Uncomment actions you use:
          # TEAMS_WEBHOOK_URL: ${{ secrets.TEAMS_WEBHOOK_URL }}
          # SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
      - name: Commit agent state
        run: |
          git config user.name "bctb-agent"
          git config user.email "bctb-agent@noreply.github.com"
          git add agents/
          git diff --cached --quiet || git commit -m "agent: run $(date -u +%Y-%m-%dT%H:%MZ)"
          git push

Note: Non-sensitive values (tenant ID, App Insights ID, Kusto URL, LLM endpoint/deployment) are read from .bctb-config.json in the repo — you don't need them as secrets. Only add actual secrets: BCTB_CLIENT_ID, BCTB_CLIENT_SECRET, your LLM API key, and any action secrets you configured.

See the full template at templates/github-actions/README.md for detailed setup instructions.

Azure DevOps

Copy templates/azure-devops/azure-pipelines.yml to your repository root. Create a variable group named bctb-secrets (Pipelines → Library → Variable groups) with the same secrets listed above (BCTB_CLIENT_ID, BCTB_CLIENT_SECRET, AZURE_OPENAI_KEY, plus any action secrets).

See templates/azure-devops/README.md for the complete setup guide.

Action Types

Agents can take actions when issues are detected. Configure the action in the agents.actions section of .bctb-config.json. All actions are optional — configure only the ones you need.

Tip: To tell an agent to use an action, mention it naturally in the agent's instruction.md. For example: "If failures persist for 3 checks, post to Teams" or "Send an email to the dev lead." The agent will call the matching action automatically.

Teams Webhook

Post rich alert cards to a Microsoft Teams channel.

How to create a Teams Incoming Webhook:

Open Microsoft Teams and navigate to the channel where you want alerts
Click the ⋯ (more options) next to the channel name → Manage channel
Go to Connectors (classic) or Workflows (new Teams):
- Connectors (classic): Search for Incoming Webhook → Add → give it a name (e.g. "Telemetry Agent") and optionally upload an icon → Create → copy the webhook URL
- Workflows (new Teams): Click + New workflow → choose "Post to a channel when a webhook request is received" → follow the wizard → copy the webhook URL
Paste the URL in the wizard or in your config:

"agents": {
  "actions": {
    "teams-webhook": {
      "url": "${TEAMS_WEBHOOK_URL}"
    }
  }
}

Security: Store the URL in the TEAMS_WEBHOOK_URL environment variable (or CI/CD secret) rather than hardcoding it. The ${TEAMS_WEBHOOK_URL} syntax tells the agent runtime to read from the environment.

In your instruction: "If failures persist across 3 consecutive checks, post to Teams."

Email via SMTP

Send email alerts through any SMTP relay. This works with hosted services like SendGrid, Mailgun, Amazon SES, or your own mail server.

Example: Free SMTP with Brevo (formerly Sendinblue):

Sign up at brevo.com (free tier: 300 emails/day)
Go to Settings → SMTP & API → SMTP
Note your credentials:
- Host: smtp-relay.brevo.com
- Port: 587
- Username: your Brevo login email
- Password: the SMTP key shown on the page
Store the password as SMTP_PASSWORD environment variable

Example: SendGrid:

Sign up at sendgrid.com (free tier: 100 emails/day)
Go to Settings → API Keys → Create API Key (select "Restricted Access" → enable "Mail Send")
Note your credentials:
- Host: smtp.sendgrid.net
- Port: 587
- Username: apikey (literal string)
- Password: the API key you just created
Store the API key as SMTP_PASSWORD environment variable

Configuration:

"agents": {
  "actions": {
    "email-smtp": {
      "host": "smtp.sendgrid.net",
      "port": 587,
      "secure": false,
      "auth": { "user": "apikey" },
      "from": "telemetry-agent@yourcompany.com",
      "defaultTo": ["devlead@yourcompany.com"]
    }
  }
}

Field	Description
`host`	SMTP server hostname
`port`	`587` (STARTTLS) or `465` (TLS)
`secure`	`true` for port 465 (TLS), `false` for port 587 (STARTTLS)
`auth.user`	SMTP username
`from`	Sender email address (must be verified with your SMTP provider)
`defaultTo`	Array of default recipient addresses

Set SMTP_PASSWORD environment variable. In your instruction: "Send an email to the dev lead."

Email via Microsoft Graph

Send email using the Microsoft Graph API — ideal if your organization uses Microsoft 365 and you want to send from a shared mailbox or service account without SMTP.

How to set up:

Go to the Azure Portal → Azure Active Directory → App registrations → New registration
Name it (e.g. "BC Telemetry Agent Email"), set Supported account types to "Single tenant", click Register
On the app's Overview page, copy:
- Application (client) ID → this is your clientId
- Directory (tenant) ID → this is your tenantId
Go to API permissions → Add a permission → Microsoft Graph → Application permissions → search for Mail.Send → Add → click Grant admin consent
Go to Certificates & secrets → New client secret → set an expiry → Add → copy the secret value immediately (you won't see it again)
Store the secret as GRAPH_CLIENT_SECRET environment variable

Important: The from address must be a valid mailbox in your tenant (e.g. a shared mailbox). The App Registration sends on behalf of that mailbox.

Configuration:

"agents": {
  "actions": {
    "email-graph": {
      "tenantId": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "from": "telemetry-agent@yourcompany.com",
      "defaultTo": ["devlead@yourcompany.com"]
    }
  }
}

Set GRAPH_CLIENT_SECRET environment variable.

Generic Webhook (Slack, PagerDuty, etc.)

Send a JSON payload to any HTTP endpoint. This is a flexible catch-all for integration with services like Slack, PagerDuty, Discord, Zapier, Power Automate, or your own REST APIs.

The agent will POST a JSON body with the alert details (issue title, severity, affected tenants, etc.) to the URL you configure.

Example: Slack Incoming Webhook:

Go to api.slack.com/apps → Create New App → From scratch
Go to Incoming Webhooks → toggle Activate → Add New Webhook to Workspace → pick a channel → Allow
Copy the webhook URL

"agents": {
  "actions": {
    "generic-webhook": {
      "url": "https://hooks.slack.com/services/T00000/B00000/XXXXXXXXX",
      "method": "POST",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

Example: Discord Webhook:

Open Discord → Server Settings → Integrations → Webhooks → New Webhook
Pick a channel, copy the URL, and append /slack to use Slack-compatible format

"generic-webhook": {
  "url": "https://discord.com/api/webhooks/1234567890/abcdef/slack",
  "method": "POST",
  "headers": { "Content-Type": "application/json" }
}

Example: Custom API with auth:

"generic-webhook": {
  "url": "https://your-api.com/alerts",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json"
  }
}

Field	Description
`url`	The endpoint to call
`method`	`POST` (default) or `PUT`
`headers`	Optional JSON object of HTTP headers (use for auth tokens, content type, etc.)

Azure DevOps Pipeline Trigger

Trigger an Azure DevOps pipeline when the agent detects an issue — useful for automated remediation, rollback workflows, or kicking off a diagnostic build.

How to set up:

In Azure DevOps, go to your project → Pipelines → open the pipeline you want to trigger
The Pipeline ID is the number in the URL: https://dev.azure.com/org/project/_build?definitionId=42 → ID is 42
Create a Personal Access Token (PAT):
- Click your profile icon (top-right) → Personal access tokens → New Token
- Scope: Build → Read & execute
- Set an expiry and copy the token
Store the PAT as DEVOPS_PAT environment variable

Configuration:

"agents": {
  "actions": {
    "pipeline-trigger": {
      "orgUrl": "https://dev.azure.com/yourorg",
      "project": "BC-Ops",
      "pipelineId": 42
    }
  }
}

Set DEVOPS_PAT environment variable.

Tip: The agent passes the issue details as pipeline parameters, so your triggered pipeline can read them and act accordingly (e.g. run diagnostics, create a work item, or initiate a rollback).

LLM Provider Configuration

Azure OpenAI (Default)

"agents": {
  "llm": {
    "provider": "azure-openai",
    "endpoint": "https://your-resource.openai.azure.com",
    "deployment": "gpt-4o",
    "apiVersion": "2024-10-21"
  }
}

Environment variable: AZURE_OPENAI_KEY

Anthropic / Claude

"agents": {
  "llm": {
    "provider": "anthropic",
    "model": "claude-opus-4-5"
  }
}

Environment variable: ANTHROPIC_API_KEY

Agent State and Memory

Each agent maintains state in agents/<name>/state.json:

{
  "agentName": "error-monitor",
  "lastRun": "2026-02-26T10:00:00Z",
  "runCount": 12,
  "status": "active",
  "summary": "Monitoring since Feb 24. Error rates stable at 20-30/hour. RT0005 spike on Feb 25 (85/hour) self-resolved within 1 hour.",
  "activeIssues": [],
  "resolvedIssues": [...],
  "recentRuns": [...]
}

Context compaction: The recentRuns array is a sliding window (default: 5 runs). When a run falls out of the window, the LLM folds it into the summary. This keeps state.json bounded regardless of how many runs have occurred.

Resolved issue pruning: Issues in resolvedIssues are automatically pruned after 30 days (configurable via resolvedIssueTTLDays).

Advanced Agent Configuration

Full defaults reference:

"agents": {
  "defaults": {
    "maxToolCalls": 20,          // Max LLM tool calls per run before aborting
    "maxTokens": 4096,           // Max tokens per LLM response
    "contextWindowRuns": 5,      // Sliding window size for recentRuns
    "resolvedIssueTTLDays": 30,  // Days to keep resolved issues
    "toolScope": "read-only"     // "read-only" or "full" (full allows save_query etc.)
  }
}

Troubleshooting Agents

Problem	Cause	Fix
`No agents.llm section in config`	Missing agents config	Add `agents.llm` section to `.bctb-config.json`
`AZURE_OPENAI_KEY not set`	Missing env var	Set `AZURE_OPENAI_KEY` environment variable
`Agent exceeded max tool calls`	LLM loop / unclear instruction	Simplify instruction; increase `maxToolCalls`
No findings after first run	Config or App Insights issue	Verify `BCTB_APP_INSIGHTS_ID` is correct; check with `get_event_catalog`
Teams notification not sent	Webhook URL issue or not configured	Check `agents.actions.teams-webhook.url` and `TEAMS_WEBHOOK_URL` env var
Teams shows raw markdown tables	Adaptive Card version < 1.5	Update to latest MCP version — tables are now converted to native Adaptive Card `Table` elements
Pipeline output too noisy	Internal kusto/auth/cache logs visible	Update to latest MCP version — these are now in collapsible groups in Azure DevOps / GitHub Actions
Agent paused after error	Not applicable — errors don't auto-pause	Check the run log in `agents/<name>/runs/`
Git push fails in pipeline	Branch protection	Ensure pipeline has `contents: write` permission (GitHub) or Contribute on repo (Azure DevOps)

Now that you're set up:

✅ Explore discovery tools - Ask Copilot "what events are available?" to see get_event_catalog in action
✅ Analyze event structure - Use get_event_field_samples to understand customDimensions for specific events
✅ Save your first query - Run a KQL query and save it for future reference
✅ Add external references - Configure the BCTech GitHub samples for additional context
✅ Build your query library - Save queries as you discover useful patterns
✅ Share with your team - Commit .kql files to your repository

Happy querying! 🚀