Skip to content

Commit

Permalink
Merge pull request #510 from sarette/publish-9-26-2023
Browse files Browse the repository at this point in the history 
Publish 9 26 2023
  • Loading branch information
@jonathan-ly
jonathan-ly authored Sep 28, 2023
2 parents 0970613 + add5b71 commit fddbf27
Show file tree
Hide file tree
Showing 41 changed files with 1,676 additions and 0 deletions.
154 changes: 154 additions & 0 deletions products/access/docs/adem/adem-faqs.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
---
id: adem-faqs
title: Autonomous DEM API FAQs
description: Autonomous DEM API FAQs
sidebar_label: ADEM API FAQs
---

## What are ADEM APIs used for?

This API provides access to Autonomous Digital Experience Management summary, distribution and
timeseries data.It helps fetch data such as application score and Agent scores to help troubleshoot
if the issue is with the endpoint /application or the network. ADEM APIs can be additionally used to
fetch the zoom meeting data.

For more information, see [Autonomous DEM API](/access/docs/adem/).

## What type of authorization do ADEM APIs use?

ADEM APIs are routed through the API GW which uses the OAuth2 authentication. A valid Bearer token
is required, which verifies tenant access described by the following header formats:

| Prisma-Tenant | Prisma-SubTenant |
| --------------- | ------------------ |
| tenant_service_group | Mobile User Agent |
| <tenant\>:<subtenant\> | Mobile User Probe |


## What are the response types that the ADEM endpoint supports?

Each endpoint supports one or more of the following responses, specified by the response-type query
parameter:

| response-type | Description |
| --------------- | ------------ |
| summary | A summary (aggregate) of the requested object (for example, agent or application score) |
| timeseries | A timeseries of the requested object, with the each sample an aggregate over a sample period defined by the selected time interval |
| distribution | A distribution of objects, grouped by an entity and classified into good, fair, poor categories, for example, distribution of agent scores by user or endpoint |
| grouped-summary | As for summary, grouped by one or more entities, for example, agent scores grouped by user or endpoint |
| grouped-timeseries | As for timeseries, grouped by one or more entities |
| grouped-distribution | As for distribution, grouped by one or more entities |

For more information, see [ADEM Response Type Parameter](/access/docs/adem/response-type-parameter/).

## What are Groups used for?

Group parameter is used when the response-type is grouped-summary to specify which entity to group
by. The format is `Entity.<property>[,...]`.

For example, `Entity.user, Entity.endpoint` would group
results by user and endpoint. `en` is an alias for Entity so `en.user, en.endpoint` is also valid.

## What are Filters used for?


A parameter of the form `<field><operator><value>` is used to filter the ADEM query. The following operators are supported:

`>=`<br/>`<=`<br/>`==`<br/>`!=`<br/>`>`<br/>`<`

Multiple filters are supported. They can be logically combined with semi-colon to describe AND and a
comma for OR. For example,

agent_uuid==1234,agent_uuid==5678;application==Gmail,application==Zoom

would select records when the agent uuid is either 1234 OR 5678 AND the application is Gmail OR Zoom.

For more information, see [ADEM Filter Parameter](/access/docs/adem/filter-parameter/).


## What is an include parameter?

The include parameter is used to include additional results in the response - multiple includes can
be specified by comma separating. The format for this parameter is `<Include>.<property>[,..]`

| include | Alias | Description | Example |
| --------------- | ----- | ----------- | -------- |
| EntityCounts | ec | include a count of given entities | EntityCounts.user, ec.user, ec.endpoint |
| AgentProperties | ap | include agent properties | ap.ComputerName |

For more information, see [ADEM Include Parameter](/access/docs/adem/include-parameter/).

## What are endpoint types?

The endpoint device is used to specify the source of the ADEM timeseries data.

| Name | Description |
| ----- | ------------ |
| muAgent | Mobile User Agent |
| muProbe | Mobile User Probe |
| rnAgent | Remote Network Agent |
| rnProbe | Remote Network Probe |

For more information, see [ADEM Endpoint Type Parameter](/access/docs/adem/endpoint-type-parameter/).


## What is a result filter?

A result filter is used to limit results by filtering the output of the query, and maps to a HAVING
statement ( as compared with the input, which maps to a SELECT ). The output is filtered by
requiring specified scores to be in a range defined by the score classification:

| Category | Range |
| -------- | ----- |
| poor | less than 30 |
| fair | 30 → 70 |
| good | greater than 70 |


