Customizing Event Tools for Observability Analytics

Learn about customizing the tools for navigating from real-time event lists to historical event data in Oracle Communications Unified Assurance Observability Analytics.

About Event List Analytics Tools and the OpenSearch Dashboards Discover Application

When you view event lists, you can right-click events to open context menus that contain various options. These are event menus and event tools, configured by using the Unified Assurance Configuration menu. See Menus and Tools in Unified Assurance User's Guide for information about configuring event menus and tools.

When you right-click an event, the tools available depend on your user group. By default, if you are in the Administrators or Operators user group, you will see an Event Analytics submenu. This submenu contains tools that open lists of historical events, filtered on selected event's characteristics, in the OpenSearch Dashboards Discover application. The following image shows the default Event Analytics submenu and tools:

Analytics Event Tools

Description of analytics-event-tools.png

When you first open the Discover application using the default tools, all data for each entry is combined into a single _source column. You can split the data into separate columns by clicking the Add field as column button for the fields under Available fields in the left panel. However, the customizations are forgotten when you navigate away. The next time you use the tool, you will see the default single column view again.

Customizing the Discover Application with Analytics Tools

You can control how the data is displayed the Discover application by customizing the event tools. You can customize the default tools or clone them to create your own custom tools.

The paths in the default tools include settings that control the query to run and the time range to return data for. You can customize the paths to additionally control which columns appear, which columns to sort by, and the time interval for the X axis of the graph.

You can generate a customized path by:

After generating your tool path, you can use either the UI or the REST API to update the default tools or create your own custom tools. See Customizing the Analytics Tools by Using the UI and Customizing the Analytics Tools by Using the REST API.

Understanding the Analytics Tool Paths

The default analytics tool paths contain two parameters to open the Discover application:

For example, the Search By Event Type tool uses the following path:

/go/o/app/data-explorer/discover#?_g=(time:(from:now-1y,mode:quick,to:now))&_q=(query:(language:lucene,query:'EventType:%22<EventType>%22'))

When you run the tool, <Event_Type> is replaced by the event type for the selected event. All data for each event is returned in the _source column.

Note:

The tools use Lucene query language. When you navigate to the Discover application directly from the navigation menu rather than from a tool, the default language is OpenSearch Dashboards Query Language (DQL).

When the Discover application loads, the _a parameter is automatically added to the URL. It specifies the columns to display and sort by, the graph time interval, and the index pattern to search in. You can customize this parameter to control the default settings for the event tool.

The _a parameter uses the following format:

&_a=(discover:(columns:!(<column1,column2>),interval:<interval_value>,sort:!(!(<column_name>,<direction>))),metadata:(indexPattern:<index-pattern,view:discover))

where:

The following example path includes the _a parameter:

/go/o/app/data-explorer/discover#?_g=(time:(from:now-1w,mode:quick,to:now))&_q=(query:(language:lucene,query:'EventType:%22<EventType>%22'))&_a=(discover:(columns:!('@rowtype',Node,EventType,Method,Count,Severity.name,Severity.id,Summary),interval:d,sort:!(!(Severity.id,asc),!(LastChanged,asc))),metadata:(indexPattern:a1-eventanalytics,view:discover))

In the example:

Generating Analytics Tool Paths from the UI

Optionally, you can use the Discover application to adjust how the table is displayed, and generate the path.

  1. From the main Unified Assurance navigation menu, select Events, then select an event filter.

  2. Right-click a recent event, select Event Analytics, and then one of the default analytics tools, such as Analytic Search by Event Type.

  3. Add any columns you are interested in from the Available fields list on the panel on the left.

  4. Adjust the sorting, time range, and graph interval as needed.

  5. When you are satisfied, copy the following elements from the URL in your browser:

    • For the time range, copy _g=(time:(from:<value>,to:<value>)).

    • For the columns, copy everything in the _a element.

Note:

You can optionally adjust the query or add filters as appropriate for your environment. You can copy the entire URL, excluding the server FQDN, to include in the tool path. If you copy the entire URL, you may need to replace specific times and event fields with placeholders in the tool path that can be dynamically updated based on the selected event.

Customizing the Analytics Tools by Using the UI

  1. From the main Unified Assurance navigation menu, select Configuration, then Events, and then Tools.

  2. Select any of the default analytics tools:

    • Analytic Search By Device

    • Analytic Search By Event Text

    • Analytic Search By Event Type

    • View History

  3. Do one of the following:

    • Customize the default tool by adding your new _a parameter to the end of the path and optionally adjusting any other parameters.

    • Create a custom tool:

      1. Click the Clone button.

      2. Customize the tool as needed by changing the name, icon, target, or journal fields.

      3. In Path, add your new _a parameter to the end, and optionally adjust any other parameters.

  4. Click Submit.

  5. If you created a custom tool, add it to an existing menu or create a new menu for it. See Menus in Unified Assurance User's Guide for information about using the Menus UI.

Customizing the Analytics Tools by Using the REST API

You can update an existing tool, or create your own custom tool by using the REST API.

