Add centralized OpenTelemetry tracing for MCP tool execution by Copilot · Pull Request #3111 · Azure/data-api-builder

Copilot · 2026-02-06T08:05:52Z

Why make this change?

Closes on MCP Custom Tool Telemetry #3060

MCP tool executions (both built-in DML tools and dynamic custom stored-procedure tools) currently lack explicit OpenTelemetry tracing. While ILogger logging exists, there are no tracing spans emitted for MCP tool invocations. This makes it difficult to observe and diagnose tool execution in distributed tracing systems.

What is this change?

Added centralized OpenTelemetry tracing at the MCP dispatcher level (where tools are resolved and ExecuteAsync is invoked), ensuring consistent spans for all MCP tools without code duplication.

Span Attributes

Attribute	Description
`mcp.tool.name`	Tool name
`dab.entity`	Entity alias/name (when applicable)
`dab.operation`	Operation type (e.g., `execute`)
`db.procedure`	Stored procedure name, schema-qualified if available

Outcome Recording

Success: ActivityStatusCode.Ok
Failure: ActivityStatusCode.Error with RecordException() and error.code/error.message tags

Coverage

Spans cover all paths:

Successful execution
Auth/validation failures
Database/execution errors

Implementation Details

Uses existing TelemetryTracesHelper.DABActivitySource ("DataApiBuilder")
Follows the established pattern from ExecutionHelper where DABActivitySource.StartActivity() wraps query execution
Instrumentation is centralized at the MCP dispatcher level, not inside individual tools

How was this tested?

Integration Tests
Unit Tests

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

…EntityName property Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Copilot

Pull request overview

Adds centralized OpenTelemetry tracing around MCP tool execution so both built-in and dynamic custom MCP tools emit consistent spans across stdio and HTTP transports.

Changes:

Added McpTelemetryHelper.ExecuteWithTelemetryAsync to start/finish spans, set tags, and record exceptions with MCP-specific error codes.
Wired telemetry wrapper into both MCP dispatch entry points (McpStdioServer and HTTP CallToolHandler).
Added unit tests for telemetry helpers and exposed DynamicCustomTool.EntityName to avoid reflection.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs	Central telemetry wrapper + operation inference + error-code mapping + custom-tool metadata extraction
src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryErrorCodes.cs	Defines MCP telemetry error-code constants
src/Core/Telemetry/TelemetryTracesHelper.cs	Adds Activity extension methods for MCP tool tags/status/exception recording
src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs	Wraps stdio tool execution with telemetry helper
src/Azure.DataApiBuilder.Mcp/Core/McpServerConfiguration.cs	Wraps HTTP tool execution with telemetry helper
src/Azure.DataApiBuilder.Mcp/Core/DynamicCustomTool.cs	Exposes `EntityName` property and updates internal usage
src/Service.Tests/UnitTests/McpTelemetryTests.cs	Adds unit tests validating MCP telemetry tagging/status/error mapping
src/Service.Tests/Azure.DataApiBuilder.Service.Tests.csproj	Adds project reference to MCP project for unit testing
src/Azure.DataApiBuilder.Mcp/Azure.DataApiBuilder.Mcp.csproj	Adds `InternalsVisibleTo` for `Azure.DataApiBuilder.Service.Tests`

Copilot · 2026-02-11T13:56:35Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+                // Check if the tool returned an error result (tools catch exceptions internally
+                // and return CallToolResult with IsError=true instead of throwing)
+                if (result.IsError == true)
+                {
+                    activity?.SetStatus(ActivityStatusCode.Error, "Tool returned an error result");
+                    activity?.SetTag("mcp.tool.error", true);
+                }


When CallToolResult.IsError == true, the span is marked as error but no error.code / error.message tags are set. Since MCP tools standardize errors via McpResponseBuilder.BuildErrorResult (type/message in the JSON payload), consider extracting those values and setting error.code (and optionally error.message) so non-exception failures (auth/validation/etc.) are diagnosable in traces.