| Name | Format | Type | Description | Examples |
| ----- | ------ | ---- | ----------- | -------- |
| result-filter | Score.<field1\>==<category\>,..; | string | Limit score results by category | Score.endpointScore==fair,good Score.application==good;Score.lan==fair,good |

For more information, see [ADEM Result Filter Parameter](/access/docs/adem/result-filter-parameter/).


## What are the valid values that can be used in a time series filter?

- start, end : timestamps in Unix timestamp format (seconds), for example, start=1686814360&end=1686900760
- timerange:

| Format | Description | Example |
| ------ | ----------- | -------- |
| start,end | timestamps in Unix timestamp format (seconds) | start=1686814360&end=1686900760 |
| timerange | human readable format: <p>last_<N\>\_minutes \| hours \| days \| weeks \| months</p> | last_30\_days<br/> last_30\_minutes<br/> last_2\_weeks |

For timeseries responses, records are aggregated over a sample period which is a function of the
time interval requested, such that the granularity decreases with increasing interval. This keeps
the number of sample returned to a reasonable number whilst still allowing higher resolution at
small intervals.

| interval (days) | sample period (minutes) |
| --------------- | ----------------------- |
| <= 1 | 5 |
| <= 3 | 15 |
| <= 7 | 30 |
| <= 14 | 60 |
| <= 21 | 120 |
| > 21 | 180 |


## Is pagination supported?

Yes, pagination is supported for ADEM APIs. The following are the details of pagination or sorting parameters.
A parameter used to limit the number of results in the response, used when the response type is grouped-summary

| Name | Format | Type | Examples |
| ---- | ------ | ----- | -------- |
| pagination | page==<page\>;limit==<limit\><br/>[;sortBy==<field\>;sortOrder==asc] <br/>\| none | string | <p>page==0;limit==10;sortBy==application;<br/>sortOrder==asc</p><p>page==0;limit==20</p>none |

where page and limit are required and are the page number and number of results per page. sortBy / sortOrder are optional
If no pagination is specified, the default is page==0;limit=50. To disable paging, use pagination=none.

For more information, see [ADEM Pagination Parameter](/access/docs/adem/pagination-parameter/).


37 changes: 37 additions & 0 deletions ...ss/docs/adem/examples/application-performance/mu-experience-score-for-an-app.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
id: mu-experience-score-for-an-app
title: Get Mobile User Experience Score for an Application
description: GET Mobile User Experience Score for an Application
sidebar_label: Get Mobile User Experience Score for an Application
---

This API retrieves the Mobile User experience score for an application based on its app ID. In the Response section, the lines that are followed by a comment (<<<<<<) correspond to the location in the UI (see attached screenshot) that is enclosed in a red box.
The attached screen is located in Monitor -> Users -> User details page in the Strata Cloud Manager UI.

The following shows the portions of the UI widget where the data is displayed for this example:

![](/sase/img/adem/DOCS-3765-mu-experience-score-for-an-app.png)


## Request

GET https://api.sase.paloaltonetworks.com/adem/telemetry/v2/measure/application/score?timerange=last_3_day&filter=testUuid==3100bb11-dde4-4ab9-8503-d0c6ad5f9698&endpoint-type=muAgent&response-type=summary
header = { "prisma-tenant": "<tenant-id>" }


## Response

{
    "startTime": 1692100200,
    "endTime": 1692111000,
    "endpointType": "muAgent",
    "tenantServiceGroup": [
        "<tenant-id>:<subtenant-id>”
    ],
    "rowCount": 462,
    "average": {
        "application": 90 <<<<<<
    }
}

59 changes: 59 additions & 0 deletions ...mples/application-performance/network-performance-metrics-for-an-application.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
id: network-performance-metrics-for-an-application
title: Get Network Performance Metrics for an Application
description: Network Performance Metrics for a given application
sidebar_label: Get Network Performance Metrics for an Application
---

This API retrieves the Network Performance Metrics for a given application. In the Response section, the lines that are followed by a comment (<<<<<<) correspond to the location in the UI (see attached screenshot) that is enclosed in a red box.
The attached screen is located in Monitor -> Applications -> Application details page in the Strata Cloud Manager UI.

The following shows the portions of the UI widget where the data is displayed for this example:

![](/sase/img/adem/DOCS-3771-network-performance-metircs-for-an-app.png)


## Request

GET https://api.sase.paloaltonetworks.com//adem/telemetry/v2/measure/internet/metric? timerange=last_30_day&filter=testUuid==3100bb11-dde4-4ab9-8503-d0c6ad5f9698&endpoint-type=muAgent&response-type=timeseries
header = { "prisma-tenant": "<tenant-id>" }


