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.

yaml
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.

yaml
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.

yaml
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:

yaml
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:

yaml
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.

yaml
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.

yaml
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.

yaml
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:

yaml
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:

yaml
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.

yaml
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.

yaml
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 type syn:disk that have a relationship of from direction and runsOn type to the syn:diskmanager represented via the $(entityConditions) placeholder that stands for a focused entity.

yaml
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.

yaml
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.

yaml
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.

yaml
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.

yaml
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.

yaml
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.

yaml
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

Unified analysis reference

Details settings

staticContent

layout

Details injections

Details filters

relationships

entityFilters

List settings

staticContent required

layout required

List injections

List filters

relationships

entityFilters

Properties card

properties required

RELATION

ATTRIBUTE

Chart group cards

charts

visualizationType

GRAPH_CHART

metricSelector

PIE_CHART

SINGLE_VALUE

Entities list cards

Events cards

Logs cards

Message cards

CARD

MESSAGE

Problems card

Actions

Metric table cards

`staticContent`

`layout`

`relationships`

`entityFilters`

`staticContent` required

`layout` required

`relationships`

`entityFilters`

`properties` required

`RELATION`

`ATTRIBUTE`

`charts`

`visualizationType`

`GRAPH_CHART`

`metricSelector`

`PIE_CHART`

`SINGLE_VALUE`

`CARD`

`MESSAGE`