Entities

The Cisco Observability Platform enables you to model entities and observe them. An entity represents a logical component in your solution and/or an application. An entity has attributes and tags. Entity has an associated health and a lifecycle that can be monitored. Examples of entities are REST endpoint, Service, Container, Disk, Thread, JVM, Topic, Database, Router, Cache and so on.

Entity properties help uniquely identify an entity. The entity properties are collection of immutable key/value pairs that together uniquely identify an entity. Hence, it is important to accurately define them in the domain model initially. An entity consists of the following properties:

An entity may have the following data associated with it through an external reference to its unique identifier:

• metrics (entityId)

• events (entityId)

• spans

• associations (from, to)

When you build an observability solution for any domain, it is important to understand how that domain uses the MELT data to represent aspects like performance, availability, functionality, security, and so on of any given entity.

Entity Types

Entities are categorised into specific types. Entity Types help in modelling different entities that are discovered from various sources. Type refers to a specific category of an entity - for example, disk, machine, instance, service are different types of entities. Characteristics of an entity are governed by the type.

You must define an entity type in the domain model schema for all entities created in the Cisco Observability Platform.

An entity type comprises following properties:

associationTypes:
  'common:consists_of':
    - 'infra:container' //a k8s pod can only consist of containers

Some characteristics of an entity are:

• Measurement types (metrics / events) to capture various measurements observed on entities of a given type
• Relationship types to capture how one type is related to another
• Interaction types to capture how one type may interact with another

Entity Relationship

Entities typically do not exist in isolation, but co-exist with other entities of similar or other types. These entities are often related, and the relationships (for example, parent/child) are useful to understand and configure a model framework. The Cisco Observability Platform domain model entity object has an attribute named parentType that contains a reference to the entity type that the entity inherits characteristics from.

Associations

An association represents a connection between entities. Associations connect entities with a directed edge forming a connected graph, a topology. Topology defines how entities interrelate with each other. All entities, events, metrics and topologies have types. The Cisco Observability Platform organises the types in type namespaces or domains. For example Kubernetes® is a domain type. You can traverse this topology by following any of the associations. Associations are referenced by their type name.

An association can represent one of the following:

• a static relationship between entities, for example:
  • consists_of (one to many): a k8s pod consists of multiple containers
  • relates_to (many to many): an EBS volume can be mounted to multiple EC2 instances. An EC2 instance can have multiple EBS volumes.
• a dynamic relationship, for example:
  • a service instance updates a record in a database

Following are the properties of an association:

An association is derived from MELT data based on a convention, a configuration, or an extension. It remains valid until the association either from or to entities expire.

An association is always associated with a single association type. The association type comprises of following properties:

Example

Relationship Example

{
  "kind": "relationship",
  "name": "consists_of",
  "displayName": "Consists of",
  "cardinality": "ONE_TO_MANY",
  "isHierarchical": true,
  "isContainment": true
}

Derived Entities

Some entities represent a group (aggregation) of a particular type or different type of entities. You can derive an entity from another entity; this implies a hierarchical relationship between the derived entity and the base entity. For example, a service is an entity representing a group of service instances. Such entities are derived from other observed entities based on a configured entity derivation. The derived entity configuration specifies the rules to derive a new entity.

The configuration rules help derive the following properties of the child (derived) entity:

• the name
• other identifying properties
• attributes
• relationship type between the two entities

For example, a mobile platform is a group of applications and hence platform entity can be derived from application entity. The mobile application entity contains all the properties required to define a platform entity. For example, an application entity with the following properties

1. appKey: 'EUM-AAB-AUA',
2. appName: 'Everyfeature-Android'
3. platform: 'Android'

You can write and store the dynamic entity configurations for the application entity in the config-store. This means if the above application entity is ingested into the platform, a new platform entity is created and ingested into the platform using the properties (appKey and platform) from the application entity.

Below is the sample configuration to derive platform entity from the application entity:

Derived Entity Configurations

{
    "accountId": <account-id>,
    "uniqueConfigName": "derivePlatFromApp",
    "typeId": "_dEntityC",
    "configClassName": "com.appdynamics.platform.entity.config.model.grouping.DerivedEntityConfiguration",
    "entityTypeId": "e_MAPP",
    "scopeFilter": "true",
    "targetEntityTypeId": "e_MPLT",
    "relationshipTypeId": "r_Plat-App",
    "mappings": {
        "name": [
            "this.properties.platform.value"
        ],
        "identifyingProperties": {
            "appKey": [
                "this.properties.appKey.value"
            ],
            "platform": [
                "this.properties.platform.value"
            ]
        },
        "attributes": {
            "*": [
                "this.attributes[#key]"
            ]
        },
        "labels": {
            "*": [
                "this.labels[#key]"
            ]
        }
    }
}

List of Derived Entities

When two entities are created by different sources or when both entities are derived, you need to derive the relationship configuration between the two entities.

Info: Before you start configuring a model schema for an application, ensure that you understand the metrics and entities that are supported with the current application architecture.

Entity Tags

In addition to entity properties, an entity can also have tags, such as, attributes associated with it. Each tag is a key-value pair that is associated with an entity for a time range. A tag does not uniquely identify an entity. You define a tag only when you need to group entities or define a relationship between them.

Tags change over period of time; you can add new tags, update existing tags or delete a tag. Every change in the tag affects the group the entities belong to or the relationships they have. Each change in the tag creates a new version of the same entity, creating a timeline for the entity and the tag.

For example, a mobile application, where the application can be uniquely identified by the properties AppKey, Platform and AppName. But along with the properties the application entity may contain attribute - appVersion.

These tags can be used to

• Group the entities together
• Relate entities to each other
• Query/lookup the entities

When you create a solution, you can add entities to your solution domain model in the entity definition file in a folder under your solution package (link to solution package description) folder. See the Student Lab Guide.