Overview

This onboarding guide walks platform and engineering leaders through the phases of implementing Datadog’s Internal Developer Portal (IDP).

Recommendations:

• Onboard one or two teams first, and use their feedback to refine standards.
• Iterate regularly—treat your Internal Developer Portal as a product.
• Connect IDP standards with other initiatives, such as SLOs, CI/CD pipelines, and incident workflows.

Phase 1: Plan your implementation

1. Review key concepts: Learn about the Entity model, Scorecards, and Self-service Actions.
2. Bring in your organization’s structure: Set up Teams and mirror your hierarchy in Datadog.
3. Define your ontology: Map your existing systems to the Entity model so your structure aligns with Datadog’s schema. Decide which entity types and validations you want to enforce.

Phase 2: Familiarize yourself with tooling

1. Identify data sources: Learn about the three ways to bring in entities, and decide what to use as sources of truth for your Software Catalog:

   • Automatically discover entries from Datadog products, such as APM, RUM, or USM. You can also import from Infrastructure or Log Management.
   • Import from external systems such as Backstage or ServiceNow.
   • Create entries directly through the Datadog UI, or programmatically by importing from GitHub, Terraform, the Datadog Software Metadata Provider, or the Service Definition API.

Note: If you use APM, prioritize Unified Service Tagging and Inferred Services as entry points, rather than relying on service overrides.

1. Create internal onboarding guidance: Document tagging standards, sample entity.definition.yaml files, and expectations for application teams.
2. Explore automation: Use the API or Terraform provider to manage entities, scorecards, and workflows programmatically.

Phase 3: Integrate data sources

1. Adopt GitOps-style management: Connect GitHub or other repos to manage your catalog. Import existing Backstage manifests if available.
2. Import from ServiceNow: Sync CIs from your ServiceNow CMDB into IDP.
3. Connect on-call and incident tools: Configure Jira, PagerDuty, or other integrations.

Phase 4: Customize and extend schema

1. Establish entity definition standards: Decide how you represent criticality, lifecycle, and environments. See Entity Model for definition schemas.
2. Set metadata expectations: Decide on whether to include custom tags and extensions. Determine how to define relationships between components, and how to audit automatically detected relationships.
3. Maintain internal guidance: Keep documentation for developers, such as standards for instrumentation and tagging, and sample entity definition manifests.

Phase 5: Establish and communicate standards

1. Review recommended Scorecards: Start with Datadog’s out-of-the-box rules. Select those relevant to your organization.
2. Add organization-specific rules: Extend scorecards with custom security checks, deployment frequency requirements, or tagging standards.
3. Set levels of criticality: Group rules into levels to signal importance.

Phase 6: Set up golden paths

1. Review example blueprints: Explore Self-service blueprints, which show example paths for infrastructure provisioning and management, project scaffolding, and more. Experiment with modifying the blueprints to fit your organization’s stack.
2. Explore the Action Catalog: See supported integrations, or extend with HTTP requests and private actions.
3. Publish your first workflow: Build a golden path and iterate based on developer feedback.

Phase 7: Explore engineering reports

1. Track progress: Use built-in Engineering Reports to monitor production readiness, reliability, and adoption of best practices.
2. Measure engagement: Monitor developer engagement through the built-in usage analytics dashboard.

Further reading

Additional helpful documentation, links, and articles:

Getting started with Internal Developer PortalDOCUMENTATION Software CatalogDOCUMENTATION ScorecardsDOCUMENTATION Self-service ActionsDOCUMENTATION Engineering ReportsDOCUMENTATION