## Response

{
    "startTime": 1691010000,
    "endTime": 1693602000,
    "endpointType": "muAgent",
    "tenantServiceGroup": [
         "<tenant-id>:<subtenant-id>”
    ],
    "samplePeriod": 10800,
    "series": [
        {
            "_rowCount": 352,
            "availability": 99.9, <<<<<<
            "delay": 51399, <<<<<<
            "maxDelay": 485085,
            "jitter": 17979.7, <<<<<<
            "maxJitter": 1005062,
            "loss": 0.2, <<<<<<
            "maxLoss": 60,
            "sample": 1691010000
        },
        {
            "_rowCount": 322,
            "availability": 100,
            "delay": 53642.5,
            "maxDelay": 477375,
            "jitter": 13411.3,
            "maxJitter": 851835,
            "loss": 0.1,
            "maxLoss": 14.3,
            "sample": 1691020800
        },
…….
]
}

57 changes: 57 additions & 0 deletions ...-performance/timeseries-data-of-application-performance-for-all-applications.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
id: timeseries-data-of-application-performance-for-all-applications
title: Get Timeseries Data of Application Performance for all Applications
description: Timeseries Data of Application Performance for all Applications
sidebar_label: Get Timeseries Data of Application Performance for all Applications
---

This API retrieves the timeseries data of application performance for all applications. In the Response section, the lines that are followed by a comment (<<<<<<) correspond to the location in the UI (see attached screenshot) that is enclosed in a red box. The values shown for each field, for example dnsLookupTime, are the average values for that field in the timeseries. The availability is always 100% which is indicated by 1.

The following shows the portions of the UI widget where the data is displayed for this example:

![](/sase/img/adem/DOCS-3762-timeseries-data-of-app-perf-for-all-apps.png)


## Request

GET https://api.sase.paloaltonetworks.com//adem/telemetry/v2/measure/application/metric? timerange=last_30_day&endpoint-type=muAgent&response-type=timeseries
header = { "prisma-tenant": "<tenant-id>" }


## Response

{
    "startTime": 1691334000,
    "endTime": 1693926000,
    "endpointType": "muAgent",
    "tenantServiceGroup": [
        "xxx:xxx"
    ],
    "samplePeriod": 10800,
    "series": [
        {
            "_rowCount": 3580,
            "dnsLookupTime": 42.8, <<<<<<
            "maxDnsLookupTime": 530,
            "throughput": 3316902.9,
            "maxThroughput": 75128344,
            "tcpHandshakeTime": 82406.2,
            "maxTcpHandshakeTime": 1521664,
            "sslHandshakeTime": 197720.8,
            "maxSslHandshakeTime": 10583855,
            "waitTime": 245688.1,
            "maxWaitTime": 13142609,
            "dataTransferTime": 264332,
            "maxDataTransferTime": 15013933,
            "timeToFirstByte": 525857.4, <<<<<<
            "maxTimeToFirstByte": 13879987,
            "totalTime": 828298.6,
            "wireSize": 65611.4,
            "availability": 1, <<<<<<
            "sample": 1691334000
        },
…..
]
}

47 changes: 47 additions & 0 deletions products/access/docs/adem/examples/application-test/application-testuuid.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
id: application-testuuid
title: Get an Application’s testUUID
description: Get an Application’s testUUID
sidebar_label: Get an Application’s testUUID
---

This API retrieves an application’s test UUID. This API does not have an impact on the UI as it only fetches the test ID and name.

## Request

GET https://api.sase.paloaltonetworks.com//adem/telemetry/v2/measure/application/score?timerange=last_3_day&group=en.testName,en.test&endpoint-type=muAgent&response-type=grouped-summary
header = { "prisma-tenant": "<tenant-id>" }


## Response

{
    "startTime": 1693344600,
    "endTime": 1693603800,
    "endpointType": "muAgent",
    "tenantServiceGroup": [
          "<tenant-id>:<subtenant-id>”
    ],
    "pagination": {
        "page": 0,
        "limit": 50,
        "sortOrder": "DESC",
        "enabled": true
    },
    "collection": [
     ……
        {
            "rowCount": 13166,
            "id": {
                "test": "<test-id>", <<<<<<
                "testName": "Google" <<<<<<
            },
            "average": {
                "application": 91.6
            }
        },
    ……..
    ]
}

Loading

0 comments on commit fddbf27

Please sign in to comment.