detailedResponse Field

• If an error occurs in parsing a metric or model, such as a required field is missing, an error is returned in the JSON response body.
• If there are only a few metrics or models, these may be easy to identify, but can prove difficult if there are many at one time.
• Specific feedback is provided when parsing fails if the detailedResponse field is set to true.
• detailedResponse must be set at the same level as the metrics or models field.

Without setting "detailedResponse": true

With setting "detailedResponse": true

Relationships between Entities

• Used with Smartview
• A model’s dimension fields identify the entity it defines.
• You can create one or more relationships between the entity represented by the model and another entity
• Entity relationships are directional
  • The arrows shown in the image represent who is dependent on what.
  • API Gateway is dependent on Products service and Orders service
  • Products service is dependent on the Redis Products DB
  • Orders service is dependent on the PostgreSQL Orders DB
• Most common way to create a relationship between two or more entities is by using the impactToDimensions (Most commonly used) or impactFromDimensions (less common) metadataField in one of the entities models
  • Products DB impacts to the Products service
  • Orders DB impacts to the Orders service
• Zenoss Cloud Smart View displays information about the selected entity (the “anchor entity”) on the left and related entities on the right.
• Smartview allows users to ispect metric data for related entities on one screen
• Synced time-sliders between related graphs make it easier to for users to understand what caused a problem.

Example:

If there is an issue with the API gateway (Web UI), we can drill down into the microservices to see what might be the cause of the issue.

How do these work

• impactToDimensions
  • Creates a relations from the current entity to another entity
  • current-entity -> other-entity
    • If I go down, I affect this…
• impactFromDimensions
  • Creates a relationship to the current entity from another entity
  • current-entity <- other-entity
    • If that goes down, it affects me.
• These fields are always list datatypes.
• This creates a directed acyclic graph between the two entities.
• If Entity-A is related to Entity-B (A -> B): (think fo the arrow as “impacts”)
  • Smart View display for Entity-B will show Entity-A as a related entity
  • Smart View display for Entity-A will not show Entity-B as a related entity
  • Per the example, neither the Products DB nor the PostgreSQL DBs will have related entities.

impactToDimensions Relationships with JSON

Single entity relationship example

...
  "metadataFields": {
    "impactsToDimensions": [
      "shop.gateway=austin-gateway"
    ],
...

Multiple entity relationship example

• Note: The only reason this example would be necessary is because there is no directly relationship between the API Gateway and Orders Service here.
• This would not be necessary to relate the Products DB to the Gateway because it is inherited from the Products Service.

...
  "metadataFields": {
    "impactsToDimensions": [
      "shop.gateway=austin-gateway,shop.service=products-service"
    ],
...

• Note, above example image shows all one string. This defines that entity.
  • All dimensions listed must EXACTLY match the entity
• Additional entities are entered as additional strings in the list.

    "impactsToDimensions": [
      "shop.gateway=austin-gateway,shop.service=products-service",
      "order.service=orders-service"
    ],

impactFromDimensions Examples

Best Practices – Which one should you use

• The agent creating the model for one entity must know the precise dimensions of any related entity/entities in order to use these fields.
• Because of this, impactToDimensions is often the more natural choice.
• impactToDimensions works best for entities that have the shortest lifespan
  • For example: services and containers are normally created and destroyed more frequently than higher-level entities, so it’s easier to define the relationship in the model of the more short-lived entity.
  • Imagine a service that needs to spin up/spin down multiple worker processes.  It would be better for these worker processes to define whom they affect vs. trying to keep track of all of these in the parent service and constantly update its model.
• impactFromDimensions are useful when the agent that creates the impacted entity’s model knows the dimensions of the impacting entity but not the other way around.
  • For example: EntityA is impacted by EntityB (B -> A)
  • EntityB (more correctly, the agent publishing the model for EntityB) does not have access to EntityA’s dimensions
  • EntityA can create the relationship

Bottom Line: Use impactToDimensions unless you cannot.

Named Relationships

• if you need to define a relationship between two or more entities where none of the entities are aware of the other’s dimensions, you can create a unidirectional  named relationship using one of the these metadata fields in each of the related entity’s models:
  • simpleCustomRelationshipSourceTag declares that this entity impacts any entities with a corresponding Sink tag.
  • simpleCustomRelationshipSinkTag declares that this entity is impacted by any entities with a corresponding Source tag.
  • Tags in both the source and sink models must exist for the relationship to exist.  This is different from the impactTo and impactFrom tags where only 1 is required.
  • Names can be anything you want, as long as they match, but they should be descriptive.

Source tag example (I impact you)

Sink tag example (I’m impacted by)

Deleting Entites

• To delete an entity, publish its model with the _zen_deleted_entity metadata field set to true:
• This will not affect the time slider.  If the entity existed in the past, it will still be available in the graphs any time the entity existed.

{
  "models": [
    {
...
      "metadataFields": {
        "_zen_deleted_entity": true
      }
...