This section gives some sample cURL requests to update and create tools. For complete information about the various endpoints mentioned, including a detailed discussion of how the batch endpoint works, see REST API for Unified Assurance Core.

Customizing an Existing Analytics Tool by Using the REST API

To customize an existing tool:

  1. Get the ID of the default analytics tools by making the following request:

    curl -X GET --user-agent "Assure1 CURL ClientCertificate" --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key 'https://<webFQDN>/api/event/Tools?filter=%5B%7B%22property%22%3A%22ToolName%22%2C%22value%22%3A%22Analytic%22%7D%5D'

    Copy the value of ToolID for the tool you want to update.

  2. Create a file called AnalyticsToolUpdate.json with the JSON formatted tool definition. For example, to update the default Analytic Search By Event Type with the columns and sorting information described in Understanding the Analytics Tool Paths, if ToolID is 41:

    {
"ToolID": "41",
"ToolName": "Analytic Search By Event Type",
"ToolTypeID": "1",
"ToolTypeName": "View",
"JournalStatusName": "Enabled",
"JournalStatusIcon": "OrbGreen.png",
"Icon": "fugue/application-search-result.png",
"JournalStatus": "1",
"JournalText": "Ran 'Analytic Search By Event Type' Tool",
"JournalAction": "",
"JournalActor": "",
"ToolPath": "/go/o/app/data-explorer/discover#?_g=(time:(from:now-1y,mode:quick,to:now))&_q=(query:(language:lucene,query:'EventType:%22<EventType>%22'))&_a=(discover:(columns:!('@rowtype',Node,EventType,Method,Count,Severity.name,Severity.id,Summary),interval:d,sort:!(!(Severity.id,asc),!(LastChanged,asc))),metadata:(indexPattern:a1-eventanalytics,view:discover))",
"ToolPathType": "Remote",
"AugmentData": "1",
"Refresh": "0",
"Width": "800",
"Height": "600",
"ToolTarget": "newtab",
"ToolTargetDisplay": "New Tab",
"ToolPathTypeID": "4",
"ToolSQL": null
}

  3. Update the tool by making the following request:

    curl -X PUT --user-agent "Assure1 CURL ClientCertificate" --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -d @AnalyticsToolUpdate.json 'https://<webFQDN>/api/event/Tools/<id>'

Creating Custom Tools and Menus by Using the REST API

Instead of updating the default tools, you can create new tools by submitting POST requests to the /api/event/Tools endpoint, then adding them to menus by using the /api/event/menus endpoint.

