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.
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:v3kind:systemmetadata:name:product-recommendationdescription:Surfaces personalized product suggestions in ShopistdisplayName:"Product Recommendation"tags:- product:recommendations- business-line:shared-componentsowner:shopistadditionalOwners:- name:Shopist Support Teamtype:Operatorspec:lifecycle:productiontier:"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.
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
YAML definition for an inferred datastore
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.
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.
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
YAML for an inferred queue
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.
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.
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.
