How to Migrate a Datadog Organization: A Step-by-Step Guide Org Migration

Migrating a Datadog organization is a complex but necessary process when consolidating accounts, restructuring teams, or implementing new security and compliance strategies. This guide walks you through the key aspects of Datadog org migration, covering asset migration, challenges with telemetry history, strategies for sharing metrics, forwarding logs, and best practices for communication.

Why Migrate a Datadog Organization?

Organizations may need to migrate Datadog environments for several reasons:

• Merging teams or business units under a single Datadog account.
• Ensuring compliance with security and governance policies. For instance, migrating to the EU instance of Datadog for GDPR compliance.
• Separating environments due to restructuring or acquisitions.
• Optimizing billing and cost allocation across teams.

Regardless of the reason, a smooth migration plan is critical to minimizing disruptions to monitoring, alerting, and observability workflows.

Migrating Key Assets

One of the first steps for any migration is transferring various assets and configurations from one organization to another. Datadog offers a sync CLI (Datadog Sync CLI) that covers some of the most common assets to migrate. With one command, the tool automatically queries the API of the source organization and applies the relevant changes to the new organization.

Even though the sync CLI is the recommended method, a previous Python script was also available for part of the assets. If custom logic is required, this script can be a good starting point.

Final note, if teams are accustomed to specific dashboard layouts, maintaining familiarity during migration is crucial. Consider linking the old dashboard to the new one and vice versa during the transition.

Handling Telemetry History

One of the key limitations of Datadog organization migration is that telemetry history is difficult or not feasible to migrate. Historical logs, traces, and metrics are stored within a specific Datadog account and do not transfer easily across organizations.

What Does This Mean?

• The new organization will not have access to previously collected data by default and will start with a clean slate.
• The old organization will retain historical data. Users needing past data will need to log back into the old org to query it.
  • Most dropdowns and trend-based insights depend on recently received data so manual input will be required at some point but historical data will be kept for the retention period mentioned in the documentation.

Why would you need history in the new org?

• Trend analysis: Troubleshooting often requires comparing past behaviors to identify changes. If errors occur consistently at a low level, a sudden increase in pattern may indicate a problem. For instance, an error that occurs at a high rate but is consistent across time is often ignored to understand the root cause since it is not unusual.
• Machine learning monitors: Anomaly monitors rely on historical patterns. For instance, an anomaly monitor analyzing weekly trends will require at least two weeks of data to establish a baseline. Consider temporarily adjusting alert thresholds to compensate for missing historical data.

Strategies for Sharing Metrics Between Organizations

Generic options

One of the simplest (but with additional cost) solutions for sharing data between accounts is dual shipping (Dual Shipping Guide). This method requires advanced configuration to ensure that only essential data is sent to both accounts. This feature includes a high level of granular configuration to ensure only key data is transferred on both accounts.

Dual Shipping

Datadog, the leading service for cloud-scale monitoring.

Datadog Infrastructure and Application MonitoringDatadog

If using OpenTelemetry or Datadog Observability Pipelines, similar features exist for forwarding data to multiple destinations.

Metric specific

Datadog retains metrics for 15 months by default, which is useful for understanding trends.

Options:

• Cross-org visibility: Datadog now supports cross-org visibility for metrics (Cross-Org Visibility Guide). This feature allows dashboards to display metrics from multiple organizations but requires manual selection of the metric source.
• Custom scripts: Develop scripts to periodically export and import selected metrics. While this may add additional costs, it allows greater control over which data is transferred. Make sure to take into consideration rate limits when opting for such solution.

Log specific

Logs play a crucial role in troubleshooting and compliance. While other telemetry history may be difficult to move, logs can be forwarded to the new organization in real time.

Options:

• Reconfigure log sources (e.g., AWS Lambda, EC2, Kubernetes, or applications) to send logs to the new Datadog organization.
• Use Datadog log pipelines and custom destinations to forward logs between organizations (Log Forwarding Guide).

Forwarding Logs to Custom Destinations

Datadog, the leading service for cloud-scale monitoring.

Datadog Infrastructure and Application MonitoringDatadog

Migration Changes

While we just looked at how to handle the management of historical data on the new organization, this section covers at a high level the requirements for a change of destination.

Updating Agents and Integrations

For everything related to Datadog Agents and integrations, it is necessary to update the destination URL and API key. The complexity of this task depends on the automation available in your organization. For instance, with Kubernetes Operator, an upgrade will trigger an update of all agents, progressively redirecting reports to the new organization.

Overall, the level of complexity of changing an API key and destination depends a lot on the size of the organization but also to the level of automation in place to manage the agents.

Agentless

For Agentless integrations such as for the Cloud Providers, AWS, GCP, MongoDB Atlas, the integration will have to be configured in the new organization. In some cases, Datadog provide an API and/or a terraform module which could make the migration simpler.

• AWS API - AWS Terraform
• Azure API - Azure Terraform
• GCP API - GCP Terraform
• MS Teams API
• more (search for datadog_integration in the terraform resources)

Communication integrations

While the above are important, many organizations use third-party integrations for alerts (e.g., Slack, PagerDuty, email). Ensure all notification channels, webhooks, and alerting workflows are properly recreated in the new org.

Custom Scripts

Custom scripts interacting with the Datadog API also need to be updated to connect to the new organization. If unsure, enabling Datadog Audit Trail (additional product) can help identify API usage patterns and the owner of those keys.

For instance, one of the common usage of API is to maintain the configuration of various assets in Terraform.

RBAC

While the roles and some RBAC policies are transferred automatically with the Datadog Sync CLI, more granular and advanced policies may require manual configuration. Ensure that such configuration is implemented during migration.

Migrating to an Existing Organization

While the sections above primarily consider migration to a new organization, there are scenarios where consolidation into an existing organization is required—especially when multiple teams already have their telemetry reporting in a shared environment.

Asset Migration Considerations

In such cases, asset migration must be handled more carefully to avoid conflicts. Key considerations include:

Tagging

Analyzing the tagging structure of the destination organization is essential.

• Ensure compliance with existing naming conventions, such as env:prod vs. env:prd.
• Align cost allocation tags (cost_center:abc123 vs. project:mcnulty).
• If the current tagging system does not match, consider adjusting it before migration or as part of the migration process.

Naming Conventions

Similar to tagging, maintaining consistency in naming conventions across dashboards, monitors, and team structures ensures clarity and usability. Agreeing on naming standards before migration will help prevent confusion and redundant assets.

Effective Communication Plan

A successful Datadog migration depends on clear communication across all stakeholders.

Key Stakeholders:

• Engineering teams: Responsible for configuring monitoring and observability settings.
• SRE/Operations teams: Ensuring continuity of alerts and incident response.
• Security teams: Managing user access and compliance.
• Product managers and leadership: Understanding the impact of migration on business KPIs.

Best Practices for Communication:

• Create a migration timeline: Outline key phases and milestones.
• Document changes: Provide detailed guides on what’s moving, what’s staying, and how to access historical data.
• Hold training sessions: Educate teams on the new setup and access controls.
• Provide ongoing support: Set up a dedicated Slack channel or office hours for migration-related questions.

Conclusion

Migrating a Datadog organization requires careful planning and execution to ensure minimal disruption. By following best practices for asset migration, log forwarding, and dual shipping, teams can transition smoothly while maintaining monitoring coverage. Communication remains critical—keeping stakeholders informed ensures alignment throughout the process.

By implementing a structured migration approach, organizations can successfully transition to a new Datadog environment without losing valuable observability capabilities.