EDU-576: Datadog integration

Author: franrob-projects

content/datadog.textile

@@ -0,0 +1,83 @@
+---
+title: Ably Datadog integration
+meta_description: "Connect Ably and Datadog to monitor messages, channels, and connections in realtime, integrating your Ably metrics with your existing Datadog setup."
+meta_keywords: "Datadog, integrations, metrics, monitoring, analytics, enterprise"
+---
+
+The Ably "Datadog":https://docs.datadoghq.com/integrations/ably/ integration allows "enterprise":/pricing/enterprise users to monitor realtime application metrics like "messages":/messages, "channels":/channels, and connections within Datadog. Data streams every 60 seconds make tracking key performance indicators easier in one place. If you require access, contact "support":https://ably.com/support to enable the integration feature via your "dashboard":https://ably.com/accounts/any.
+
+If you're on the Ably "Pro plan":/pricing/pro, you can enable a limited Datadog-lite integration. "Standard plan":/pricing/standard users may request a 30-day trial to evaluate Datadog-lite before upgrading. This version includes a smaller set of metrics but still provides visibility into your Ably usage. If you need detailed analytics, per-channel breakdowns, custom dashboards, or advanced logging, upgrade to the full Datadog integration available on the Enterprise plan.
+
+|_. Feature |_. Datadog-lite |_. Full Datadog (Enterprise) |
+| Messages | ✅ | ✅ |
+| Connections | ✅ | ✅ |
+| Channels | ✅ | ✅ |
+| Bandwidth | ✅ | ✅ |
+| Message size | ✅ | ✅ |
+| Message direction breakdown (Inbound vs. Outbound) | ❌ | ✅ |
+| Per-Channel metrics | ❌ | ✅ |
+| Usage analytics & trends | ❌ | ✅ |
+| Custom dashboards & alerts | ❌ | ✅ |
+| Advanced logging & debugging | ❌ | ✅ |
+
+
+Ably includes @AppID@ and @AccountID@ tags with each metric to help with data organization. These ID tags enable you to filter, group, and analyze information efficiently, making it more manageable to spot trends and diagnose issues in your Datadog "dashboard":https://docs.datadoghq.com/dashboards/.
+
+To connect Ably and Datadog, you must authorize the integration through Datadog's "OAuth":https://docs.datadoghq.com/developers/integrations/oauth_for_integrations/ flow. This process requires the @api_keys_write@ scope, allowing Ably to push data to your Datadog account. Once the integration is active, Datadog provides a default Ably "dashboard":https://docs.datadoghq.com/integrations/ably/ so that you can monitor key metrics without extra setup.
+
+Every 60 seconds, Ably streams "statistics":https://ably.com/docs/metadata-stats/stats to the Datadog API using the generated API key. Metrics come from channels like @[meta]stats.minute@ and include App ID and Account ID tags. Datadog then displays these metrics in the Ably dashboard, giving you a clear view of messages, channels, and connections.
+
+h2. Set up the Ably Datadog integration
+
+Initiate the integration from the Datadog:
+
+# In Datadog, go to *Integrations*, find the *Ably* tile, and click *Install Integration*.
+# Click *Connect Accounts* to start the authorization process. Datadog redirects you to Ably.
+# Log in to your *Ably* account.
+# Select your application from the *Your Apps* page.
+# In the Ably dashboard, navigate to *Integrations* and select *Connect to Datadog*.
+# When prompted in Datadog, authorize Ably using *OAuth* to grant access. The required authorization scope is: @api_keys_write@.
+# After completing authorization, return to the Ably dashboard. A confirmation banner appears, along with a *See Dashboard* button that takes you to your Datadog dashboard.
+
+h3. Troubleshoot
+
+If the provided information does not resolve your issue, contact Ably "support":https://ably.com/support. When contacting, include details such as your app ID, and any relevant logs to help troubleshoot.
+
+h4. Integration stuck in “Connecting…”
+
+If your connection remains in this state, your setup may have been interrupted.
+
+For example, this can occur when a message is published while the connection is in a suspended state.
+
+*Resolution*: Reauthorize the integration.
+
+h4. Connection failed
+
+If the connection fails, it may be due to incorrect network settings or insufficient OAuth permissions in Datadog.
+
+For example, this can happen if the OAuth scope @api_keys_write@ was not granted during authorization or if network restrictions block communication between Ably and Datadog.
+
+*Resolution*: Verify your network settings and ensure the required OAuth permissions are granted in Datadog.
+
+h4. Duplicate API key
+
+If Datadog notifies you that an API key with this name already exists, it means a key with the same identifier has already been stored in your Datadog account.
+
+For example, this can happen if the integration was previously set up and an existing API key was not removed before attempting a new connection.
+
+*Resolution*: Remove or rename the existing API key in Datadog, then re-initiate the integration.
+
+h2. Remove access
+
+Removing access disconnects Ably from Datadog, stopping data transmission and revoking authorization. Follow the steps below to remove access from both platforms.
+
+h3. Remove access in Ably
+
+* Open your application's integration settings.
+* Click *Remove* next to the Datadog integration.
+* Ably revokes OAuth credentials and stops metric transmission.
+
+h3. Remove access in Datadog
+
+* Remove associated Ably API keys via *Integrations* or *API Keys*.
+* Adjust scopes or entirely revoke OAuth tokens if necessary.