You can use the /api/core/Batch/execute endpoint to create or update multiple tools and menus in one API call. The following example batch request creates new tools and adds them to new menus under the default Administrators and Operators menus by making a single call to the batch endpoint:

  1. Create a json file called NewAnalyticsTools.json with the following content: 

    {
  "Actions": 
    [
      {
        "api": "event/Tools",
        "method": "create",
        "data":
          { "ToolName": "History Search for this Event","ToolTypeID": "1","Width": "800","Height": "600","ToolPath": "/go/o/app/data-explorer/discover#?_q=(filters:!(),query:(language:lucene,query:'EventID:%22<EventID>%22'))&_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:'<FirstReported>',to:'<LastChanged>'))&_a=(discover:(columns:!('@rowtype',Node,EventType,Method,Count,Severity.name,Summary),sort:!(!(LastChanged,asc))),metadata:(indexPattern:a1-eventanalytics,view:discover))","JournalStatus": "0","AugmentData": "1","ToolTarget": "newtab","ToolTargetDisplay": "New Tab","Icon": "fugue/application-search-result.png","Refresh": "0","ToolPathTypeID": "4","JournalText": "","JournalAction": "","JournalActor": "" },
        "response": [
          { "varName": "MyHistoryToolID_1","fieldName": "ToolID","varType": "single" }]
      },
      {
        "api": "event/Tools",
        "method": "create",
        "data":
          { "ToolName": "History Search by Node", "ToolTypeID": "1", "Width": "800", "Height": "600", "ToolPath": "/go/o/app/data-explorer/discover#?_q=(filters:!(),query:(language:lucene,query:'Node:%22<Node>%22'))&_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-7d,to:now))&_a=(discover:(columns:!('@rowtype',Node,EventType,Method,Count,Severity.name,Summary),sort:!(!())),metadata:(indexPattern:a1-eventanalytics,view:discover))", "JournalStatus": "0", "AugmentData": "1", "ToolTarget": "newtab", "ToolTargetDisplay": "New Tab", "Icon": "fugue/application-search-result.png", "Refresh": "0", "ToolPathTypeID": "4", "JournalText": "", "JournalAction": "", "JournalActor": "" },
        "response": [
          { "varName": "MyHistoryToolID_2", "fieldName": "ToolID", "varType": "single" }]
      },
      {
        "api": "event/Tools",
        "method": "create",
        "data":
          { "ToolName": "History Search by EventType", "ToolTypeID": "1", "Width": "800", "Height": "600", "ToolPath": "/go/o/app/data-explorer/discover#?_q=(filters:!(),query:(language:lucene,query:'EventType:%22<EventType>%22'))&_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-7d,to:now))&_a=(discover:(columns:!('@rowtype',Node,EventType,Method,Count,Severity.name,Summary),sort:!(!())),metadata:(indexPattern:a1-eventanalytics,view:discover))", "JournalStatus": "0", "AugmentData": "1", "ToolTarget": "newtab", "ToolTargetDisplay": "New Tab", "Icon": "fugue/application-search-result.png", "Refresh": "0", "ToolPathTypeID": "4", "JournalText": "", "JournalAction": "", "JournalActor": "" },
        "response": [
          { "varName": "MyHistoryToolID_3", "fieldName": "ToolID", "varType": "single" }]
      },
      {
        "api": "event/Tools",
        "method": "create",
        "data":
          { "ToolName": "History Search by Summary ", "ToolTypeID": "1", "Width": "800", "Height": "600", "ToolPath": "/go/o/app/data-explorer/discover#?_q=(filters:!(),query:(language:lucene,query:'Summary:%22<Summary>%22'))&_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-7d,to:now))&_a=(discover:(columns:!('@rowtype',Node,EventType,Method,Count,Severity.name,Summary),sort:!(!())),metadata:(indexPattern:a1-eventanalytics,view:discover))", "JournalStatus": "0", "AugmentData": "1", "ToolTarget": "newtab", "ToolTargetDisplay": "New Tab", "Icon": "fugue/application-search-result.png", "Refresh": "0", "ToolPathTypeID": "4", "JournalText": "", "JournalAction": "", "JournalActor": "" },
        "response": [
          { "varName": "MyHistoryToolID_4", "fieldName": "ToolID", "varType": "single" }]
      },
      {
        "api": "event/Tools",
        "method": "create",
        "data":
          { "ToolName": "View Journal History for this Event", "ToolTypeID": "1", "Width": "800", "Height": "600", "ToolPath": "/go/o/app/data-explorer/discover#?_q=(filters:!(),query:(language:lucene,query:'EventID:%22<EventID>%22'))&_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:'<FirstReported>',to:'now'))&_a=(discover:(columns:!(EventID,Action,Actor,Entry,Username),sort:!(!())),metadata:(indexPattern:a1-eventjournals,view:discover))", "JournalStatus": "0", "AugmentData": "1", "ToolTarget": "newtab", "ToolTargetDisplay": "New Tab", "Icon": "fugue/application-search-result.png", "Refresh": "0", "ToolPathTypeID": "4", "JournalText": "", "JournalAction": "", "JournalActor": "" },
        "response": [
          { "varName": "MyHistoryToolID_6", "fieldName": "ToolID", "varType": "single" }]
      },
      {
        "api": "event/Tools",
        "method": "read",
        "dynamicData": {
          "limit": 1,
          "filter": [
            { "property": "ToolName", "value": "Anomaly Explorer", "operator": "eq" }]},
        "response": [
          { "varName": "MyHistoryToolID_5", "fieldName": "ToolID", "varType": "single" }]
      },
      {
        "api": "event/Menus",
        "method": "create",
        "data":
          { "MenuName": "Event History", "ParentMenuID": "2", "UserGroupID": "", "DefaultMenu": "" },
        "dynamicData":
          { "Tools": [ "$MyHistoryToolID_1", "$MyHistoryToolID_2", "$MyHistoryToolID_3", "$MyHistoryToolID_4", "$MyHistoryToolID_5", "$MyHistoryToolID_6" ] }
      },
      {
        "api": "event/Menus",
        "method": "create",
        "data":
          { "MenuName": "Event History", "ParentMenuID": "3", "UserGroupID": "", "DefaultMenu": "" },
        "dynamicData":
          { "Tools": [ "$MyHistoryToolID_1", "$MyHistoryToolID_2", "$MyHistoryToolID_3", "$MyHistoryToolID_4", "$MyHistoryToolID_5", "$MyHistoryToolID_6" ] } 
      }
    ]
}

    The request body:

    1. Creates five new tools that use custom columns, and stores their IDs in variables to use later in the batch.

      The tools mimic the default event tools, and an additional sample tool, View Journal History for this Event, searches the event journals index for journals related to the event.

    2. Gets the ID of the existing Anomaly Explorer tool and stores it in a variable to use later in the batch.

    3. Creates a new Event History menu under each of the existing default menus (2 is the Administrators menu and 3 is the Operators menu), and adds the tools to them, using the IDs in the variables from the earlier calls.

  2. Create the tools and menus by submitting the following request:

    curl -X POST --user-agent "Assure1 CURL ClientCertificate" --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -d @NewAnalyticsTools.json 'https://<webFQDN>/api/core/Batch/execute'

  3. Verify that the tools and menus appear and work as expected in the UI.

Troubleshooting Tool Paths

If you do not create valid paths, you may see errors when you run the tool.

Some common resolutions are: