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.
The policy service uses this value to select a policy. |
source |
An instance identifier for 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 The |
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 theimpactToDimensions
key when you know the dimension attributes of the other entity or entities in a dependency relationship. - Use the
simpleCustomRelationshipSourceTag
andsimpleCustomRelationshipSinkTag
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.