In APM, a service (kind:service) is a group of related endpoints, queries, or jobs that perform a piece of work for your application. For example, a service could be a group of endpoints, a group of DB queries, or a group of periodic jobs.

Through custom instrumentation in APM, you can create an arbitrary service. In practice, microservice-based architecture includes multiple APM services, each measuring the performance of sub-components of the application through Trace Metrics.

In Software Catalog, you can collect non-instrumented services by declaring them through metadata or importing through external sources like Backstage or ServiceNow.

In Software Catalog, a system (kind:system) is a group of entities that cooperate to perform a broader function. For example, you can group multiple instrumented APM services into a system because they are operated by the same team. You can also use system to represent a full microservice-based architecture, and include components like APIs, datastores, queues, and other common building blocks.

Note: System in Datadog has the same meaning as in Backstage’s System Model.

To define components within a system, you can specify values for the components key in the spec field of the entity’s v3 definition.

Example YAML for kind:system:

apiVersion: v3
kind: system
metadata:
  name: product-recommendation
  description: Surfaces personalized product suggestions in Shopist
  displayName: "Product Recommendation"
  tags:
  - product:recommendations
  - business-line:shared-components
  owner: shopist
  additionalOwners:
    - name: Shopist Support Team
      type: Operator
spec:
  lifecycle: production
  tier: "0"
  components:
  - service: product-recommendation
  - service: orders-app
  - api: products
  - system: shopist-user-trends

This user-defined system appears in Software Catalog as shown:

This page holds relationship data of components between the system and upstream/downstream dependencies as well as scorecards, logs, and events aggregated across all system components.

Note: If a single component is part of multiple systems, you must specify that component in the YAML for each system.

In Software Catalog, an API (kind:API) refers to a collection of endpoints that belong together logically. APIs offer an alternative way to group endpoints beyond APM services (the mapping between endpoints and services are not modifiable).

To define components within an API, you can specify values for the components key in the spec field of the entity’s v3 definition.

Example YAML for kind:api:

{
 "apiVersion": "v3",
 "kind": "api",
 "metadata": {
   "name": "payments",
   "displayName": "Payments",
   "owner": "Payments Team",
   "links": [
     {
       "name": "Deployment Information",
       "type": "doc",
       "url": "https://wiki/products
"
     },
     {
       "name": "Source",
       "type": "repo",
       "provider": "github",
       "url": "https://github.com/"
     },
     {
       "name": "Performance Dashboard",
       "type": "dashboard",
       "url": "https://datadoghq.com"
     }
   ]
 },
 "integrations": {
   "pagerduty": {
     "serviceURL": "https://www.pagerduty.com/service-directory/products"
   }
 },
 "spec": {
   "type": "openapi",
   "implementedBy": [
     "service:payment",
     "service:payments-go"
   ],
   "interface": {
     "definition": {
       "info": {
         "title": "Payments"
       },
       "openapi": "3.0.0",
       "paths": {
         "/add_item": {
           "post": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         },
         "/add_purchases": {
           "post": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         },
         "/admin/update_user": {
           "post": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         },
         "/carts": {
           "get": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         }
       }
     }
   },
   "lifecycle": "production",
   "tier": "Tier 0"
 }
}

The user-defined API appears in Software Catalog as shown:

This page holds relationship data of how the API interacts with dependencies, the API components, an OpenAPI preview, and logs and events aggregated across all endpoints.

Note: Software Catalog contains HTTP endpoints that are automatically discovered by APM. The concept of endpoints correspond to APM resources for an APM web service.

In Software Catalog, a datastore (kind:datastore) represents a data storage component or database that services depend on. Datastores can represent relational databases (such as PostgreSQL or MySQL), NoSQL datastores (such as Redis or MongoDB), data warehouses, and caches.

Datastore entities can be:

• Inferred by APM when instrumented services make outbound calls to a database (for example, a PostgreSQL query).
• Manually defined to represent uninstrumented datastores or enrich inferred ones with additional metadata.

Note: If Database Monitoring is enabled, the datastore entity page displays query throughput, latency, and error rates. Otherwise, the page shows basic trace-derived metrics and dependency relationships.

Example YAML definitions

