Overview

In Software Catalog, an entity represents the smallest building block of modern microservice-based architecture. As of schema definition v3.0+, an entity can be an instrumented APM service, a datastore, a system, an API, a queue, or even a custom-defined entity.

See GitHub for full schema definitions.

Entity types

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:

entity.datadog.yaml

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:

System page for Product Recommendations system in Software Catalog

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:

entity.datadog.yaml

{
 "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:

API page for Payments API in Software Catalog

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

This example shows a kind:datastore definition for a database automatically detected by APM.

Note: The metadata.name value must exactly match the peer tags used by APM.

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"               

This example shows a kind:datastore definition for a manually declared datastore.

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:

Peer TagSource Attributes
peer.aws.dynamodb.tabletablename
peer.aws.s3.bucketbucketname, aws.s3.bucket
peer.cassandra.contact.pointsdb.cassandra.contact.points
peer.couchbase.seed.nodesdb.couchbase.seed.nodes
peer.db.namedb.name, mongodb.db, db.instance, cassandra.keyspace, db.namespace
peer.db.systemdb.system

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

This example shows a kind:queue definition for a queue automatically detected by APM.

Note: The metadata.name value must exactly match the peer tags used by APM.

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"

This example shows a kind:queue definition for a manually declared queue.

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:

Peer TagSource Attributes
peer.aws.kinesis.streamstreamname
peer.aws.sqs.queuequeuename
peer.kafka.bootstrap.serversmessaging.kafka.bootstrap.servers
peer.messaging.destinationtopicname, messaging.destination, messaging.destination.name, messaging.rabbitmq.exchange, amqp.destination, ampqb.queue, amqp.exchange, msmq.queue.path, aws.queue.name
peer.messaging.systemmessaging.system

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.

Example YAML:

entity.datadog.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
  

Further reading