Managing Session Metrics Using the Public API

Structuring a Session Metric Definition for an API Request

PerfMon

To structure a PerfMon Session Metric definition, use a JSON schema. Start by defining a JSON schema that outlines the structure of a PerfMon Session Metric.

The following JSON schema consists of general properties like type, name, and description, along with a nested measurement object that specifies performance counter details.

{
  "type": "string",
  "name": "string",
  "description": "string",
  "tag": "string",
  "measurement": {
    "counterCategory": "string",
    "counterName": "string",
    "counterInstance": "string",
    "displayName": "string",
    "unit": "string"
  }
}

In this example:

• "type": The type of the metric, e.g., "PerformanceCounter."

• "name": The name of the metric as defined in its general settings.

• "description": A short description of the metric, describing what it measures.

• "tag" (Optional): A label used for sorting, filtering, and searching in future Login Enterprise versions.

• "measurement": An object containing properties specific to the performance counter:

  • "counterCategory": The category of the performance counter.

  • "counterName": The specific counter within the category, e.g., "% Idle Time."

  • "counterInstance": (Optional): The instance of the counter, e.g., "_Total."

  • "displayName": A user-friendly name shown in charts.

  • "unit": The unit of measurement, e.g., "%". This value is shown on the y-axis in charts. Only metrics with the same unit can be displayed on the same chart.

Now that you've structured your JSON object, you need to use it in an API request to create your Session Metric Definition. This way, you will be able to add a Session Metrics definition to a Session Metric Group and edit or delete it as necessary.

WMI

The following JSON schema consists of general properties, like type, name, and description, along with a nested measurement object that specifies WMI counter details.

{
  "type": "WmiQuery",
  "name": "string",
  "description": "string",
  "tag": "string",
  "wmiQuery": "string",
  "namespace": "string",
  "instanceField": "string",
  "measurements": [
    {
      "propertyName": "string",
      "summarizeOperation": "none",
      "displayName": "string",
      "unit": "string"
    }
  ]
}

In this example:

• "type": The type of the metric, e.g., "WMIQuery."

• "name": The name of the metric as defined in its general settings.

• "description": A short description of the metric, describing what it measures.

• "tag" (Optional): A label used for sorting, filtering, and searching in future Login Enterprise versions.

• "wmiQuery": WMI query string to retrieve the metrics. The string has to be in the SELECT, FROM, WHERE format.

• "namespace": WMI namespace to specify the database for the query. If left blank, the default namespace "root\cimv2" will be used.

• "instanceField": The field name describing the instance, not the actual instance name. For example, if you use '_Total' as an instance, you would reference the 'Name' column in the dataset listing the instances.

• "measurement": An object containing properties specific to the performance counter:

  • "propertyName": The property name corresponding to the WMI property.

  • "summarizeOperation": The summarization operation for the measurement. This way, you can aggregate multiple instances to generate results using operations such as min, max, avg, and sum. If the summarizeOperation is set to 'none,' up to 16 instances will be returned in a random order.

  • "displayName": A user-friendly name shown in charts.

  • "unit": The unit of measurement, e.g., "%". This value is shown on the y-axis in charts. Only metrics with the same unit can be displayed on the same chart.

Now that you've structured your JSON object, you need to use it in an API request to create your Session Metric Definition. This way, you will be able to add a Session Metric Definition to a Session Metric Group and edit or delete it as necessary.

Accessing the API

To learn how to access the API in Login Enterprise, see Accessing the Public API.

Creating a Session Metric Definition

1. In the Swagger UI console, find UserSessionMetricDefinition

2. In UserSessionMetricDefinition, click POST /v7/user-session-metric-definition

3. In the top-right corner, click Try it out (The Request body field will open).

4. Paste the JSON object you’ve defined in Structuring a PerfMon Session Metric Definition for an API Request into the Request body field.

5. Click Execute.

If successful, the API response will return a key (ID) of a new Session Metric definition. Copy the ID to the clipboard, as you will need this ID when adding your Session Metric to a Session Metric Group.

{
"id": "755ef1b3-0a2d-4718-9746-3eabbcc69229"
}

Creating a Group for Session Metric Definitions

1. In the Swagger UI console, find SessionMetricDefinitionGroup.

2. In SessionMetricDefinitionGroup, click POST /v7/session-metric-definition-groups.

3. In the top-right corner, click Try it out (The Request body field will open).

4. In the "name" parameter, specify the name of your Group, e.g., Custom Metrics.

5. The "description" field is optional. You can fill it out to provide additional information about the parameter, explaining that the custom metric group is a logical collection of related metrics that facilitates management and analysis.

6. In "definitionKeys", provide the ID of the Session Metric definition returned from the API request in Creating a Session Metric Definition.

7. Click Execute.

If successful, the API response will return the groupId of a new Session Metric Group. Copy the ID to the clipboard, as you will need this ID when adding members to a Session Metric Group.

{
"id": "a2f7d6d2-1dd8-4f42-a455-b741535527e1"
}

Adding a Session Metric Definition to a Group

To add Session Metric definitions, for example, CPU and Memory, to a Group:

1. In the Swagger UI console, find UserSessionMetricDefinition.

2. In UserSessionMetricDefinition, click GET /v7/user-session-metric-definitions.

3. In the top-right, click Try it out, and then Execute.

The API response will return a list of existing Session Metrics. The Default Session Metrics are shown as "BuiltIn":

{
"type": "BuiltIn",
"key": "12a1cbf2-cf51-ee11-92e0-000d3a1d9eab",
"metricId": 1,
"sessionMetricsType": "cpuUsage",
"displayName": "CPU",
"unit": "%"
},...

Adding Members to a Group

To add existing Session Metrics (Members) to a Group:

1. In the Swagger UI console, find SessionMetricDefinitionGroupMembers.

2. In SessionMetricDefinitionGroupMembers, click POST /v7/session-metric-definition-groups/{group-id}/members.

3. In the top-right, click Try it out (The Request body field will open).

4. In groupId, specify the ID of the Group returned from the API request in Creating a Group for Session Metric Definitions.

5. In the Request body, provide the "key" (ID) of each Session Metric you want to add to a Session Metric Group. To add, for example, only the "CPU" Session Metric, specify the "key" returned from the API request in Adding a Session Metric Definition to a Group.

6. Click Execute.