Copilot · 2026-02-11T13:56:36Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+            try
+            {
+                // Access public properties instead of reflection
+                string? entityName = customTool.EntityName;
+
+                if (entityName != null)
+                {
+                    // Try to get the stored procedure name from the runtime configuration
+                    RuntimeConfigProvider? runtimeConfigProvider = serviceProvider.GetService<RuntimeConfigProvider>();
+                    if (runtimeConfigProvider != null)
+                    {
+                        RuntimeConfig config = runtimeConfigProvider.GetConfig();
+                        if (config.Entities.TryGetValue(entityName, out Entity? entityConfig))
+                        {
+                            string? dbProcedure = entityConfig.Source.Object;
+                            return (entityName, dbProcedure);
+                        }
+                    }
+                }
+
+                return (entityName, null);
+            }
+            catch (Exception ex) when (ex is InvalidOperationException || ex is ArgumentException)
+            {
+                // If configuration access fails due to invalid state or arguments, return null values
+                // This is expected during startup or configuration changes
+                return (null, null);
+            }


ExtractCustomToolMetadata calls runtimeConfigProvider.GetConfig(), which can throw DataApiBuilderException when the runtime config isn't set up. Because this helper runs inside the telemetry wrapper, an exception here would fail the tool invocation even though metadata extraction should be best-effort. Consider catching broader exceptions (at least DataApiBuilderException) and returning (customTool.EntityName, null) so telemetry can't break tool execution.

Suggested change

try

{

// Access public properties instead of reflection

string? entityName = customTool.EntityName;

if (entityName != null)

{

// Try to get the stored procedure name from the runtime configuration

RuntimeConfigProvider? runtimeConfigProvider = serviceProvider.GetService<RuntimeConfigProvider>();

if (runtimeConfigProvider != null)

{

RuntimeConfig config = runtimeConfigProvider.GetConfig();

if (config.Entities.TryGetValue(entityName, out Entity? entityConfig))

{

string? dbProcedure = entityConfig.Source.Object;

return (entityName, dbProcedure);

}

}

}

return (entityName, null);

}

catch (Exception ex) when (ex is InvalidOperationException || ex is ArgumentException)

{

// If configuration access fails due to invalid state or arguments, return null values

// This is expected during startup or configuration changes

return (null, null);

}

// Access public properties instead of reflection

string? entityName = customTool.EntityName;

if (entityName == null)

{

return (null, null);

}

try

{

// Try to get the stored procedure name from the runtime configuration

RuntimeConfigProvider? runtimeConfigProvider = serviceProvider.GetService<RuntimeConfigProvider>();

if (runtimeConfigProvider != null)

{

RuntimeConfig config = runtimeConfigProvider.GetConfig();

if (config.Entities.TryGetValue(entityName, out Entity? entityConfig))

{

string? dbProcedure = entityConfig.Source.Object;

return (entityName, dbProcedure);

}

}

}

catch (Exception)

{

// If configuration access fails for any reason, fall back to returning only the entity name.

// Telemetry must not prevent tool execution, and metadata extraction is best-effort.

}

return (entityName, null);

Copilot · 2026-02-11T13:56:36Z

src/Service.Tests/UnitTests/McpTelemetryTests.cs

+            activity.TrackMcpToolExecutionFinishedWithException(testException, errorCode: "ExecutionFailed");
+
+            Activity recorded = StopAndGetRecordedActivity(activity);
+            Assert.AreEqual(ActivityStatusCode.Error, recorded.Status);
+            Assert.AreEqual("Test exception", recorded.StatusDescription);
+            Assert.AreEqual("InvalidOperationException", recorded.GetTagItem("error.type"));
+            Assert.AreEqual("Test exception", recorded.GetTagItem("error.message"));
+            Assert.AreEqual("ExecutionFailed", recorded.GetTagItem("error.code"));


Use McpTelemetryErrorCodes.EXECUTION_FAILED instead of the string literal "ExecutionFailed" here to avoid test drift if the constant value ever changes.

Suggested change

activity.TrackMcpToolExecutionFinishedWithException(testException, errorCode: "ExecutionFailed");

Activity recorded = StopAndGetRecordedActivity(activity);

Assert.AreEqual(ActivityStatusCode.Error, recorded.Status);

Assert.AreEqual("Test exception", recorded.StatusDescription);

Assert.AreEqual("InvalidOperationException", recorded.GetTagItem("error.type"));

