Cisco Observability Platform

This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.

Create an Entity Centric Page

You can create an Entity Centric Page that displays a list of starships as a table. The building block for rendering a table is grid. The configuration of a grid largely consists of the specification of its columns. Each column is specified by an object in this array, which consists of:

  • a label text to display at the top of the column.
  • a cell that specifies the template elements that render cell content. The grid can render multiple sets of entities (this can be specified in an optional property rowSets). Therefore, the cell property contains a map specifying one element per row set name. If no explicit row sets are specified, the key for the element rendering the cell is default:
json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "grid",
    "columns": [
      {
        "label": "Name",
        "cell": {
          "default": {
            "instanceOf": "string",
            "path": "attributes(spacefleet.starship.name)"
          }
        }
      }
    ]
  }
}

In this case, the building block rendering the cell content is a simple string, binding to the field id of the starship entity. For example, you can change the instanceOf property to cartesian to render a line chart in the cell.

Add two more columns to see the registry attribute and the current value of the metric speed:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "grid",
    "columns": [
      {
        "label": "Name",
        "cell": {
          "default": {
            "instanceOf": "string",
            "path": "attributes(spacefleet.starship.name)"
          }
        }
      },
      {
        "label": "Registry",
        "cell": {
          "default": {
            "instanceOf": "string",
            "path": "attributes(spacefleet.starship.registry)"
          }
        }
      },
      {
        "label": "Speed",
        "cell": {
          "default": {
            "path": "metrics(\"spacefleet:speed\", \"RS-datagen\").value",
            "instanceOf": "number"
          }
        }
      }
    ]
  }
}

For the speed, the building block number is used, which formats the number properly. You can also use the string building block. However, it will not do any formatting. Click Run to see the preview.

The elements in the cell property can be configurations of arbitrary building blocks. If you exchange the cell element for Speed by a sparkGraph configuration, the resulting table displays the speed graph.

json
Copy{
  "label": "Speed",
  "cell": {
    "default": {
      "path": "spacefleet:speed",
      "source": "RS-datagen",
      "instanceOf": "sparkGraph"
    }
  }
}

The sparkGraph building block automatically requests the metric time series from the parent element's topology context so that it can render the line chart. Building blocks that render content include:

  • cartesian (chart)
  • count
  • dateTime
  • duration
  • entityType
  • icon
  • number
  • propertyList
  • sparkGraph
  • string
  • text

Wrapper Elements

In the configuration of the grid, you can see that template elements (such as configurations of string or number) can be nested into other template elements. Several types of building blocks are used as wrappers to arrange or add functionality to embedded elements visually.

For example, you can wrap the grid element using the card building block to embed the table in a background panel with rounded corners:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "card",
    "props": {
      "style": {
        "width": "100%",
        "height": "230px"
      },
      "title": "Endpoints"
    },
    "elements": [
      {
        "instanceOf": "grid",
        "columns": [
          {
            "label": "Name",
            "cell": {
              "default": {
                "instanceOf": "string",
                "path": "attributes(spacefleet.starship.name)"
              }
            }
          },
          {
            "label": "Registry",
            "cell": {
              "default": {
                "instanceOf": "string",
                "path": "attributes(spacefleet.starship.registry)"
              }
            }
          },
          {
            "label": "Speed",
            "cell": {
              "default": {
                "path": "spacefleet:speed",
                "source": "RS-datagen",
                "instanceOf": "sparkGraph"
              }
            }
          }
        ]
      }
    ]
  }
}

You can also get a similar result using the html element, which corresponds to a div in the browser's DOM:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "html",
    "style": {
      "width": "100%",
      "height": "230px",
      "backgroundColor": "#202030",
      "borderRadius": "12px"
    },
    "elements": [
      {
        "instanceOf": "grid",
        "...": "..."
      }
    ]
  }
}

The use of html building blocks to add css style attributes to elements is a powerful way to control layout and appearance of your UI components.

Layout-related wrapper building blocks include:

  • card
  • collapsible
  • elements
  • empty
  • headline
  • html
  • tab

Other wrapper building blocks, such as toolTip and clickable add interaction functionality to UI elements. There are also wrapper elements that change the topology context (data) that its children use.

