Analytic Management
Prerequisites: Adding an Analytic to Catalog Using REST APIs
Understand how to find the URI values and to configure the REST headers for each API.
Before You Begin
Review the following information.
Adding and Validating an Analytic Using REST APIs
The Analytics Catalog is a repository for hosting analytics. This example guides you through the process to add an analytic to the Analytics Catalog.
About This Task
The high level steps are as follows.
- (Optional) Update the catalog taxonomy structure for the analytic classification.
- Create an analytic catalog entry with the attributes for the analytic.
- Upload the executable to the catalog.
- Validate that the analytic runs in the Cloud Foundry environment (deploy and run the analytic, then retrieve the results).
Procedure
About Running a Single Analytic
If you have a self-contained data set you can run (execute) a single analytic without providing an analytic template or using the orchestration runtime. There are three methods to run a single analytic.
- Running an Analytic Synchronously Using the Analytics Catalog
- Running an Analytic Synchronously Using a Direct Call
- Running an Analytic Asynchronously Using a Direct Call
Running an Analytic Synchronously Using the Analytics Catalog
Run a single analytic synchronously as follows.
Before You Begin
The analytic must be already validated and deployed to the Cloud Foundry environment before it can be run. For more information and detailed steps, see
Issue the following REST API request. Provide the analytic input JSON in the body of the request each time the analytic is run.
POST <catalog_uri>/api/v1/catalog/analytics/{id}/executionIf you are running the analytic multiple times with the same input data, or you have a large data set, you can upload the data as an artifact attached to the analytic (see Attaching Additional Artifacts to an Analytic Catalog Entry) to be retrieved when calling the analytic execution API. You can then call the analytic execution API without a request body, but with the artifact ID a query parameter, as in the following endpoint.
POST <catalog_uri>/api/v1/catalog/analytics/{analyticId}/execution?inputId={artifactId}Running an Analytic Synchronously Using a Direct Call
Run a single analytic synchronously as follows. You can provide different data sets in the body of the request each time the analytic is run.
Before You Begin
The analytic must be already validated and deployed to the Cloud Foundry environment before it can be run. For more information and detailed steps, see
Issue the following REST API request.
POST <analytic_uri>/api/v1/analytic/executionWhere <analytic_uri> is the analytic catalog entry id followed by your Predix platform domain name. For example, https://09718078-95e7-4b60-b74a-152838f03b41.analytics.run.aws-usw02-pr.ice.predix.io. For more information about how to determine the <analytic_uri>, see Deployed Analytic URI.
The following table describes the request parameters.
| Parameter | Parameter Type | Data Type | Description |
|---|---|---|---|
body | body, required | JSON string | The JSON string that will be passed to the analytic via its configured entry point in the config.json. |
Predix-Zone-Id | header, required | String | The zone-id from the Analytics Catalog. |
Authorization | header, required | String | The user's UAA token. |
If an error occurs it will contain an error response object similar to the following.
{
"code": <see troubleshooting guide>,
"severity": <not used at this time>,
"detail": <a detailed description of the error>,
"message": <a summary description of the error>
}Running an Analytic Asynchronously Using a Direct Call
Run a single analytic asynchronously as follows. Provide the analytic input JSON in the body of the request each time the analytic is run.
Before You Begin
The analytic must be already validated and deployed to the Cloud Foundry environment before it can be run. For more information and detailed steps, see
Procedure
Retrieving Analytic Catalog Entries
You can retrieve analytic catalog entries by pagination, sorting, and filtering criteria by issuing the following REST API request.
GET <catalog_uri>/api/v1/catalog/analytics The following sample request retrieves entries starting at page three in a zero-based page index, displaying 10 entries per page, and sorted by analytic name in ascending order.
GET <catalog_uri>/api/v1/catalog/analytics?page=2&size=10&sortOrder=asc&sortableFields=nameThe following sample request retrieves entries belonging to an /Analytics/Diagnostic taxonomy .
GET <catalog_uri>/api/v1/catalog/analytics?taxonomyPath=/Analytics/DiagnosticDeploying a Production Analytic to Cloud Foundry
Before You Begin
The analytic entry has been added to the catalog and validation is completed. See Adding and Validating an Analytic Using REST APIs.
About This Task
- Promote the validated analytic to a production state so it can be consumed by the Runtime service.
- Optimize the analytics’s
memoryusage,disk usage, and number ofinstances. - Restart a previously deployed analytic.
Procedure
Retrieving Recent Analytic Logs
You can retrieve the recent logs from a deployed analytic. Reviewing the logs can be useful when debugging issues such as execution failures.
GET <catalog_uri>/api/v1/catalog/analytics/{id}/logsThe response will contain the recent analytic logs in text/plain format. The following is a sample response.
[fd3dc098-113a-4f28-b1c9-1fb0265ce58c [Fri Mar 18 22:43:56 UTC 2016] 2016-03-18 22:43:56,377 10572 px_correlation_id= px_zone_id= px_service= px_user_name= [main] INFO c.g.p.a.j.s.JavaBasedAnalyticApplication - Started JavaBasedAnalyticApplication in 9.946 seconds (JVM running for 10.999) (STDOUT, App),
fd3dc098-113a-4f28-b1c9-1fb0265ce58c [Fri Mar 18 22:48:17 UTC 2016] 2016-03-18 22:48:17,584 271779 px_correlation_id=a427cf91-c91f-4d1f-89a9-6775af8acb9a px_zone_id=<zone_id> px_service=analytic px_user_name= [http-nio-61729-exec-3] INFO c.g.p.a.j.JavaBasedAnalyticServiceImpl - analyticId=<analytic_id> status=STARTED data={"number1":2,"number2":4} (STDOUT, App),
fd3dc098-113a-4f28-b1c9-1fb0265ce58c [Fri Mar 18 22:48:17 UTC 2016] 2016-03-18 22:48:17,588 271783 px_correlation_id=a427cf91-c91f-4d1f-89a9-6775af8acb9a px_zone_id=<zone_id> px_service=analytic px_user_name= [http-nio-61729-exec-3] INFO c.g.p.a.j.JavaBasedAnalyticServiceImpl - analyticId=<analytic_id> status=COMPLETED data={"result":6} (STDOUT, App)]
Deleting an Analytic From the Catalog
Deleting a non-subscription analytic will delete it from the analytics catalog. Deleting a subscription analytic will first unsubscribe it, and then delete it from the analytics catalog.
About This Task
Delete the analytic catalog entry by ID by issuing the following REST API request.
DELETE <catalog_uri>/api/v1/catalog/analytics/{id} Managing Multiple Versions of an Analytic
Procedure
About Analytic Taxonomy
Analytics hosted in the analytic catalog are categorized by their taxonomy locations. This provides a structured method for grouping related analytics and aids in analytic retrieval.
A taxonomy is a hierarchy of taxonomy nodes. The taxonomy JSON structure specification is as follows.
- A taxonomy node contains
node_nameandchild_nodes. - A
node_namespecifies the name of the node and must not contain a forward slash ("/"). - A
child_nodecan contain an array of nested taxonomy nodes. - An empty
child_nodesarray indicates a leaf node.
Taxonomy locations can be added using the API, which expects the desired taxonomy in a JSON structure (as either a single node object or an array of node objects). This API is additive, allowing additional nodes to be inserted after the initial structure is loaded.
The following is an example of the expected JSON structure.
Sample Taxonomy JSON Structure
[
{
"node_name": "Diagnostic",
"child_nodes": [
{
"node_name": "Health Assessment",
"child_nodes": [
{
"node_name": "Fault Diagnosis",
"child_nodes": []
},
{
"node_name": "Confidence Estimation",
"child_nodes": []
},
{
"node_name": "Uncertainty Estimation",
"child_nodes": []
}
]
},
{
"node_name": "Condition Monitoring",
"child_nodes": [
{
"node_name": "Fault Isolation",
"child_nodes": []
},
{
"node_name": "Anomaly Detection",
"child_nodes": []
}
]
}
]
},
{
"node_name": "Descriptive",
"child_nodes": [
{
"node_name": "Standard Stats Techniques",
"child_nodes": [
{
"node_name": "Bivariate Analysis",
"child_nodes": [
{
"node_name": "Cross Tabulation",
"child_nodes": []
},
{
"node_name": "Scatter Plots",
"child_nodes": []
}
]
},
{
"node_name": "Univariate-Summary",
"child_nodes": []
}
]
}
]
}
]When creating or updating an analytic entry, the taxonomy location can be specified as a slash-separated path. For example:
/Diagnostic/Condition Monitoring/Anomaly Detection
/Descriptive/Standard Stats Techniques/Bivariate AnalysisTaxonomy locations must be loaded before they can be assigned to an analytic.
If the taxonomy location is not specified for an analytic entry, it uses the following default location:
/uncategorizedAdding Taxonomy Locations
A taxonomy is a hierarchical tree of categories structuring an analytic. The following API call adds the taxonomy specified in the request body to the existing taxonomy in the catalog. It does not remove any part of the existing taxonomy.
About This Task
Set up the taxonomy by issuing the following REST API request.
POST <catalog_uri>/api/v1/catalog/taxonomySample request to load a taxonomy.
{
"node_name": "Analytics",
"child_nodes": [
{
"node_name": "Diagnostic",
"child_nodes": []
},
{
"node_name": "Descriptive",
"child_nodes": []
},
{
"node_name": "Predictive",
"child_nodes": []
},
{
"node_name": "Prescriptive",
"child_nodes": []
}
]
}