Assert.AreEqual("Test exception", recorded.GetTagItem("error.message"));

Assert.AreEqual("ExecutionFailed", recorded.GetTagItem("error.code"));

activity.TrackMcpToolExecutionFinishedWithException(testException, errorCode: McpTelemetryErrorCodes.EXECUTION_FAILED);

Activity recorded = StopAndGetRecordedActivity(activity);

Assert.AreEqual(ActivityStatusCode.Error, recorded.Status);

Assert.AreEqual("Test exception", recorded.StatusDescription);

Assert.AreEqual("InvalidOperationException", recorded.GetTagItem("error.type"));

Assert.AreEqual("Test exception", recorded.GetTagItem("error.message"));

Assert.AreEqual(McpTelemetryErrorCodes.EXECUTION_FAILED, recorded.GetTagItem("error.code"));

Copilot · 2026-02-11T13:56:36Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+            return toolName.ToLowerInvariant() switch
+            {
+                string s when s.Contains("read") || s.Contains("get") || s.Contains("list") || s.Contains("describe") => "read",
+                string s when s.Contains("create") || s.Contains("insert") => "create",
+                string s when s.Contains("update") || s.Contains("modify") => "update",
+                string s when s.Contains("delete") || s.Contains("remove") => "delete",
+                string s when s.Contains("execute") => "execute",
+                _ => "execute"
+            };


InferOperationFromToolName uses substring matching (e.g., Contains("get")), which can misclassify tool names where those sequences occur inside other words (e.g., target_entity contains get). Since this value is emitted as dab.operation, consider tokenizing on _ (or checking prefixes) so only verb tokens like get, list, create, etc. drive the inference.

Suggested change

return toolName.ToLowerInvariant() switch

{

string s when s.Contains("read") || s.Contains("get") || s.Contains("list") || s.Contains("describe") => "read",

string s when s.Contains("create") || s.Contains("insert") => "create",

string s when s.Contains("update") || s.Contains("modify") => "update",

string s when s.Contains("delete") || s.Contains("remove") => "delete",

string s when s.Contains("execute") => "execute",

_ => "execute"

};

if (string.IsNullOrWhiteSpace(toolName))

{

return "execute";

}

string normalizedName = toolName.ToLowerInvariant();

string[] tokens = normalizedName.Split(

new[] { '_', '-', ' ' },

StringSplitOptions.RemoveEmptyEntries);

static bool HasVerbToken(string[] tokens, params string[] verbs)

{

foreach (string token in tokens)

{

foreach (string verb in verbs)

{

if (token == verb)

{

return true;

}

}

}

return false;

}

if (HasVerbToken(tokens, "read", "get", "list", "describe"))

{

return "read";

}

if (HasVerbToken(tokens, "create", "insert"))

{

return "create";

}

if (HasVerbToken(tokens, "update", "modify"))

{

return "update";

}

if (HasVerbToken(tokens, "delete", "remove"))

{

return "delete";

}

if (HasVerbToken(tokens, "execute"))

{

return "execute";

}

return "execute";

Copilot · 2026-02-11T13:56:37Z

src/Service.Tests/UnitTests/McpTelemetryTests.cs

