|
| 1 | +--- |
| 2 | +title: Getting Started with Internal Developer Portal |
| 3 | +aliases: |
| 4 | + - /getting_started/service_catalog |
| 5 | + - /getting_started/software_catalog/ |
| 6 | +further_reading: |
| 7 | + - link: '/internal_developer_portal' |
| 8 | + tag: 'Documentation' |
| 9 | + text: 'Internal Developer Portal' |
| 10 | + - link: '/internal_developer_portal/software_catalog/' |
| 11 | + tag: 'Documentation' |
| 12 | + text: 'Software Catalog' |
| 13 | + - link: 'https://learn.datadoghq.com/courses/managing-service-catalog' |
| 14 | + tag: 'Learning Center' |
| 15 | + text: 'Managing Services with the Service Catalog' |
| 16 | + - link: 'https://www.datadoghq.com/blog/service-owner-knowledge-with-datadog-service-catalog/' |
| 17 | + tag: 'Blog' |
| 18 | + text: 'Simplify microservice governance with the Datadog Service Catalog' |
| 19 | + - link: '/internal_developer_portal/scorecards' |
| 20 | + tag: 'Documentation' |
| 21 | + text: 'Scorecards' |
| 22 | + - link: '/internal_developer_portal/self_service_actions' |
| 23 | + tag: 'Documentation' |
| 24 | + text: 'Self-Service Actions' |
| 25 | + - link: '/internal_developer_portal/eng_reports' |
| 26 | + tag: 'Documentation' |
| 27 | + text: 'Engineering Reports' |
| 28 | + - link: '/internal_developer_portal/overview_pages' |
| 29 | + tag: 'Documentation' |
| 30 | + text: 'Overview Pages' |
| 31 | +--- |
| 32 | + |
| 33 | +{{< img src="tracing/internal_developer_portal/scrolling_the_catalog.mp4" alt="A video that scrolls through the Internal Developer Portal Catalog page and clicks on a service to show a dependency graph with parent and child services represented" video=true >}} |
| 34 | + |
| 35 | +## Overview |
| 36 | + |
| 37 | +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: |
| 38 | + |
| 39 | +- [Software Catalog][1]: Real-time inventory of entities and environments, enriched with ownership and operational metadata. |
| 40 | +- [Scorecards][2]: Measure adoption of engineering best practices using rules-based evaluations. |
| 41 | +- [Self-Service Actions][3]: Enable developers to execute standardized tasks with a single click. |
| 42 | +- [Engineering Reports][4]: Visualize quality, reliability, and compliance metrics across your stack. |
| 43 | +- [Overview Pages][5]: Give developers and teams a personalized view of their entities, issues, and action items. |
| 44 | + |
| 45 | +Whether you're starting from scratch or integrating with existing systems like Backstage or ServiceNow, use this guide to get started with IDP. |
| 46 | + |
| 47 | + |
| 48 | +## Prerequisites |
| 49 | + |
| 50 | +If you have not already, create a [Datadog account][6]. |
| 51 | + |
| 52 | +## Step 1: Populate Software Catalog |
| 53 | + |
| 54 | +IDP starts with [Software Catalog][1], 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. |
| 55 | + |
| 56 | +You can add entities from: |
| 57 | + |
| 58 | +- [APM, USM, and RUM][7]: Automatically discovered based on application telemetry |
| 59 | +- [Manual definitions][8]: Created through [Datadog][9] or imported through tools like Terraform, Datadog APIs, or the GitHub integration |
| 60 | +- [Third-party systems][10]: Through integrations with ServiceNow and Backstage |
| 61 | + |
| 62 | +Start with a basic definition to register the entity, then enrich it with metadata to add ownership and operational context, including: |
| 63 | +- Ownership info and team contacts |
| 64 | +- Documentation, dashboards, runbooks |
| 65 | +- Deployment pipelines and config links |
| 66 | +- Production readiness data through unified service tagging |
| 67 | + |
| 68 | +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. |
| 69 | + |
| 70 | +{{< code-block lang="yaml" filename="entity.datadog.yaml" disable_copy="true" collapsible="true" >}} |
| 71 | +apiVersion: v3 |
| 72 | + kind: system |
| 73 | + metadata: |
| 74 | + name: myapp |
| 75 | + displayName: My App |
| 76 | + tags: |
| 77 | + - tag:value |
| 78 | + links: |
| 79 | + - name: shopping-cart runbook |
| 80 | + type: runbook |
| 81 | + url: https://runbook/shopping-cart |
| 82 | + - name: shopping-cart architecture |
| 83 | + provider: gdoc |
| 84 | + url: https://google.drive/shopping-cart-architecture |
| 85 | + type: doc |
| 86 | + - name: shopping-cart Wiki |
| 87 | + provider: wiki |
| 88 | + url: https://wiki/shopping-cart |
| 89 | + type: doc |
| 90 | + - name: shopping-cart source code |
| 91 | + provider: github |
| 92 | + url: http://github/shopping-cart |
| 93 | + type: repo |
| 94 | + contacts: |
| 95 | + - name: Support Slack |
| 96 | + type: slack |
| 97 | + contact: https://www.slack.com/archives/shopping-cart |
| 98 | + owner: myteam |
| 99 | + additionalOwners: |
| 100 | + - name: opsTeam |
| 101 | + type: operator |
| 102 | + integrations: |
| 103 | + pagerduty: |
| 104 | + serviceURL: https://www.pagerduty.com/service-directory/Pshopping-cart |
| 105 | + spec: |
| 106 | + components: |
| 107 | + - service:myservice |
| 108 | + - service:otherservice |
| 109 | +{{< /code-block >}} |
| 110 | + |
| 111 | +Read the [Software Catalog setup guide][11] to learn how to add or import entities, and review the [entity model reference][12] for schema details. |
| 112 | + |
| 113 | +## Step 2: Evaluate entity quality with Scorecards |
| 114 | + |
| 115 | +Use Scorecards to assess whether entities meet your organization's standards. Scorecards can measure: |
| 116 | +- Monitoring coverage |
| 117 | +- Production readiness |
| 118 | +- Security posture |
| 119 | +- Internal tooling adoption |
| 120 | +- Ownership and documentation |
| 121 | + |
| 122 | +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). |
| 123 | + |
| 124 | +In addition to using default rules, you can define custom rules to reflect your internal standards: |
| 125 | + |
| 126 | +1. Go to the [Scorecards page][13] and click Create Rule. |
| 127 | +1. Specify the rule name, the scorecard it belongs to, a description, and the owning team. |
| 128 | +1. Send an outcome of `pass`, `fail`, or `skip` for each entity in one of the following ways: |
| 129 | + - Manually through the Datadog UI |
| 130 | + - Programmatically through the Scorecards API |
| 131 | + - Automatically, using [Workflow Automation][14] to post outcomes on a schedule |
| 132 | +1. View an overview of outcomes on the [Scorecards page][13]. |
| 133 | + |
| 134 | +Learn more about scorecard configuration and custom rules in the [Scorecards documentation][2]. |
| 135 | + |
| 136 | +## Step 3: Use Self-Service Actions |
| 137 | + |
| 138 | +Self-Service Actions let you run repeatable tasks through a UI or API. For example, use Self-Service Actions to: |
| 139 | +- [Create an S3 bucket with Terraform][16] |
| 140 | +- [Scaffold a new project in GitHub][17] |
| 141 | +- [Manage Kubernetes deployments][18] |
| 142 | + |
| 143 | +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. |
| 144 | + |
| 145 | +Get started by exploring the Self-Service Actions [Blueprint Library][19] in Datadog for example apps that you can customize for your use case. |
| 146 | + |
| 147 | +To start automating developer workflows, explore the [Self-Service Actions documentation][3]. |
| 148 | + |
| 149 | +## Step 4: Monitor engineering health with reports |
| 150 | + |
| 151 | +Engineering Reports provide an at-a-glance view of: |
| 152 | +- Scorecards performance across all teams |
| 153 | +- Org-wide reliability trends based on SLOs and incident performance |
| 154 | +- Velocity and stability of software development |
| 155 | + |
| 156 | +Explore [Engineering Reports][20] in the Datadog app. These reports are automatically generated and updated in real time. |
| 157 | + |
| 158 | +Read the [Engineering Reports documentation][4] for more details on available reports and configuration options. |
| 159 | + |
| 160 | +## Step 5: Use overview pages for personalized insights |
| 161 | + |
| 162 | +Overview pages surface high-level metrics and action items tailored to individual contributors and teams. |
| 163 | + |
| 164 | +Start with the [developer overview page][21], which shows: |
| 165 | +- Your open Jira tickets and GitHub PRs |
| 166 | +- Your team's Monitors, Incidents, SLOs, and Scorecards |
| 167 | +- Active issues, errors, and Watchdog alerts |
| 168 | + |
| 169 | +For setup and customization tips, read the [Overview Pages documentation][22]. |
| 170 | + |
| 171 | + |
| 172 | +## Further reading |
| 173 | + |
| 174 | +{{< partial name="whats-next/whats-next.html" >}} |
| 175 | + |
| 176 | +[1]: /internal_developer_portal/software_catalog/ |
| 177 | +[2]: /internal_developer_portal/scorecards/ |
| 178 | +[3]: /internal_developer_portal/self_service_actions |
| 179 | +[4]: /internal_developer_portal/eng_reports |
| 180 | +[5]: /internal_developer_portal/overview_pages |
| 181 | +[6]: https://www.datadoghq.com/ |
| 182 | +[7]: /internal_developer_portal/software_catalog/set_up/discover_entities/ |
| 183 | +[8]: /internal_developer_portal/software_catalog/set_up/create_entities/ |
| 184 | +[9]: https://app.datadoghq.com/software |
| 185 | +[10]: /internal_developer_portal/software_catalog/set_up/import_entities/ |
| 186 | +[11]: /internal_developer_portal/software_catalog/set_up/ |
| 187 | +[12]: /internal_developer_portal/software_catalog/entity_model/entity_types/ |
| 188 | +[13]: https://app.datadoghq.com/software/scorecards |
| 189 | +[14]: https://app.datadoghq.com/workflow/blueprints?selected_category=SCORECARDS |
| 190 | +[16]: https://app.datadoghq.com/app-builder/apps/edit?startModalOpen=false&template=create-new-s3-bucket&viewMode=templatePreview |
| 191 | +[17]: https://app.datadoghq.com/app-builder/apps/edit?startModalOpen=false&template=scaffold-github&viewMode=templatePreview |
| 192 | +[18]: https://app.datadoghq.com/app-builder/apps/edit?startModalOpen=false&template=manage-kubernetes-deployments&viewMode=templatePreview |
| 193 | +[19]: https://app.datadoghq.com/software/self-service-actions |
| 194 | +[20]: https://app.datadoghq.com/idp/reports |
| 195 | +[21]: https://app.datadoghq.com/idp/overview/developer |
| 196 | +[22]: /internal_developer_portal/overview_pages/ |
0 commit comments