Add diagnostic events for Portal visibility (GA requirement)

Emit MS_DiagnosticEvent structured log entries for:
- AZFK0001: Connection string not found
- AZFK0002: Ingestion failed/partial success
- AZFK0003: Query execution failed

These are picked up by the Functions runtime and surfaced in
the Portal Overview section for customers.

Author: monishkadas-ms

src/Bindings/KustoAsyncCollector.cs

@@ -92,7 +92,7 @@ public async Task FlushAsync(CancellationToken cancellationToken = default)
                     if (ingestionStatus.Status == Status.Failed || ingestionStatus.Status == Status.PartiallySucceeded)
                     {
                         string errorMessage = $"Ingestion status reported failure/partial success for {ingestSourceId}. Ingest detail {this._contextdetail.Value}, and status reported was {ingestionStatus.Status}";
-                        this._logger.LogError(errorMessage);
+                        this._logger.Log(LogLevel.Error, new EventId(0), KustoDiagnosticEvent.Create(KustoConstants.IngestionErrorCode, errorMessage, KustoConstants.KustoBindingHelpLink), null, (state, ex) => state.ToString());
                         throw new FunctionInvocationException(errorMessage);
                     }
                     this._rows.Clear();

src/Bindings/KustoQueryConverters.cs

@@ -72,7 +72,7 @@ public async Task<IEnumerable<T>> ConvertAsync(KustoAttribute attribute, Cancell
                 catch (Exception ex)
                 {
                     string logMessage = $"Error in Query/Conversion. Attributes [DB='{attribute?.Database}', Query='{attribute?.KqlCommand}',Parameters='{attribute?.KqlParameters}',CRP='{attribute?.ClientRequestProperties}']";
-                    this._logger.LogError(ex, logMessage);
+                    this._logger.Log(LogLevel.Error, new EventId(0), KustoDiagnosticEvent.Create(KustoConstants.QueryErrorCode, logMessage, KustoConstants.KustoBindingHelpLink), ex, (state, e) => state.ToString());
                     throw new InvalidOperationException(logMessage, ex);
                 }
             }

src/Config/KustoDiagnosticEvent.cs

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+
+using System.Collections;
+using System.Collections.Generic;
+
+namespace Microsoft.Azure.WebJobs.Extensions.Kusto
+{
+    /// <summary>
+    /// Creates structured log state dictionaries that the Azure Functions runtime
+    /// recognizes as diagnostic events. These events are aggregated and surfaced
+    /// in the Portal Overview section for customers.
+    /// </summary>
+    internal sealed class KustoDiagnosticEvent : IReadOnlyList<KeyValuePair<string, object>>
+    {
+        private readonly List<KeyValuePair<string, object>> _state;
+        private readonly string _message;
+
+        private KustoDiagnosticEvent(string errorCode, string message, string helpLink)
+        {
+            this._message = message;
+            this._state = new List<KeyValuePair<string, object>>
+            {
+                new KeyValuePair<string, object>(KustoConstants.DiagnosticEventKey, true),
+                new KeyValuePair<string, object>(KustoConstants.ErrorCodeKey, errorCode),
+                new KeyValuePair<string, object>(KustoConstants.HelpLinkKey, helpLink),
+                new KeyValuePair<string, object>("{OriginalFormat}", message),
+            };
+        }
+
+        public static KustoDiagnosticEvent Create(string errorCode, string message, string helpLink)
+        {
+            return new KustoDiagnosticEvent(errorCode, message, helpLink);
+        }
+
+        public int Count => this._state.Count;
+
+        public KeyValuePair<string, object> this[int index] => this._state[index];
+
+        public IEnumerator<KeyValuePair<string, object>> GetEnumerator()
+        {
+            return this._state.GetEnumerator();
+        }
+
+        IEnumerator IEnumerable.GetEnumerator()
+        {
+            return this.GetEnumerator();
+        }
+
+        public override string ToString()
+        {
+            return this._message;
+        }
+    }
+}

src/Config/KustoExtensionConfigProvider.cs

@@ -83,7 +83,9 @@ internal void ValidateConnection(KustoAttribute attribute, Type paramType)
             if (string.IsNullOrEmpty(resolvedConnectionString))
             {
                 string attributeProperty = $"{nameof(KustoAttribute)}.{nameof(KustoAttribute.Connection)}";
-                throw new InvalidOperationException($"Parameter {attributeProperty} should be passed as an environment variable. This value resolved to null");
+                string errorMessage = $"Parameter {attributeProperty} should be passed as an environment variable. This value resolved to null";
+                this._logger.Log(LogLevel.Error, new EventId(0), KustoDiagnosticEvent.Create(KustoConstants.ConnectionErrorCode, errorMessage, KustoConstants.KustoBindingHelpLink), null, (state, ex) => state.ToString());
+                throw new InvalidOperationException(errorMessage);
             }
             // Empty database check is added right when the KustoAttribute is constructed. This however is deferred here. 
             // TODO : Add check based on parameters and parameter indexes ?

src/KustoConstants.cs

@@ -22,6 +22,16 @@ internal static class KustoConstants
         public const string InputBindingType = "InputBinding";
         public const string OutputBindingType = "OutputBinding";
         public const string FunctionsRuntimeHostKey = "FUNCTIONS_WORKER_RUNTIME";
+        // Diagnostic event keys used by the Functions runtime to surface events in the Portal
+        public const string DiagnosticEventKey = "MS_DiagnosticEvent";
+        public const string HelpLinkKey = "MS_HelpLink";
+        public const string ErrorCodeKey = "MS_ErrorCode";
+        // Kusto extension error codes
+        public const string ConnectionErrorCode = "AZFK0001";
+        public const string IngestionErrorCode = "AZFK0002";
+        public const string QueryErrorCode = "AZFK0003";
+        // Help links for documentation
+        public const string KustoBindingHelpLink = "https://learn.microsoft.com/azure/azure-functions/functions-bindings-azure-data-explorer";
         public static readonly string AssemblyVersion = Assembly.GetExecutingAssembly().GetName().Version.ToString();
         public static readonly string ClientDetailForTracing = $"{AzFunctionsClientName}:{AssemblyVersion}";
         public static readonly string ClientRequestId = $"AzFunctions.InputBinding;{AssemblyVersion}";