Getting Started with Internal Developer Portal

Docs > Getting Started > Getting Started with Internal Developer Portal

Overview

Datadog’s Internal Developer Portal (IDP) helps you unify software metadata, live telemetry, and developer workflows in a single platform. This guide walks you through setting up each core IDP component:

Software Catalog: Real-time inventory of entities and environments, enriched with ownership and operational metadata.
Scorecards: Measure adoption of engineering best practices using rules-based evaluations.
Self-Service Actions: Enable developers to execute standardized tasks with a single click.
Engineering Reports: Visualize quality, reliability, and compliance metrics across your stack.
Overview Pages: Give developers and teams a personalized view of their entities, issues, and action items.

Whether you’re starting from scratch or integrating with existing systems like Backstage or ServiceNow, use this guide to get started with IDP.

Prerequisites

If you have not already, create a Datadog account.

Step 1: Populate Software Catalog

IDP starts with Software Catalog, a real-time inventory of your software architecture’s key building blocks. In Datadog, these are called entities—they can represent individual services, APIs, or grouped Systems.

You can add entities from:

APM, USM, and RUM: Automatically discovered based on application telemetry
Manual definitions: Created through Datadog or imported through tools like Terraform, Datadog APIs, or the GitHub integration
Third-party systems: Through integrations with ServiceNow and Backstage

Start with a basic definition to register the entity, then enrich it with metadata to add ownership and operational context, including:

Ownership info and team contacts
Documentation, dashboards, runbooks
Deployment pipelines and config links
Production readiness data through unified service tagging

The following example defines a system entity representing an application composed of multiple services. It includes metadata such as display name, ownership, contacts, related documentation, integrations, and associated service components.

entity.datadog.yaml

apiVersion: v3
  kind: system
  metadata:
    name: myapp
    displayName: My App
    tags:
      - tag:value
    links:
      - name: shopping-cart runbook
        type: runbook
        url: https://runbook/shopping-cart
      - name: shopping-cart architecture
        provider: gdoc
        url: https://google.drive/shopping-cart-architecture
        type: doc
      - name: shopping-cart Wiki
        provider: wiki
        url: https://wiki/shopping-cart
        type: doc
      - name: shopping-cart source code
        provider: github
        url: http://github/shopping-cart
        type: repo
    contacts:
      - name: Support Slack
        type: slack
        contact: https://www.slack.com/archives/shopping-cart
    owner: myteam
    additionalOwners:
      - name: opsTeam
        type: operator
  integrations:
    pagerduty:
      serviceURL: https://www.pagerduty.com/service-directory/Pshopping-cart
  spec:
    components:
      - service:myservice
      - service:otherservice

Read the Software Catalog setup guide to learn how to add or import entities, and review the entity model reference for schema details.

Step 2: Evaluate entity quality with Scorecards

Use Scorecards to assess whether entities meet your organization’s standards. Scorecards can measure:

Monitoring coverage
Production readiness
Security posture
Internal tooling adoption
Ownership and documentation

Datadog Scorecards include 10 out-of-the-box rules across observability practices, ownership tagging, and production readiness checkpoints. You can group rules into levels to categorize them by their criticality-level 1 (basic expectations), level 2 (recommended practices), and level 3 (advanced/aspirational goals).

In addition to using default rules, you can define custom rules to reflect your internal standards:

Go to the Scorecards page and click Create Rule.
Specify the rule name, the scorecard it belongs to, a description, and the owning team.
Send an outcome of pass, fail, or skip for each entity in one of the following ways:
- Manually through the Datadog UI
- Programmatically through the Scorecards API
- Automatically, using Workflow Automation to post outcomes on a schedule
View an overview of outcomes on the Scorecards page.

Learn more about scorecard configuration and custom rules in the Scorecards documentation.

Step 3: Use Self-Service Actions

Self-Service Actions let you run repeatable tasks through a UI or API. For example, use Self-Service Actions to:

Actions can be backed by automation systems like Terraform, GitHub Actions, or internal scripts. Self Service Actions offer over 1000+ pre-built integrations with tools across source code management (for example, GitHub and GitLab), ticketing and incident management (for example, Jira, ServiceNow, and PagerDuty), chat (for example, Slack and Microsoft Teams), cloud providers (for example, AWS, GCP, and Azure), and more. You can connect with any additional endpoints, including private resources, leveraging HTTP requests and private action runners.

Get started by exploring the Self-Service Actions Blueprint Library in Datadog for example apps that you can customize for your use case.

To start automating developer workflows, explore the Self-Service Actions documentation.