Skip to content

Using entities

An entity represents any discrete system, process or feature for which Zenoss Cloud gathers or is sent time series data. For more information about entities, see Entities and devices.

Creating an entity

To create an entity, you send a model of it to Zenoss Cloud, which stores the model as the first data point in the entity's time series. An entity model must include metadata that make it unique in Zenoss Cloud (dimension attributes) and may include additional metadata (metadata attributes). Both attribute types are specified as key-value pairs. Some key names are reserved.

Dimension attributes

The metadata that make an entity unique in Zenoss Cloud are dimension attributes, or simply, dimensions. When you create an entity with the Zenoss API, you must specify at least one dimension (key-value pair) and you may specify as many as you wish. However, dimensions cannot vary. Each time you send Zenoss Cloud an entity model that contains a combination of dimensions that have not been sent before, you create a new entity.

For example, consider the following information about a daily special:

  • The name of the special (tuna casserole, chicken pot pie, and so on).
  • The day of the week the special is offered.
  • The name and location of the cafeteria that is offering the special.

The name of the special and the day of the week are variable, so they can't be used as dimension attributes. However, you can use an abstraction of the special and the cafeteria name and location. The following table shows an example set of key-value pairs that could be used as dimensions in an entity model of the special.

Key Value
meal Special
cafe-name Hey Zenny Cafe
cafe-city Austin

The key-value pairs in the preceding table are valid and likely unique, but probably not what you would use, because of processing requirements. For example, a reserved key (source) is commonly used as a dimension; reserved keys are described in a following section.

Tip

Why bother with multiple dimension attributes, anyway? A globally-unique identifier would work and could be easier to implement. The answer is search—each dimension attribute becomes another name and value that can be used separately or in combination to find an entity. In fact, all entity and metric metadata can be used in queries.

Metadata attributes

The metadata that are not used as dimension attributes are included in a model as metadata attributes. Unlike dimension attributes, metadata attributes can include variable content. For example, for a daily special, metadata attributes would be used to record the name of the special and the day of the week on which the special is offered. Also, metadata attributes are used to define dependency relationships with other entities.

Note

The name key (a common key) may be used as a metadata attribute in entities, but not in metrics.

Reserved keys

A key can be any contiguous string of uppercase or lowercase letters, numerals, hyphens, full stops, or underscores. However, some keys are reserved for use by Zenoss Cloud:

  • Common keys, which are used in most entity models.
  • Relationship keys, which are used only to define dependency relationships between entities.

Common keys

The reserved keys in the following table are used in most entity models.

Key Description
source-type

The class name of the application sending data.

This key is required.

  • For custom applications, Zenoss recommends using the reverse-DNS naming convention.
  • For Zenoss agents, the class names are fixed. For the Kubernetes agent, it's specified for you.

The policy service uses this value to select a policy.
source

An instance identifier for source-type.

Currently, this key is required to create a dashboard scope. Commonly used as a dimension.
name

The display name of an entity.

This key is not required, but without it entities are labeled [ UNNAMED ] in displays such as Smart View. The value does not have to be unique.

The name key may be used as a metadata attribute in entities, but may not be used as either a dimension or metadata attribute in metrics.

A required key may be used either as a dimension attribute or as a metadata attribute.

Note

There is one additional reserved key, which is only used to delete entities. For more information, see Deleting an entity.

Relationship keys

Zenoss Cloud provides two pairs of reserved keys for defining dependency relationships between entities:

  • Use the impactFromDimensions key or the impactToDimensions key when you know the dimension attributes of the other entity or entities in a dependency relationship.
  • Use the simpleCustomRelationshipSourceTag and simpleCustomRelationshipSinkTag keys when you do not know the dimension attributes of the other entity or entities in a dependency relationship.

In graph theory terms, the preceding keys establish an edge between two nodes in a directed acyclic graph of dependency relationships.

The impactFromDimensions and impactToDimensions keys

You may add the impactFromDimensions key or the impactToDimensions key to the metadata attributes of an entity to define a dependency relationship with one or more other entities. Only one key in one entity model is required to establish the relationship. However, you must know the dimension attributes of the other entities in the relationship, so these keys are only appropriate for applications in which the dimensions are readily available.

For example, the following diagram highlights the equivalent options for defining entity A's dependence on entity B:

  • Add the impactFromDimensions key to the model of entity A.

  • Add the impactToDimensions key to the model of entity B.

Since you can establish the relationship from either side of the dependency, just choose the side that is most convenient for you. For example, it's easier to identify the pod or virtual machine on which a container depends than it is to update the model of a pod or virtual machine every time a container is created.

The simpleCustomRelationshipSourceTag and simpleCustomRelationshipSinkTag keys

The simpleCustomRelationshipSourceTag and simpleCustomRelationshipSinkTag keys use an identical value to define a dependency relationship with one or more other entities. The keys are appropriate when you do not know the dimension attributes of the other entities in the relationship, such as when the entities are gathered or sent by different source applications. The identical value specified on each entity establishes the edge between them.

For example, the following diagram shows myString as the value for simpleCustomRelationshipSourceTag in the model of entity A, and as the value for simpleCustomRelationshipSinkTag in the model of entity Ω (omega). Together, these two key-value pairs establish that entity A is dependent on entity Ω (omega).

The time of the last model update determines the beginning of a relationship. For example, if entity A is updated at 9:30 and entity Ω (omega) is updated at 10:30, then the start of their relationship is 10:30.

Updating an entity

To update an entity, you send its model to Zenoss Cloud with either or both of the following:

  • One or more new metadata attributes.
  • New content for one or more existing metadata attributes.

The model need only contain the entity's dimension attributes plus the metadata attributes that you want to add or update. Each model update becomes another data point in the entity's time series.