Mapping metrics data

After you set master-listener relation, cyclic master-listener relation, or drill-down relation, you must set parameters that must be passed from the source to the target widgets for communication. The published dashboard displays any relation only when the mapping is set. You can also specify a regular expression to extract values from the source widget and pass those values to the target widget. Additionally, you can prefix and suffix static characters to the extracted data and then pass that data to the listener or drill-down widget.

Before you begin

  • For master-listener relation, the source and target widgets must already be specified in the dashboard.

    For transformation widgets that are used as listeners, master parameter names must already be specified by using the Filter by Master Parameter operation, when you create the widgets.

  • For cyclic master-listener relation, both the transformation widgets must already be specified in the dashboard, and in both the widgets, the master parameter names must already be specified by using the Filter by Master Parameter operation.
  • For widgets that contain manual data definition, the metric values to be published on the source widget must already be specified in the manual data definition of the target widget.

About this task

Mapping metric data involves the following steps:
  1. On the source widget, select the metrics that you want to publish on the target widget or target drill-down dashboard. Enter a name for each of the selected metric values in the Parameter field.
    Note: In a cyclic master-listener relation, both the transformation widgets act as a source widget for each other. Hence, you need to specify a master parameter value in each of the transformation widgets.
  2. On the target widget (for master-listener relation) or target widget of the target dashboard (for drill-down relation), you must map those selected metrics to the predefined master parameters.
    • If the target widget contains manual data definition, then that manual data definition must contain the common metric value, and the value that you enter in the Parameter field for the source widget.
    • If the target widget contains an embedded web application or website, then the website URL or web application URL must contain the value that you enter in the Parameter field for the source widget.
      For example, https://www.example.com/{filter_name}/{parameter_name}
      Note: You can add multiple parameters to a URL.
    • If the target widget contains transformation widgets, then to the master parameter names must already be specified by using the Filter by Master Parameter operation, when you create the widgets.
      Note: In a drill-down relation, in the target transformation widget, you do not need to specify the master parameter names by using the Filter by Master Parameter operation.

For master-listener or drill-down relation between multiple widgets, in the listener or drill-down widget, you must always map the parameters of the adjacent master widget only.

For example, when set master-listener relation between four widgets, A > B > C > D, you must map the parameters as follows:
  • Widget C is the master of Widget D. Hence, in widget D, you must map the parameters of its master widget, that is, widget C.
  • Similarly, Widget B is the master of Widget C. Hence, in Widget C, you must map the parameters of its master widget, that is, widget B.
  • Similarly, in Widget B, you must map the parameters of its master widget, that is, widget A.
For drill-down relation, based on the state of the data definition in the target dashboard, the target dashboard can display any of the following Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icons:
  • Incomplete Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon. This icon is displayed when the data definition is incomplete.
  • Complete Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon. This icon is displayed when the data definition is complete.
  • Deleted Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon. This icon is displayed when the data definition is deleted.

Regular expression

Use regular expression to extract data of the column name entered in the Value field. Based on the regular expression, data is extracted for the column and then passed to the listener or drill-down widget.

If you want to prefix and suffix characters to the extracted data, and then pass that value to the listener or drill-down widget, you must specify those characters in the Characters to be added before and Characters to be added after fields. Ensure that you do not use any of the following characters or tags as prefix or suffix values: <, >, /, <script>, onload=, <svg>, <eval()>, <javascript:>, <vbscript:>, and alert().

If the source column does not contain any data that matches the regular expression, then the following values are passed to the listener or drill-down widget:
  • If prefix and suffix values are not specified, then an empty string, "" is passed to the listener or drill-down widget.
  • If prefix and suffix values are specified, then only those values are passed to the listener or drill-down widget.

    For example, if the prefix value is ac1 and suffix value is eg, then the value that is passed to the listener or drill-down widget is ac1eg