+    public class McpTelemetryTests
+    {
+        private static ActivityListener? _activityListener;
+        private static List<Activity> _recordedActivities = new();


Field '_recordedActivities' can be 'readonly'.

Suggested change

private static List<Activity> _recordedActivities = new();

private static readonly List<Activity> _recordedActivities = new();

Aniruddh25 · 2026-02-12T02:09:38Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryErrorCodes.cs

+        public const string EXECUTION_FAILED = "ExecutionFailed";
+
+        /// <summary>
+        /// Authentication or authorization failure error code.


There should be a separate failure code for authorization like
AUTHORIZATION_FAILED

Aniruddh25 · 2026-02-12T02:15:22Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+            {
+                // Extract telemetry metadata
+                string? entityName = ExtractEntityNameFromArguments(arguments);
+                string? operation = InferOperationFromToolName(toolName);


Operation should be inferred only for built in tools.
For dynamic custom tools, it should always be "execute"

Aniruddh25 · 2026-02-12T02:17:52Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+        /// <returns>The inferred operation type.</returns>
+        public static string InferOperationFromToolName(string toolName)
+        {
+            return toolName.ToLowerInvariant() switch


The operation shouldn't be inferred from toolname,

All the built in tools have types associated with them, so could check the tool type and infer the action. create_record tool is create action. String comparison should not be needed.

Aniruddh25

Need to address changes related to inferring tool names, and unit tests.

Aniruddh25 · 2026-02-12T02:19:28Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+        {
+            return toolName.ToLowerInvariant() switch
+            {
+                string s when s.Contains("read") || s.Contains("get") || s.Contains("list") || s.Contains("describe") => "read",


list and describe_entites tools are not typical dab operations - crude. the operation for these tools could simply be list/describe

Aniruddh25 · 2026-02-12T02:20:32Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+            return ex switch
+            {
+                OperationCanceledException => McpTelemetryErrorCodes.OPERATION_CANCELLED,
+                UnauthorizedAccessException => McpTelemetryErrorCodes.AUTHENTICATION_FAILED,


UnthorizedAccess should be AUTHORIZATION_FAILED

Isnt there an exception for Unauthenticated Access?

Aniruddh25 · 2026-02-12T02:23:07Z

src/Azure.DataApiBuilder.Mcp/Utils/McpTelemetryHelper.cs

+                        RuntimeConfig config = runtimeConfigProvider.GetConfig();
+                        if (config.Entities.TryGetValue(entityName, out Entity? entityConfig))
+                        {
+                            string? dbProcedure = entityConfig.Source.Object;


Does Source.Object give the procedure name including the schema?

Aniruddh25 · 2026-02-12T02:30:56Z

src/Service.Tests/UnitTests/McpTelemetryTests.cs

+        /// including when optional parameters are null.
+        /// </summary>
+        [DataTestMethod]
+        [DataRow("read_records", "books", "read", null, DisplayName = "Sets entity, operation; no procedure")]


should test all dml tools, not just read

Aniruddh25 · 2026-02-12T02:35:16Z

src/Service.Tests/UnitTests/McpTelemetryTests.cs

+        [DataTestMethod]
+        // Built-in tool names
+        [DataRow("read_records", "read")]
+        [DataRow("get_book", "read")]


get_book should be execute - since its likely a stored procedure that has been called - its not a built-in tool name

Aniruddh25 · 2026-02-12T02:41:19Z

src/Service.Tests/UnitTests/McpTelemetryTests.cs

+        {
+            // Arrange & Act
+            using Activity activity = CreateActivity();
+            activity.TrackMcpToolExecutionStarted(


can we unit test ExecuteWithTelemetryAsync? Since, here we are simply testing whether the Activity's TrackXX function is accurately implemented or not - which is not what this PR is implementing

Aniruddh25 · 2026-02-12T02:42:38Z

src/Service.Tests/UnitTests/McpTelemetryTests.cs

+
+        #endregion
+
+        #region Test Fakes


Call it Mock instead of Fake.

Initial plan

3784c3c

Copilot AI assigned Copilot and souvikghosh04 Feb 6, 2026

Copilot started work on behalf of souvikghosh04 February 6, 2026 08:06 View session

Copilot AI and others added 5 commits February 6, 2026 08:11

Add OpenTelemetry tracing infrastructure for MCP tools

da7c4cd

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Add comprehensive telemetry tests for MCP tools

d015084

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Refactor: Extract telemetry helpers to shared utility and add public …

db3f83d

…EntityName property Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Improve error handling and use specific error codes in telemetry

7b9a376

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Apply code formatting fixes

61d54c9

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add OpenTelemetry tracing for custom tools~~ Add OpenTelemetry tracing for MCP tool execution Feb 6, 2026

Copilot finished work on behalf of souvikghosh04 February 6, 2026 08:29

Copilot AI requested a review from souvikghosh04 February 6, 2026 08:29

souvikghosh04 added 3 commits February 9, 2026 22:25

Merge branch 'main' into copilot/add-telemetry-for-custom-tools

b4c119d

Refactor and optimize

5ece5ff

Merge branch 'main' into copilot/add-telemetry-for-custom-tools

19bd5b0

souvikghosh04 requested a review from Copilot February 11, 2026 13:51

Copilot started reviewing on behalf of souvikghosh04 February 11, 2026 13:51 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

souvikghosh04 marked this pull request as ready for review February 11, 2026 14:25

souvikghosh04 requested review from Alekhya-Polavarapu, Aniruddh25, RubenCerna2079, aaronburtle, anushakolan, neeraj-sharma2592, rusamant, sourabh1007 and vadeveka as code owners February 11, 2026 14:25

souvikghosh04 added this to Data API builder Feb 11, 2026

github-project-automation bot moved this to Todo in Data API builder Feb 11, 2026

souvikghosh04 added this to the Feb 2026 milestone Feb 11, 2026

souvikghosh04 added the mcp-server label Feb 11, 2026

souvikghosh04 moved this from Todo to Review In Progress in Data API builder Feb 11, 2026

Aniruddh25 added 2 commits February 11, 2026 17:39

Merge branch 'main' into copilot/add-telemetry-for-custom-tools

44b7937

Merge branch 'main' into copilot/add-telemetry-for-custom-tools

0d9d882

Aniruddh25 reviewed Feb 12, 2026

View reviewed changes

Aniruddh25 requested changes Feb 12, 2026

View reviewed changes

Copilot started work on behalf of souvikghosh04 February 12, 2026 09:41 View session

Copilot stopped work on behalf of souvikghosh04 due to an error February 12, 2026 09:44
The session was cancelled by the user.

Copilot started work on behalf of souvikghosh04 February 12, 2026 09:45 View session

Copilot AI changed the title ~~Add OpenTelemetry tracing for MCP tool execution~~ Restrict /openapi endpoint to development mode only Feb 12, 2026

Copilot finished work on behalf of souvikghosh04 February 12, 2026 09:46

souvikghosh04 changed the title ~~Restrict /openapi endpoint to development mode only~~ Add centralized OpenTelemetry tracing for MCP tool execution Feb 13, 2026

souvikghosh04 linked an issue Feb 13, 2026 that may be closed by this pull request

MCP Custom Tool Telemetry #3060

Open

-            return toolName.ToLowerInvariant() switch
-            {
-                string s when s.Contains("read") || s.Contains("get") || s.Contains("list") || s.Contains("describe") => "read",
-                string s when s.Contains("create") || s.Contains("insert") => "create",
-                string s when s.Contains("update") || s.Contains("modify") => "update",
-                string s when s.Contains("delete") || s.Contains("remove") => "delete",
-                string s when s.Contains("execute") => "execute",
-                _ => "execute"
-            };
+            if (string.IsNullOrWhiteSpace(toolName))
+            {
+                return "execute";
+            }
+            string normalizedName = toolName.ToLowerInvariant();
+            string[] tokens = normalizedName.Split(
+                new[] { '_', '-', ' ' },
+                StringSplitOptions.RemoveEmptyEntries);
+            static bool HasVerbToken(string[] tokens, params string[] verbs)
+            {
+                foreach (string token in tokens)
+                {
+                    foreach (string verb in verbs)
+                    {
+                        if (token == verb)
+                        {
+                            return true;
+                        }
+                    }
+                }
+                return false;
+            }
+            if (HasVerbToken(tokens, "read", "get", "list", "describe"))
+            {
+                return "read";
+            }
+            if (HasVerbToken(tokens, "create", "insert"))
+            {
+                return "create";
+            }
+            if (HasVerbToken(tokens, "update", "modify"))
+            {
+                return "update";
+            }
+            if (HasVerbToken(tokens, "delete", "remove"))
+            {
+                return "delete";
+            }
+            if (HasVerbToken(tokens, "execute"))
+            {
+                return "execute";
+            }
+            return "execute";

	private static List<Activity> _recordedActivities = new();
	private static readonly List<Activity> _recordedActivities = new();

Conversation

Copilot AI commented Feb 6, 2026 • edited by souvikghosh04 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why make this change?

What is this change?

Span Attributes

Outcome Recording

Coverage

Implementation Details

How was this tested?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 6, 2026 •

edited by souvikghosh04

Loading

Aniruddh25 Feb 12, 2026 •

edited

Loading