Unified analysis reference
This is a general description of the unified analysis extension YAML file and ways to create custom visualizations and configure cards, dashboards, and injections.
Details settings
To customize the details screen, start with the detailsSettings
and specify the types of information to be included on a unified analysis page. This enables you to customize the page to show all of the data points, charts, and visuals that are most relevant and beneficial to you.
detailsSettings:
staticContent:
showProblems: true
showProperties: true
showTags: true
showGlobalFilter: true
showAddTag: true
layout:
autoGenerate: false
cards:
- key: cpu_mem
type: CHART_GROUP
- key: disks
type: ENTITIES_LIST
staticContent
Enable or disable static elements like problems, properties, tags, global filter and Add tag option.
Field | Description | Required |
---|---|---|
showProblems | If true , the details screen shows the problem card. | required |
showProperties | If true , the details screem shows the properties card. | required |
showTags | If true , the details screem shows the entity tags. | required |
showGlobalFilter | If true , the details screen shows the filter bar. | required |
showAddTag | If true , the details screen shows the Add tag option. | required |
header | The definition of the page header. | optional |
breadcrumbs | A list of breadcrumbs leading to the page. | optional |
layout
Reference cards that should be shown on the screen (like chart groups or entity lists) or use the automatically generated screen layout.
Field | Description | Required |
---|---|---|
autoGenerate | If true , the screen content is automatically generated. . | required |
cards | Possible values for type field: CHART_GROUP , ENTITIES_LIST , EVENTS , LOGS , MESSAGE , METRIC_TABLE , INJECTIONS , BREAK_LINE . | optional |
Details injections
The detailsInjections
field defines injections for the entity details page. This information can be used to better evaluate user experience and also help with root-cause analysis. Note: Injections must be supported by the screen—the layout needs to include an injected cards placeholder.
detailsInjections:
- type: CHART_GROUP
entitySelectorTemplate: type(custom:host), toRelationship.sameAs($(entityConditions))
key: injectedChartGroups
- type: ENTITIES_LIST
key: injectedList
width: HALF_SIZE
- type: EVENTS
key: injectedEvents
width: FULL_SIZE
Field | Type | Description | Required |
---|---|---|---|
type | enum | Defines the type of card available to inject. Possible values: CHART_GROUP , ENTITIES_LIST , EVENTS , LOGS , MESSAGE . | required |
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
entitySelectorTemplate | String | Entity selector pointing to related entities. | optional |
width | enum | A value that determines how much vertical space the card is taking. Possible values: HALF_SIZE , FULL_SIZE . | optional |
Details filters
The detailsFilter
field defines filters for the entity details screen. It enables you to customize the page to show only the data you want to see.
detailsFilters:
relationships:
- type(HOST_GROUP), toRelationship.isInstanceOf($(entityConditions))
- type(AZURE_REGION), fromRelationship.isSiteOf($(entityConditions))
entityFilters:
- displayName: filters
filters:
- type: entityName
displayName: name
freeText: false
modifier: contains
defaultSearch: true
distinct: false
entityTypes:
- my:interface
relationships
You can enable filtering by configuring the relationship between screen entity type and related entity type. For example, filter process list by host name:
relationships:
- type(HOST) AND toRelationship.isProcessOf($(entityConditions))
You can also configure the filtering on multiple levels. For example, filter the processes by host group name:
relationships:
- type(HOST) AND toRelationship.isProcessOf($(entityConditions))
- type(HOST) AND fromRelationship.isInstanceOf(type(HOST_GROUP))
entityFilters
The block that defines the groups of filters (these are displayed slightly grayed out in the filtering list).
Field | Type | Description | Required |
---|---|---|---|
filters | String | The actual filters that are part of this group. | required |
type | String | Must reference an attribute of the entity you are filtering. Note: every entity has entityName as a default attribute. | required |
displayName | String | How this filter is labelled within the web UI. | required |
freeText | boolean | If true , the user can freely type text; otherwise, they must select from a list of suggestions. Note: only default attributes such as entityName are capable of offering list of suggestions. | required |
modifier | boolean | When freeText is true, this defines how the text should be matched against the attribute. When freeText is false, this must be omitted. Note: All non-default attributes must match as equals regardless of this option. | optional |
defaultSearch | boolean | If true , if the user starts typing without selecting a filter first, this filter is selected by default. Only one filter within the filtering block may have this enabled. | optional |
distinct | boolean | If true , only one instance of this filter can be applied. | required |
entityTypes | Array | A mandatory list of entity types that this filter applies to. If you omit this, your filtering bar just shows a spinning wheel because of the incomplete definition. | optional |
List settings
The listSettings
section enables you to customize the list view of the unified analysis page. You can change the selection and order of columns, how the list is sorted, and the number of rows to display.
listSettings:
staticContent:
showGlobalFilter: true
header:
title: My hosts
description: My hosts list
icon: host
layout:
autoGenerate: false
cards:
- type: CHART_GROUP
key: chart
- type: ENTITIES_LIST
key: entitiesList
- type: INJECTIONS
staticContent
required
Enable or disable static elements like problems, properties, tags, global filter, and the Add tag option.
Field | Description | Required |
---|---|---|
showProblems | If true , the details screen shows the problem card. | optional |
showProperties | If true , the details screem shows the properties card. | optional |
showTags | If true , the details screem shows the entity tags. | optional |
showGlobalFilter | If true , the details screen shows the filter bar. | required |
showAddTag | If true , the details screen shows the Add tag option. | optional |
header | The definition of the page header. | optional |
breadcrumbs | A list of breadcrumbs leading to the page. | optional |
layout
required
Reference cards that should be shown on the screen (like chart groups or entity lists) or use the automatically generated screen layout.
Field | Description | Required |
---|---|---|
autoGenerate | If true , the screen content is automatically generated. . | required |
cards | Possible values for type field: CHART_GROUP , ENTITIES_LIST , EVENTS , LOGS , MESSAGE , METRIC_TABLE , INJECTIONS , BREAK_LINE . | optional |
List injections
The listInjections
field defines injections for entity details screen. Injections must be supported by the screen—the layout needs to include an injected cards placeholder.
listInjections:
- type: CHART_GROUP
key: injectedChartGroups
- type: ENTITIES_LIST
key: injectedList
width: HALF_SIZE
Field | Type | Description | Required |
---|---|---|---|
type | enum | Defines the type of card available to inject. Possible values: CHART_GROUP , ENTITIES_LIST , MESSAGE . | required |
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
List filters
The listFilters
field defines filters on the list page.
listFilters:
relationships:
- type(HOST_GROUP), toRelationship.isInstanceOf($(entityConditions))
- type(AZURE_REGION), fromRelationship.isSiteOf($(entityConditions))
entityFilters:
- displayName: filters
filters:
- type: entityName
entityTypes:
- HOST_GROUP
- AZURE_REGION
freeText: false
displayName: name
distinct: true
relationships
You can enable filtering by configuring the relationship between screen entity type and related entity type. For example, filter process list by host name:
relationships:
- type(HOST) AND toRelationship.isProcessOf($(entityConditions))
You can also configure the filtering on multiple levels. For example, filter the processes by host group name:
relationships:
- type(HOST) AND toRelationship.isProcessOf($(entityConditions))
- type(HOST) AND fromRelationship.isInstanceOf(type(HOST_GROUP))
entityFilters
The list of entity filters.
Field | Type | Description | Required |
---|---|---|---|
filters | String | The actual filters that are part of this group. | required |
type | String | Must reference an attribute of the entity you are filtering. Note: every entity has entityName as a default attribute. | required |
displayName | String | How this filter is labelled within the web UI. | required |
freeText | boolean | If true , the user can freely type text; otherwise, they must select from a list of suggestions. Note: only default attributes such as entityName are capable of offering list of suggestions. | required |
modifier | boolean | When freeText is true, this defines how the text should be matched against the attribute. When freeText is false, this must be omitted. Note: All non-default attributes must match as equals regardless of this option. | optional |
defaultSearch | boolean | If true , if the user starts typing without selecting a filter first, this filter is selected by default. Only one filter within the filtering block may have this enabled. | optional |
distinct | boolean | If true , only one instance of this filter can be applied. | required |
entityTypes | Array | A mandatory list of entity types that this filter applies to. If you omit this, your filtering bar just shows a spinning wheel because of the incomplete definition. | optional |
Properties card
The propertiesCard
field displays the entity properties that are shown on the card as key-value pairs. By default, all available attribute properties are displayed.
propertiesCard:
properties:
- type: RELATION
relation:
entitySelectorTemplate: NOT VALIDATED IN SCHEMA
displayName: default
- type: ATTRIBUTE
attribute:
key: attribute
displayName: Attribute
properties
required
Use this configuration to specify the properties card.
Field | Type | Description | Required |
---|---|---|---|
type | enum | Defines the type of property. Possible values: RELATION , ATTRIBUTE . | optional |
RELATION
Enables you to specify the relation to the specific entity.
Field | Type | Description | Required |
---|---|---|---|
entitySelectorTemplate | String | An entity selector that is used to retrieve the selected entities. | required |
displayName | String | The name of the relation. | required |
ATTRIBUTE
Enables you to overwrite attribute display options.
Field | Type | Description | Required |
---|---|---|---|
key | String | Used to reference the desired attribute. | required |
displayName | String | The name of the attribute. | optional |
Chart group cards
The chart group cards enable you to visualize the specified metrics in dedicated charts.
- The
metricSelector
expression specifies the metrics your chart is based on. For more information, see Metrics API - Metric selector. The examples below use simple metric selector expressions referring directly to the metric keys.
chartsCards:
- key: chartGroup
conditions:
- NOT VALIDATED IN SCHEMA
numberOfVisibleCharts: 2
charts:
- displayName: Chart
conditions:
- NOT VALIDATED IN SCHEMA
visualizationType: GRAPH_CHART
graphChartConfig:
visualization:
themeColor: DEFAULT
seriesType: LINE
metrics:
- metricSelector: NOT VALIDATED IN SCHEMA
- metricSelector: builtin:host.cpu.usage:avg
visualization:
themeColor: DEFAULT
seriesType: LINE
- displayName: Chart2
visualizationType: PIE_CHART
pieChartConfig:
metric:
metricSelector: NOT VALIDATED IN SCHEMA
defaultAggregation: AVG
showLegend: true
themeColor: ORANGE
- displayName: Chart3
visualizationType: SINGLE_VALUE
singleValueConfig:
metric:
metricSelector: NOT VALIDATED IN SCHEMA
displayName: Single value
defaultAggregation: COUNT
showSparkline: true
showTrend: true
Field | Type | Description | Required |
---|---|---|---|
key | enum | The unique key of the card, which is used to reference desired card configuration | required |
conditions | enum | Defines the conditions that need to be fulfilled for the chart group card to be visible. | optional |
numberOfVisibleCharts | enum | The number of charts that are visible on the unified analysis page. | required |
charts
Field | Type | Description | Required |
---|---|---|---|
displayName | enum | The title of the card. | required |
conditions | enum | Defines the conditions that need to be fulfilled for the chart group card to be visible. | optional |
visualizationType
The visualizationType
defines the type for your chart: a graph chart GRAPH_CHART
, a pie chart PIE_CHART
, or a single value SINGLE_VALUE
. If you don't specify the visualization type, the graph chart is rendered by default.
GRAPH_CHART
Field | Type | Description | Required |
---|---|---|---|
visualization | enum | Enables you to define a theme color, and series type (COLUMN , LINE or AREA ). You can also enable showing the axis legend by setting the showLegend flag to true . | required |
metrics | enum | Defines how to retrieve data for a single line in the chart. | required |
metricSelector
A metric selector expression for a dedicated metric line.
Field | Type | Description | Required |
---|---|---|---|
visualization | enum | Enables you to define a theme color, and series type (COLUMN , LINE or AREA ). You can also enable showing the axis legend by setting the showLegend flag to true . | optional |
PIE_CHART
Field | Type | Description | Required |
---|---|---|---|
metric | enum | Defines how to retrieve data for the pie chart. | required |
defaultAggregation | enum | Defines default aggregation of the chart timeseries. If not defined or selected one is not supported, it is deduced from metrics metadata. | optional |
SINGLE_VALUE
Field | Type | Description | Required |
---|---|---|---|
metric | enum | Defines how to retrieve data for the single chart. | required |
displayName | enum | Defines the name of the value. | optional |
defaultAggregation | enum | Defines default aggregation of the chart timeseries. If not defined or selected one is not supported, it is deduced from metrics metadata. | optional |
showSparkline | enum | If true , the sparkline is visible. | optional |
showTrend | enum | If true , the trend is visible. | optional |
Entities list cards
The entities list card displays other entities that are related to the focused entity. The YAML file below lists all Synology disks mapped to an instance of DiskStation Manager on which the details screen focuses.
- The
entitySelectorTemplate
expression specifies the entities to list on the card. For more information, see Environment API v2 - Entity selector. - The expression
type(syn:disk),fromRelationships.runsOn($(entityConditions))
lists the entities of typesyn:disk
that have a relationship offrom
direction andrunsOn
type to thesyn:diskmanager
represented via the$(entityConditions)
placeholder that stands for a focused entity.
entitiesListCards:
- key: disks
displayName: Synology disks
pageSize: 10
displayCharts: false
entitySelectorTemplate: "type(syn:disk),fromRelationships.runsOn($(entityConditions))"
displayIcons: true
enableDetailsExpandability: true
numberOfVisibleCharts: 2
Field | Type | Description | Required |
---|---|---|---|
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
displayName | String | The card title. | optional |
pageSize | Integer | The number of rows visible on a single page. | required |
displayCharts | boolean | If true , charts with aggregated data appears above table. | required |
entitySelectorTemplate | String | The entity selector is used to find entities that are to be displayed on the list. | optional |
displayIcons | boolean | If true , the name column displays the icon of the entity. | required |
enableDetailsExpandability | boolean | If true , rows can be expanded with charts related to that row dimension values. | required |
numberOfVisibleCharts | Integer | The number of charts that are visible on the unified analysis page. | required |
Events cards
The events cards display the events related to specified entities.
eventsCards:
- key: events
displayName: Events
entitySelectorTemplates:
- "$(entityConditions)",
- "type(CONTAINER_GROUP_INSTANCE),fromRelationships.isInstanceOf($(entityConditions))",
- "type(PROCESS_GROUP_INSTANCE),fromRelationships.isPgiOfCgi(type(CONTAINER_GROUP_INSTANCE),fromRelationships.isInstanceOf($(entityConditions)))"
showFiltering: true
showPagination: true
pageSize: 10
Field | Type | Description | Required |
---|---|---|---|
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
displayName | String | The card title. If not set, card are named Events . | optional |
entitySelectorTemplates | Array | The list of entity selector templates. It defines where the events are gathered from. If empty, the events are gathered for current entity. | optional |
showFiltering | boolean | The filtering bar displays above events chart. | required |
showPagination | String | The Show more action is available under events list. | required |
pageSize | Integer | The number of rows visible at card load. | required |
Logs cards
The logsCards
field specifies the behavior of the logs card and has the same functionality as Log viewer. It consists of a bar chart representing different log occurrences during selected timeframe and detailed table where each log is an entry with additional properties like: timestamp, status, content.
logsCards:
- key: logs
displayName: Logs
enablePaging: true
filterQuery: event.type!="k8s" AND ($(logEntityAttributeKey) inEntitySelector "$(entityConditions)" OR dt.entity.container_group_instance inEntitySelector "type(CONTAINER_GROUP_INSTANCE),fromRelationships.isInstanceOf($(entityConditions))" OR dt.entity.process_group_instance inEntitySelector "type(PROCESS_GROUP_INSTANCE),fromRelationships.isPgiOfCgi(type(CONTAINER_GROUP_INSTANCE),fromRelationships.isInstanceOf($(entityConditions)))")
showFiltering: true
pageSize: 10
Field | Type | Description | Required |
---|---|---|---|
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
displayName | String | The card title. | optional |
enablePaging | Array | Enables paging of the log results in the table. | optional |
filterQuery | boolean | The predefined filtering for the log table. It is possible to to use LQL syntax also to more complex cases that include entity selectors with unified analysis placeholders in format: expression {attribute} inEntitySelector "{entitySelector}" to display logs of related entities. For example, dt.entity.host inEntitySelector "type(PROCESS_GROUP_INSTANCE) AND fromRelationship.isProcessOf($(entityConditions))" . | optional |
showFiltering | String | Controls the visibility of the filter bar. | optional |
pageSize | Integer | The number of rows visible on a single page. | optional |
Message cards
The messageCards
field specifies the behaviour of the message card, like visualization options, theme, or text.
messageCards:
- key: message-card
type: CARD
card:
text: internal text
theme: MAIN
displayName: Message Card
- key: message-card2
type: MESSAGE
message:
text: internal text
theme: INFO
Field | Type | Description | Required |
---|---|---|---|
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
type | enum | Defines the type of your message card. The possible values are: CARD , MESSAGE . | required |
CARD
Displays the message in the card format with title, description and buttons.
Field | Type | Description | Required |
---|---|---|---|
text | String | Defines the description of the card . | required |
theme | String | Defines the color theme of the card. The possible values are: INFO , WARNING , ERROR , MAIN , CTA . | required |
displayName | String | Defines the title of the card. | optional |
MESSAGE
Displays the message in the card format with description only.
Field | Type | Description | Required |
---|---|---|---|
text | String | Defines the description of the card . | required |
theme | String | Defines the color theme of the message. The possible values are: INFO , WARNING , ERROR . | required |
Problems card
The problemsCard
field specifies the behaviour of the problems card.
problemsCard:
entitySelectorTemplates:
- NOT VALIDATED IN SCHEMA
- NOT VALIDATED IN SCHEMA1
- NOT VALIDATED IN SCHEMA2
Actions
The actions
field defines actions that are available from the menu.
actions:
- actionScope: GLOBAL_DETAILS
actions:
- actionExpression: actionName|key1=value1
- actionScope: CHART_GROUP
key: chart
actionLocation: CHART
actions:
- actionExpression: actionName|key1=value1
- actionScope: ENTITIES_LIST
key: entitiesList
actionLocation: TABLE_ENTRY
actions:
- actionExpression: actionName|key1=value1
Field | Type | Description | Required |
---|---|---|---|
actionScope | enum | The defined action appears in the settings of the chosen card type. Possible values: GLOBAL_DETAILS , GLOBAL_LIST , PROPERTIES , PROBLEMS , CHART_GROUP , ENTITIES_LIST , EVENTS , LOGS , METRIC_TABLE . | required |
key | String | You can set the key if you want the action to be available only in one specific card. To add this actions in every card of this type, leave it empty. | required |
actionExpression | enum | Defines the action expression. | required |
actionLocation | enum | Defines the location of your created action. Possible values: HEADER , CHART , TABLE_ENTRY . | optional |
Metric table cards
Metric table is a graphical representation of the metrics data related to the same dimension set.
metricTableCards:
- key: metricTable
pageSize: 5
displayCharts: true
enableDetailsExpandability: true
numberOfVisibleCharts: 2
charts:
- displayName: Chart
conditions:
- NOT VALIDATED IN SCHEMA
visualizationType: GRAPH_CHART
graphChartConfig:
visualization:
themeColor: DEFAULT
seriesType: LINE
metrics:
- metricSelector: NOT VALIDATED IN SCHEMA
- metricSelector: builtin:tech.generic.processCount
visualization:
themeColor: DEFAULT
seriesType: LINE
conditions:
- NOT VALIDATED IN SCHEMA
Field | Type | Description | Required |
---|---|---|---|
key | String | The unique key of the card, which is used to reference desired card configuration. | required |
pageSize | Integer | The number of rows visible on a single page. | required |
displayCharts | boolean | If true , charts with aggregated data appears above the table. | required |
enableDetailsExpandability | boolean | If true , rows can be expanded with charts related to that row dimension values. | required |
numberOfVisibleCharts | Integer | Number of visible charts. | required |
charts | Object | Define the charts to display timeseries data in the table. Table columns are based on the dimensions from the metrics results of those charts. Make sure the metrics of all charts have the same dimensions in a result. | optional |