apiVersion: v3
kind: datastore
metadata:
  name: peer.db.name:web-store-mongo,peer.db.system:mongodb                
  displayName: "Store Inventory DB (MongoDB)"   
  description: Stores order transaction data for Shopist e-commerce
  owner: shopist            
  additionalOwners:
    - name: infra-team
      type: team
  links:
    - name: "DB Runbook"
      type: runbook
      url: https://wiki.internal/runbooks/orders-db
    - name: "Schema Repo"
      type: repo
      provider: github
      url: https://github.com/org/orders-db-schema
integrations:
  pagerduty:
    serviceURL: https://pagerduty.com/services/ORD123  
spec:
  lifecycle: "production"              
  tier: "Tier 1"               

apiVersion: v3
kind: datastore
metadata:
  name: web-store-mongo               
  displayName: "Store Inventory DB (MongoDB)"   
  description: Stores order transaction data for Shopist e-commerce
  owner: shopist            
  additionalOwners:
    - name: infra-team
      type: team
  links:
    - name: "DB Runbook"
      type: runbook
      url: https://wiki.internal/runbooks/orders-db
    - name: "Schema Repo"
      type: repo
      provider: github
      url: https://github.com/org/orders-db-schema
integrations:
  pagerduty:
    serviceURL: https://pagerduty.com/services/ORD123  
spec:
  lifecycle: "production"              
  tier: "Tier 1"               

Datastore peer tags

For inferred entities, Datadog uses standard span attributes to construct peer.* tags. The metadata.name value in your entity definition must exactly match the inferred peer tags. Manually defined datastores do not need to follow this convention.

Common peer tags for datastore entities:

Learn more about peer tags and inferred entities.

In Software Catalog, a queue (kind:queue) represents a message queue or stream-based messaging component that services interact with. Queues can represent systems such as Apache Kafka, Amazon SQS, RabbitMQ, and Google Pub/Sub.

Queue entities can be:

• Inferred by APM when instrumented services produce to or consume from a messaging system.
• Manually defined to represent uninstrumented queues or enrich inferred ones with additional metadata.

Note: If Data Streams Monitoring is enabled, the queue entity page displays metrics such as throughput, service latency, and processing errors. Otherwise, the page shows basic trace-derived metrics and service dependency relationships.

Example YAML definitions

apiVersion: v3
kind: queue
metadata:
  name: peer.messaging.destination:checkout-events
  displayName: "Checkout Events Queue (Kafka)"
  description: Captures all checkout-related events for downstream processing
  owner: shopist
  additionalOwners:
    - name: platform-team
      type: team
  links:
    - name: "Queue Runbook"
      type: runbook
      url: https://wiki.internal/runbooks/checkout-events
    - name: "Schema Repo"
      type: repo
      provider: github
      url: https://github.com/org/checkout-schema
integrations:
  pagerduty:
    serviceURL: https://pagerduty.com/services/MESSAGING123
spec:
  lifecycle: "production"
  tier: "Tier 1"

apiVersion: v3
kind: queue
metadata:
  name: checkout-events-kafka
  displayName: "Checkout Events Queue (Kafka)"
  description: Captures all checkout-related events for downstream processing
  owner: shopist
  additionalOwners:
    - name: platform-team
      type: team
  links:
    - name: "Queue Runbook"
      type: runbook
      url: https://wiki.internal/runbooks/checkout-events
    - name: "Schema Repo"
      type: repo
      provider: github
      url: https://github.com/org/checkout-schema
integrations:
  pagerduty:
    serviceURL: https://pagerduty.com/services/MESSAGING123
spec:
  lifecycle: "production"
  tier: "Tier 1"

Queue peer tags

For inferred entities, Datadog uses standard span attributes to construct peer.* tags. The metadata.name value in your entity definition must exactly match the inferred peer tags. Manually defined queues do not need to follow this convention.

Common peer tags for kind:queue entities:

Learn more about peer tags and inferred entities.

You can define custom entity types beyond service, system, datastore, queue, and API. Custom entities allow you to represent any component or resource that is important to your organization but does not fit into the standard categories.

First, define the kinds you want to use with this API. Only entities of the kinds you’ve explicitly setup are accepted. In the example below, a user is declaring a library with links, tags, and owning teams.

Example YAML:

  apiVersion: v3
  kind: library
  metadata:
    name: my-library
    displayName: My Library
    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 Email
        type: email
        contact: team@shopping.com
      - name: Support Slack
        type: slack
        contact: https://www.slack.com/archives/shopping-cart
    owner: myteam
    additionalOwners:
      - name: opsTeam
        type: operator