The following example shows the data that is extracted based on the regular expression, and prefix and suffix values. If the master widget contains the following table, and listener widget contains the same phone number column along with additional user details such as age, income, and location.
Table 1. Phone numbers
Sr. no. Phone number Username
1 +9182280000 John
2 7643892222 Jenny
3 +9118228000 Jack
4 +9118228002 Jim
5 +8118228000 Jerry
6 +9182285678 Jonathan
After you set the master-listener relation between such widgets, and specify the Phone numbers column in the Value field, then the listener widget displays data for the following rows:
  • If you define only a regular expression, for example, (1822800), then the regular expression extracts the digits 1822800 from the phone numbers and passes that to the listener widget. Therefore, on the master widget, when you click the 1st, 3rd, 4th, and 5th row, then the listener widget displays data for only those rows. Data is not displayed for the remaining rows.
  • Additionally, if you specify a prefix value as +91 and a suffix values as 2, then the value that is passed to the listener is +9118228002. Therefore, on the master widget, when you click row 4, then the listener widget displays data only for that row. The listener widget does not display data for any other row of the master widget.

Mapping metric data on the source widgets and target widget

Complete the following steps to map metric on the source widgets and target widget or target dashboard.
  1. On the source widget, complete the following steps:
    Note: In cyclic relation, both the transformation widgets are source widgets. Therefore, you need to perform this step in both the widgets.
    1. Click the Set Master Parameters Set Master Parameters icon.

      A Set Master Parameters window is displayed.

    2. The Default Parameter to be Published pane displays the default value that is published to the target widget.
      Note:
      • This value is the first metric value that you selected while setting data definitions for the widget.
      • For an all instances custom widget, the default value is instance for Cloud APM and ITM data sources or instanceName for Monitoring data sources.
    3. In the Parameter field, enter a name for the value.

      Note:
      • If the listener or drill-down widget contains manual data definition, then ensure that this parameter name is already specified in the manual data definition.
      • If the listener or drill-down widget contains an embedded website or web application, then ensure that this parameter name is already specified in the URL.
      • If the listener widget is a transformation widget, then ensure that this parameter name is already specified by using the Filter by Master Parameter operation.
    4. If you want to specify a parameter name for each of the remaining metric values, then in the ADDITIONAL PARAMETERS TO BE PUBLISHED pane, select individual metric values, and specify a parameter name for each metric value.

      Note:
      • If the listener or drill-down widget contains manual data definition, then ensure that these additional parameter names are already specified in the manual data definition.
      • If the listener or drill-down widget contains an embedded website or web application, then ensure that these additional parameter names are already specified in the URL.
      • If the listener widget is a transformation widget, then ensure that this parameter name is already specified by using the Filter by Master Parameter operation.
    5. To add a regular expression, click the Define a regular expression Define a regular expression icon, and complete the following steps:

      • In the Enter a regular expression field, enter a regular expression.

        To construct a regular expression, see https://regexr.com/.

        Note:
        • Regular expression is case-sensitive. For example, the regular expression ^D, extracts data that contains capital D and not small d.
        • If regular expression is applied on strings that contain multiple occurrences, then only one occurrence is extracted and passed to the listener. For example, if the string is Hello World and the regular expression is o+, then the regular expression extracts only a single occurrence of o and passes that to the listener. The regular expression does not extract oo.
      • If you want to prefix or suffix characters to the data extracted by the regular expression, then select the Add characters to the regular expression checkbox, and complete any of the following steps:
        • To prefix characters to the regular expression, enter the characters in the Characters to be added before field.
        • To suffix characters to the regular expression, enter the characters in the Characters to be added after field.

      After you set a regular expression, a green tick is displayed on the regular expression icon.

    6. If you want a specific metric value to be filtered and displayed on the target widget or dashboard, then in the SET STATIC VALUES pane, you must manually enter that metric value, and enter a parameter name for that metric value.

      Note:
      • If the listener or drill-down widget contains manual data definition, then ensure that the metric value and its parameter name are already specified in the manual data definition.
      • If the listener or drill-down widget contains an embedded website or web application, then ensure that the metric value and its parameter name are already specified in the URL.
      • If the listener widget is a transformation widget, then ensure that this parameter name is already specified by using the Filter by Master Parameter operation.
    7. For drill-down relation, if you want the drill-down dashboard to open in a new tab on Engine, then select the Open Drilldown in new tab checkbox, and enter a title for the new tab in the Tab Title field.

  2. On the target widget or target dashboard, you must complete the following steps to map all the metric values that you specified in the earlier step:

    1. For target listener widget, click Map Listener Metrics To Master Parameters Map Listener Metrics To Master Parameters icon or click Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon for target drill-down dashboard.

      For drill-down relation, the target dashboard opens displaying one or more widgets. You must identify a target widget, and then click the Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon on that widget.

      The Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon is not displayed on individual transformation widgets, but is displayed next to the Save button at the upper-right corner of the dashboard. To set a drill-down relation with a transformation widget, click the Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon that is displayed at the upper right of the dashboard.

      A Define Data Definitions for Data Sets window is displayed.

      All the widgets other than the transformation widgets display the Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon. When you click the icon on individual widgets, a Map Drilldown Metrics to Master Parameters window is displayed.

      Note:
      • Map Listener Metrics To Master Parameters or Map Drilldown Metrics To Master Parameters icon is not displayed on target listener or drill-down widget that contains manual data definition. You do not need to perform any additional steps as the common metric and parameter name are already specified in the manual data definition, and hence, are already mapped.
      • If you are mapping a widget to an all instances custom widget, then the mapping is implicit, and you do not need to select the metric that needs to be mapped with the master parameter. The mapping is implemented soon after you click the Map Listener Metrics To Master Parameters Map Listener Metrics To Master Parameters icon or Map Drilldown Metrics To Master Parameters Map Drilldown Metrics To Master Parameters icon and open the corresponding window.
      • If the target dashboard contains a multi-chart widget, then you can select an individual widget from the multi-chart widget as a target widget.
    2. Complete any of the following steps based on the number of data sources contained in the widget:

      • If the widget contains a single data source, then click the edit icon on the source row.
      • If the widget contains multiple data sources, click the View View icon on the connector source row of your choice, and then click the edit icon on the source row of your choice.
        Note: Widgets with multiple data sources cannot be mapped to a custom widget that lists all the instances.
      • For transformation widgets, in the Define Data Definitions for Data Sets window, click the View View icon on the connector source row of your choice, and then click the edit icon on the source row of your choice.
      A Map Metrics pane is displayed.
    3. Complete the following steps in the Map Metrics pane:

      • From the Metric list, select the metric that you selected in the source widget.
      • From the Operator list, select the default operator.
      • From the Master Parameter list, select the parameter value that you specified in the source widget.
      • To map additional metrics, click Add Metric.
      • To delete an individual mapped row, click the Delete Delete icon that is displayed next to that row.
      • To delete all the mapped rows, click Delete All Mappings.
        Note:
        • You must delete all the mapping before you delete any master-listener or drill-down relation.
        • To delete mapping of a widget or a dashboard that is attached to a custom widget that lists all the instances, click the Edit Edit icon and select another set of instances.
        • To delete mapping of a widget that contains an embedded website or web application, delete the parameter name that you entered in the URL.
      • To save the mapping, click the Save Save icon.
      Note: Repeat this step to map all the metrics values with their individual parameter values.
    4. Close the Map Listener Metrics To Master Parameters, Define Data Definitions for Data Sets, or Map Drilldown Metrics To Master Parameterswindow, and click the Save button on the dashboard.

      Note: If you do not click the Save button on the dashboard, then the mapping might get deleted.

What to do next

After you set the relations or modify the relation, you must publish the dashboards. You can view the relations on Engine after the dashboards are published.
Note: If you modify a drill-down dashboard, you must republish the source dashboard. Else, the changes are not displayed on Engine. You must avoid deploying the drill-down dashboard.