Merge pull request #308107 from anthonychu/func-otel-troubleshooting

[Functions] Add OTel troubleshooting section

Author: prmerger-automator[bot]

articles/azure-functions/opentelemetry-howto.md

@@ -407,6 +407,105 @@ When you export your data using OpenTelemetry, keep these current considerations
 ::: zone-end  
 + [Azure Functions diagnostics](functions-diagnostics.md) in the Azure portal is a useful resource for detecting and diagnosing potential monitoring-related issues. 
 
+## Troubleshooting
+
+When you export your data using OpenTelemetry, keep these common issues and solutions in mind.
+
+### Log filtering
+
+Understanding the difference between the host process and worker process is important for correctly configuring log filtering in your function app.
+
+The *host process* is the Azure Functions runtime that manages triggers, scaling, and emits system-level telemetry such as initialization logs, request traces, and runtime health information.
+
+The *worker process* is language specific, executes your function code, and produces application logs and telemetry independently.
+
+> [!IMPORTANT]
+> Filters defined in host.json apply only to logs generated by the host process. Logs from the worker process must be filtered using language-specific OpenTelemetry settings.
+
+**Example: Filter host logs for all providers in host.json**
+
+Use this approach to set a global log level across all providers managed by the host:
+
+```json
+{
+  "version": "2.0",
+  "telemetryMode": "OpenTelemetry",
+  "logging": {
+    "logLevel": {
+      "default": "Warning"
+    }
+  }
+}
+```
+
+**Example: Filter logs only for the OpenTelemetry logger provider**
+
+Use this approach to target only the OpenTelemetry logger provider while leaving other providers (such as console or file logging) unaffected:
+
+```json
+{
+  "version": "2.0",
+  "telemetryMode": "OpenTelemetry",
+  "logging": {
+    "OpenTelemetry": {
+      "logLevel": {
+        "default": "Warning"
+      }
+    }
+  }
+}
+```
+
+### Console logging
+
+The Functions host automatically captures anything written to stdout or stderr and forwards it to the telemetry pipeline. If you also use a ConsoleExporter or write directly to console in your code, duplicate logs can occur in your telemetry data.
+
+> [!NOTE]
+> Don't add ConsoleExporter or write to console in production code to avoid duplicate telemetry entries.
+
+### Microsoft Entra authentication
+
+When using Microsoft Entra authentication with OpenTelemetry, you must configure authentication separately for both the host process and the worker process.
+
+To configure authentication for the host process, see [Require Microsoft Entra authentication](configure-monitoring.md#require-microsoft-entra-authentication).
+
+To configure authentication for the worker process, see [Enable Microsoft Entra authentication](/azure/azure-monitor/app/azure-ad-authentication).
+
+### Resource attributes support
+
+Resource attributes support in Azure Monitor is currently in preview. To enable this feature, set the `OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS` environment variable to `true`. This setting ingests resource attributes into the custom metrics table.
+
+### Duplicate request telemetry
+
+The host process automatically emits request telemetry. If the worker process is also instrumented with request tracking libraries (for example, AspNetCoreInstrumentation in .NET), the same request is reported twice.
+
+> [!NOTE]
+> Since the Azure Monitor Distro typically includes AspNetCoreInstrumentation in .NET and similar instrumentation in other languages, avoid using the Azure Monitor distro in the worker process to prevent duplicate telemetry.
+
+### Logging scopes not included
+
+By default, the worker process doesn't include scopes in its logs. To enable scopes, you must configure this setting explicitly in the worker. The following example shows how to enable scopes in .NET Isolated:
+
+```csharp
+builder.Logging.AddOpenTelemetry(b => b.IncludeScopes = true);
+```
+
+### Missing request telemetry
+
+Triggers such as HTTP, Service Bus, and Event Hubs depend on context propagation for distributed tracing. With parent-based sampling as the default behavior, request telemetry isn't generated when the incoming request or message isn't sampled.
+
+### Duplicate OperationId
+
+In Azure Functions, the `OperationId` used for correlating telemetry is derived directly from the `traceparent` value in the incoming request or message. If multiple calls reuse the same `traceparent` value, they're all assigned the same `OperationId`.
+
+### Configuring OpenTelemetry with environment variables
+
+You can configure OpenTelemetry behavior using its standard environment variables, which provide a consistent way to control behavior across different languages and runtimes. These variables allow you to adjust sampling strategies, exporter settings, and resource attributes. For more information about supported environment variables, see the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/sdk-configuration/).
+
+### Use diagnostics to troubleshoot monitoring issues
+
+[Azure Functions diagnostics](functions-diagnostics.md) in the Azure portal is a useful resource for detecting and diagnosing potential monitoring-related issues. 
+
 To access diagnostics in your app:
 
   1. In the [Azure portal](https://portal.azure.com), navigate to your function app resource.