So far, you have embedded the table in a card element. However, you do not have a full Entity Centric Page (ECP) yet. To create an ECP template, you need to wrap the card into an ocpList element:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipECP",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "ocpList",
    "elements": [
      {
        "instanceOf": "card",
        "props": {
          "style": {
            "width": "100%",
            "height": "230px"
          },
          "title": "Endpoints"
        },
        "elements": [
          {
            "instanceOf": "grid",
            "columns": [
              {
                "label": "Name",
                "cell": {
                  "default": {
                    "instanceOf": "string",
                    "path": "attributes(spacefleet.starship.name)"
                  }
                }
              },
              {
                "label": "Registry",
                "cell": {
                  "default": {
                    "instanceOf": "string",
                    "path": "attributes(spacefleet.starship.registry)"
                  }
                }
              },
              {
                "label": "Speed",
                "cell": {
                  "default": {
                    "path": "spacefleet:speed",
                    "source": "RS-datagen",
                    "instanceOf": "sparkGraph"
                  }
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Click Run to see the preview.

References to Templates

By wrapping the table in a card and embedding the card in an ECP template, the nesting levels are deep. Also, we have used a different name for the ECP template, mysolution.starshipECP.

Instead of inlining the element of the template mysolution.starshipList and to reduce the complexity, you can refer to it as following:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "ocpList",
    "elements": [
      {
        "instanceOf": "mysolution:starshipList"
      }
    ]
  }
}

The configuration-driven framework infers that instanceOf points to a template instead of an atomic building block from the presence of a namespace prefix.

The authoring tool can render this preview when the template mysolution:starshipList is already deployed (as part of your solution). However, it will not work if it only exists as a local template in the authoring tool. Therefore, test this with an already deployed similar template:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "ocpList",
    "elements": [
      {
        "instanceOf": "spacefleet:starshipGridTable"
      }
    ]
  }
}

Click Run to see the preview.

There are other references to templates here, although they are not explicit. If you do not specify theleft and right properties, the left side panel is populated by the dashui:ecpRelationshipMap template, and the right side panel with the dashui:ecpListInspector template. The default configuration of the ecpList building blocks is similar to the following example:

json
Copy{
  "kind": "template",
  "name": "mysolution:starshipList",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "ocpList",
    "left": {
      "instanceOf": "template",
      "templateName": "dashui:ecpListRelationshipMap"
    },
    "right": {
      "instanceOf": "template",
      "templateName": "dashui:ecpListInspector"
    },
    "elements": [
      {
        "instanceOf": "spacefleet:starshipGridTable"
      }
    ]
  }
}

The dashui:ecpRelationshipMap template for the starship entity is defined as:

json
Copy{
  "kind": "template",
  "name": "dashui:ecpRelationshipMap",
  "view": "default",
  "target": "spacefleet:starship",
  "element": {
    "instanceOf": "leftbar",
    "label": "Relationships",
    "elements": [
      {
        "key": "starship",
        "path": ".",
        "iconName": "AgentType.Appd",
        "entityAttribute": "spacefleet.starship.name"
      },
      {
        "key": "room",
        "path": "out(common:consists_of).to(spacefleet:room)",
        "iconName": "AgentType.Appd",
        "entityAttribute": "spacefleet.room.name"
      }
    ]
  }
}

The leftbar building block always renders a relationship map and is not a wrapper. This means that the elements in its configuration are not template elements (as can be seen by the absence of the instanceOf keyword). These elements always contain the key, path, iconName, and entityAttribute properties.

path specifies the traversal path from the entities in the scope (here: starship) to the related entities.

iconName is the name of an icon that gets rendered on the left of the name of the related entity type.

entityAttribute only has an effect if the number of related entities is exactly one. In this case, the value of the specified attribute (usually the name) will be rendered below the circle.

When the ECP is created, you need to enable the user to navigate to it from other pages. Hence, you must add elements to the leftbar configuration of ECPs belonging to other solutions.

Conditional Rendering

Sometimes there are situations in which components should only be rendered when certain conditions are met. For such situations, you can specify these special wrapper elements:

  • cardinality
  • select
  • coalesce
  • inputSelect
  • selectionFilter

cardinality

The cardinality building block is used to render a subtemplate (or, strictly speaking, a template element) based on cardinality of rows in response from UQE (in other words, the number of records that the topology context represents). This building block has a list of alternative elements, out of which the one with the matching count (count of records) is selected. If the actual number of records doesn't match any of the elements in the list, the defaultTemplate is rendered. For example:

json
Copy{
  "instanceOf": "cardinality",
  "elements": [
    {
      "count": 0,
      "template": {
        "instanceOf": "text",
        "content": "0"
      }
    },
    {
      "count": 1,
      "template": {
        "instanceOf": "string",
        "path": "attributes(name)"
      }
    }
  ],
  "defaultTemplate": {
    "instanceOf": "count",
    "type": "dataMode"
  }
}

select

A very similar building block is select, which uses the value of a field or attribute to decide which element to render out of a list of attributes. The field or attribute to evaluate is specified by path. Alternative elements are specified in branches and defaultElements. In contrast to the cardinality building block, either single template elements or arrays can be used in elements and defaultElements. For example:

json
Copy{
  "instanceOf": "select",
  "path": "attributes(health)",
  "branches": [
    { "value": 1, "elements": { "instanceOf": "text", "content": "Ok" } },
    { "value": 2, "elements": { "instanceOf": "text", "content": "Not Ok" } }
  ],
  "defaultElements": { "instanceOf": "text", "content": "–" }
}

coalesce

The coalesce block is designed to provide fallback content in cases where the existence of certain attributes (or related entities) cannot be guaranteed. It also has a list of elements, but here each element has its own path. This path is only used to evaluate whether or not the template is rendered: The first element for which the evaluation of path yields data is rendered, using the topology context of the parent element. If none of the paths specified by the individual elements results in data, the defaultTemplate is rendered. For example:

json
Copy{
    "instanceOf": "coalesce",
    "elements": [
        {
            "path": "attributes(service.name)",
            "template": {
                ...
            }
        },
        {
            "template": {
                "instanceOf": "string",
                "path": "in..."
            }
        }
    ],
    "defaultTemplate": {
        "instanceOf": "text",
        "content": "-"
    }
}

inputSelect

In some cases, the user should be able to select which content to render. For these cases, the inputSelect building block creates a dropdown to select a value from multiple alternatives and store it under a specified selectionKey. For example:

json
Copy{
    "instanceOf": "inputSelect",
    "options": [
        {
            "label": "All Sources",
            "value": null
        },
        {
            "label": "AppDynamics",
            "value": "infra-agent"
        },
        {
            "label": "Aws",
            "value": "aws-cloudwatch"
        }
    ],
    "selectionKey": "dataSources",
    "label": "Data Sources"
}

selectionFilter

The selectionFilter wrapper can then be used to only render a child element when a specific value has been selected for that particular selectionKey:

json
Copy{
  "instanceOf": "selectionFilter",
  "selectionKey": "dataSources",
  "values": [null, "infra-agent"],
  "elements": [
    {
      "instanceOf": {
        "name": "hostCpuUtilizationChart"
      },
      "source": "infra-agent"
    }
  ]
}

Extend Relationship Maps

You can enable navigation between entities of your solution and towards entities of other solutions by configuring the relationship maps of your own solution. However, you would require to enable users to navigate back from related entities in other solutions to your entities.

Let us take an example relationship map of spacefleet:room:

json
Copy{
  "kind": "template",
  "name": "dashui:ecpRelationshipMap",
  "view": "default",
  "target": "spacefleet:room",
  "element": {
    "label": "Relationships",
    "elements": [
 ...
      {
        "key": "k8s:cluster",
        "path": "out(common:has).to(k8s:cluster)",
        "iconName": "AgentType.Appd",
        "entityAttribute": "k8s.cluster.name"
      }
    ],
    "instanceOf": "leftbar"
  }
}

It points to the ECP of the associated k8s:cluster entities. To have a corresponding link back from the kubernetes cluster to the related rooms, you must add a template extension for the cluster's relationship map:

json
Copy[
  {
    "kind": "templateExtension",
    "name": "spacefleet:k8sClusterRelationshipMapExtension",
    "extends": {
      "name": "dashui:ecpRelationshipMap",
      "target": "k8s:cluster"
    },
    "path": "elements.elements",
    "add": [
      {
        "index": 0,
        "value": {
          "key": "spacefleetRoom",
          "path": "in(common:has).from(spacefleet:room)",
          "entityAttribute": "spacefleet.room.name",
          "iconName": "Location.Home"
        }
      }
    ]
  }
]

The extends property of the extension specifes the template to be extended. The path points to an array inside this template (relative to the "element" of the template). The extended template has this structure:

json
Copy{
  "kind": "template",
  "name": "dashui:ecpRelationshipMap",
  "view": "default",
  "target": "k8s:cluster",
  "element": {
    "instanceOf": "featureFlag",
    "flag": [
      "APM_BT_GA",
      "APM_BT_SHORTENING"
    ],
    "elementsExpression": "/* omitted for shortness */",
    "elements": {
      "instanceOf": "leftbar",
      "label": "Relationships",
      "elements": [
        {
          "key": "service",
          "path": "/* omitted for shortness */",
          "entityAttribute": "service.name",
          "iconName": "Location.ApplicationServers"
        }
      ]
    }
  }
}

It does not expose props, hence the more robust templatePropsExtension cannot be used.

Extend the Home Screen

To display the starship and room entities in the home screen, you must extend the dashui:ecpHome template:

json
Copy[
  {
    "kind": "templateExtension",
    "name": "spacefleet:homeTemplateExtension",
    "extends": {
      "name": "dashui:ecpHome",
      "view": "default",
      "target": "*"
    },
    "path": "sections",
    "add": [
      {
        "index": 4,
        "value": {
          "sectionTitle": "Space Fleet",
          "props": [
            {
              "entityAttribute": "spacefleet.starship.name",
              "targetType": "spacefleet:starship"
            },
            {
              "entityAttribute": "spacefleet:room.name",
              "targetType": "spacefleet:room"
            }
          ]
        }
      }
    ]
  }
]
Next