Merge pull request #9753 from v-albemi/datadog-troubleshooting

ryanberg-aquent · web-flow · commit b8f1bbe83e29 · 2026-01-22T08:18:44.000-10:00
AB#9127: Datadog troubleshooting articles
diff --git a/support/azure/partner-solutions/datadog/installation-fails.md b/support/azure/partner-solutions/datadog/installation-fails.md
@@ -0,0 +1,53 @@
+---
+title: Troubleshoot Default API Key Problems in Datadog
+description: Resolve Datadog agent installation failures caused by a missing default API key, or change an incorrect default API key. 
+author: agrimayadav
+ms.author: jarrettr
+ms.service: partner-services
+ms.topic: troubleshooting-general
+ms.date: 09/22/2025
+ai-usage: ai-assisted
+
+# customer intent: As an Azure administrator or user, I want to resolve an installation failure that's caused by a missing default API key, or I want to change a default API key.
+
+---
+
+# Datadaog agent installation fails, or default API key is incorrect
+
+## Summary
+
+The Azure Datadog integration enables you to install a Datadog agent on a virtual machine or app service. This article helps you troubleshoot Datadog agent installation failures that are caused by a missing default API key. It also describes how to change the default key.
+
+## Prerequisites
+
+- Access to the [Azure portal](https://portal.azure.com) with permissions to view or configure the Datadog integration and to restart virutal machines (VMs) or app services if required.
+ 
+## Problems and solutions
+
+### Problem: Datadog installation fails
+
+If a default API key isn't selected, the Datadog agent installation fails.
+
+#### Solution
+
+1. In the Azure portal, go to the Datadog resource. 
+1. Select **Settings** > **Keys**.
+1. In **API Keys**, change the default key.
+1. Try again to install the agent. 
+
+### Problem: Incorrect API key configured on the resource
+
+The API key for the resource is incorrect.
+
+#### Solution
+
+1. In the Azure portal, go to the Datadog resource. 
+1. Select **Settings** > **Keys**.
+1. In **API Keys**, change the default key.
+1. Uninstall the Datadog agent and reinstall it.
+
+## Related content
+
+- [Datadog agent installation docs](https://docs.datadoghq.com/agent/)
+- [Datadog Azure integration documentation](https://docs.datadoghq.com/integrations/azure/)
+- [Manage extensions on Azure virtual machines](/azure/virtual-machines/extensions/overview)
diff --git a/support/azure/partner-solutions/datadog/metrics-not-emitted.md b/support/azure/partner-solutions/datadog/metrics-not-emitted.md
@@ -0,0 +1,65 @@
+---
+title: Metrics Not Being Emitted
+description: Resolve the problem in which Datadog doesn't receive metrics from Azure resources because of a missing or incorrect role assignment.
+author: agrimayadav
+ms.author: jarrettr
+ms.service: partner-services
+ms.topic: troubleshooting-problem-resolution
+ms.date: 09/19/2025
+ai-usage: ai-assisted
+
+#customer intent: As an Azure administrator or user, I want to resolve an issue in which Datadog isn't emitting metrics.
+
+---
+
+# Metrics not being emitted
+
+## Summary
+
+This article helps you resolve when Datadog isn't receiving metrics from Azure resources because the Datadog resource identity doesn't have the required Monitoring Reader role assignment.
+
+## Prerequisites
+
+- Access to the [Azure portal](https://portal.azure.com) with permissions to view access control (IAM) for the target subscription (Reader) and to assign roles (Contributor/Owner) if you will remediate the problem.
+- The Datadog resource identity (managed identity or service principal) name or principal ID.
+
+## Symptoms
+
+- Metrics from Azure resources don't appear in the Datadog UI.
+- The Datadog resource doesn't show a **Monitoring Reader** role assignment in the subscription's IAM list.
+
+## Cause
+
+Datadog requires the **Monitoring Reader** role on the appropriate Azure subscription to collect platform metrics. If the Datadog resource identity isn't assigned this role, Datadog can't read metrics and they won't be emitted to Datadog.
+
+## Solution 
+
+1. In the Azure portal, open the subscription that contains the resource.
+
+1. Select **Access control (IAM)**.
+
+1. On the **Role assignments** tab, search for the Datadog resource name.
+
+1. If you don't find a Monitoring Reader assignment for the Datadog identity, complete these steps to add one:
+
+   1. Select **Add** > **Add role assignment**.
+
+   1. On the **Role** tab, select **Monitoring Reader**, and then select **Next**.
+
+   1. In **Assign access to**, select **Managed identity** or **Service principal** as appropriate.
+
+   1. Select the Datadog resource identity and then choose **Select**.
+
+1. Wait a few minutes for role-based access control (RBAC) propagation, and then verify that Datadog is receiving metrics.
+
+> [!warning]
+> If you remove the system managed identity or the Monitoring Reader role assignment, Datadog can't collect metrics from your Azure resources.
+
+> [!Note]
+> Confirm that the Datadog identity is the one used by the Datadog integration (managed identity versus service principal). If you assign the role to the wrong principal, Datadog won't receive metrics.
+
+## Resources
+
+- [Azure role-based access control (RBAC)](/azure/role-based-access-control/)
+- [Assign Azure roles using the Azure CLI](/azure/role-based-access-control/role-assignments-cli)
+- [Datadog Azure integration documentation](https://docs.datadoghq.com/integrations/azure/)
diff --git a/support/azure/partner-solutions/index.yml b/support/azure/partner-solutions/index.yml
@@ -62,22 +62,33 @@ landingContent:
 # Card
   - title: Astro 
     linkLists:
-    - linkListType: how-to-guide
-      links:
-        - text: Can't create Astro resources in Azure  
-          url: astro/resource-creation.md
-        - text: Can't install Astro using a personal email
-          url: astro/personal-email.md
-        - text: Unable to use single sign-on in Astronomer portal
-          url: astro/single-sign-on.md
+      - linkListType: how-to-guide
+        links:
+          - text: Can't create Astro resources in Azure  
+            url: astro/resource-creation.md
+          - text: Can't install Astro using a personal email
+            url: astro/personal-email.md
+          - text: Unable to use single sign-on in Astronomer portal
+            url: astro/single-sign-on.md
 
 # Card
-  - title: Informatica
+  - title: Datadog
     linkLists:
       - linkListType: how-to-guide
         links:
-          - text: Issues creating Informatica resources in Azure
-            url: informatica/resource-creation.md 
+          - text: Datadaog agent installation fails, or default API key is incorrect
+            url: datadog/installation-fails.md
+          - text: Metrics not being emitted
+            url: datadog/metrics-not-emitted.md
+
+# Card
+  - title:  Informatica
+    linkLists:
+    - linkListType: how-to-guide
+      links:
+        - text: Issues creating Informatica resources in Azure
+          url: informatica/resource-creation.md
+ 
 
 # Card        
   - title: Observability partners
diff --git a/support/azure/partner-solutions/toc.yml b/support/azure/partner-solutions/toc.yml
@@ -39,6 +39,8 @@ items:
       href: astro/single-sign-on.md
 - name: Datadog
   items: 
+    - name: Datadaog agent installation fails, or default API key is incorrect
+      href: datadog/installation-fails.md
     - name: Diagnostic settings manual update
       href: diagnostic-settings-manual-update.md
     - name: Diagnostic settings not created
@@ -47,6 +49,8 @@ items:
       href: log-forwarding-persists.md
     - name: Log limitations
       href: log-limitations.md
+    - name: Metrics not being emitted
+      href: datadog/metrics-not-emitted.md
 - name: Dynatrace
   items: 
     - name: AKS agent installation/uninstallation unavailable
