Monitoring External Models

Overview
Monitoring can be used to track the behavior of external models running outside of the Hydrosphere platform. This tutorial describes how to register an external model, trigger analysis over your requests, and retrieve results.
By the end of this tutorial you will know how to:
Register a model
Upload training data
Assign custom metrics
Invoke analysis
Retrieve metrics
Prerequisites
For this tutorial, you need to have Hydrosphere Platform deployed on your local machine with Sonar component enabled. If you don't have it yet, please follow this guide first:
​Platform Installation​
You also need a running external model, capable of producing predictions. Inputs and outputs of that model will be fed into Hydrosphere for monitoring purposes.
Model registration
First, you have to register an external model. To do that, submit a JSON document, defining your model.
Request document structure
This section describes the structure of the JSON document used to register external models within the platform.
Top-level members
The document must contain the following top-level members, describing the interface of your model:
name: the name of the registered model. This name uniquely identifies a collection of model versions, registered within the Hydrosphere platform.
signature: the interface of the registered model. This member describes inputs and outputs of the model, as well as other complementary metadata, such as data profile for each field.  
A document may contain additional top-level members, describing other details of your model.
metadata: the metadata of the registered model. The structure of the object is not strictly defined. The only constraint is that the object must have a key-value structure, where a value can only be of a simple data type (string, number, boolean).
monitoringConfiguration: monitoring configuration to be used for this model. 
This example shows, how a model can be defined at the top level:
1
{  
2
    "name": "external-model-example",
3
    "metadata": {
4
        "architecture": "Feed-forward neural network",
5
        "description": "Sample external model example",
6
        "author": "Hydrosphere.io",
7
        "training-data": "s3://bucket/external-model-example/data/",
8
        "endpoint": "http://example.com/api/external-model/"
9
    },
10
    "monitoringConfiguration": {
11
        "batchSize": 100
12
    },
13
    "signature": {
14
        ...
15
    }
16
}
Copied!
MonitoringConfiguration object
monitoringConfiguration object defines a monitoring configuration to be used for the model version. The object must contain the following members:
batchSize: size of the batch to be used for aggregations.
The example below shows how a monitoringConfiguration object can be defined.
1
{
2
    "batchSize": 100,
3
}
Copied!
Signature object
signature object describes the signature of the model. The signature object must contain the following members:
signatureName: The signature of the model, used to process the request;
inputs: A collection of fields, defining the inputs of the model. Each item in the collection describes a single data entry, its type, shape, and profile. A collection must contain at least one item;
outputs: A collection of fields, defining the outputs of the model. Each item in the collection describes a single data entry, its type, shape, and profile. A collection must contain at least one item. 
The example below shows how a predict object can be defined.
1
{
2
    "signatureName": "predict",
3
    "inputs": [
4
        ...
5
    ],
6
    "outputs": [
7
        ...
8
    ]
9
}
Copied!
Field object
Items in the inputs / outputs collections are collectively called "fields". The field object must contain the following members:
name: Name of the field;
dtype: Data type of the field. 
profile: Data profile of the field. 
shape: Shape of the field.
The only valid options for dtype are:
DT_STRING;
DT_BOOL;
DT_VARIANT;
DT_HALF;
DT_FLOAT;
DT_DOUBLE;
DT_INT8;
DT_INT16;
DT_INT32;
DT_INT64;
DT_UINT8;
DT_UINT16;
DT_UINT32;
DT_UINT64;
DT_QINT8;
DT_QINT16;
DT_QINT32;
DT_QUINT8;
DT_QUINT16;
DT_COMPLEX64;
DT_COMPLEX128;
The only valid options for profile are:
NONE
NUMERICAL
TEXT
IMAGE
The example below shows how a single field object can be defined.
1
{
2
    "name": "age",
3
    "dtype": "DT_INT32",
4
    "profile": "NUMERICAL",
5
    "shape": {
6
        ...
7
    }
8
}
Copied!
Shape object
shape object defines the shape of the data that the model is processing. The shape object must contain the following members:
dims: An array of dimensions. A collection may be empty — in that case, the tensor will be interpreted as a scalar value. 
The example below shows how a shape object can be defined.
1
"shape": {
2
    "dims": [-1, 64, 64],
3
}
Copied!
Registering external model
A model can be registered by sending a POST request to the /api/v2/externalmodel endpoint. The request must include a model definition as primary data.
The request below shows an example of an external model registration.
1
POST /api/v2/externalmodel HTTP/1.1
2
Content-Type: application/json
3
Accept: application/json
4
​
5
{
6
    "name": "external-model-example",
7
    "metadata": {
8
        "architecture": "Feed-forward neural network",
9
        "description": "Sample external model example",
10
        "author": "Hydrosphere.io",
11
        "training-data": "s3://bucket/external-model-example/data/",
12
        "endpoint": "http://example.com/api/external-model/"
13
    },
14
    "monitoringConfiguration": {
15
        "batchSize": 100
16
    },
17
    "signature": {
18
        "signatureName": "predict",
19
        "inputs": [
20
            {
21
                "name": "in",
22
                "dtype": "DT_DOUBLE",
23
                "profile": "NUMERICAL",
24
                "shape": {
25
                    "dims": []
26
                }
27
            }
28
        ],
29
        "outputs": [
30
            {
31
                "name": "out",
32
                "dtype": "DT_DOUBLE",
33
                "profile": "NUMERICAL",
34
                "shape": {
35
                    "dims": []
36
                }
37
            }
38
        ]
39
    }
40
}
Copied!
As a response, the server will return a JSON object with complementary metadata, identifying a registered model version.
Response document structure
The response object from the external model registration request contains the following fields:
id: Model version ID, uniquely identifying a registered model version within Hydrosphere platform;
model: An object, representing a model collection, registered in Hydrosphere platform;
modelVersion: Model version number in the model collection; 
signature: Contract of the model, similar to the one defined in the request section above;
metadata: Metadata of the model, similar to the one defined in the request section above;
monitoringConfiguration: MonitoringConfiguration of the model, similar to the one defined in the request section above;
created: Timestamp, indicating when the model was registered. 
Note theid field. It will be referred as MODEL_VERSION_ID later throughout the article.
Model object
model object represents a collection of model versions, registered in the platform. The response model object contains the following fields:
id: ID of the model collection;
name: Name of the model collection.
The example below shows, a sample server response from an external model registration request.
1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
​
4
{
5
    "id": 1,
6
    "model": {
7
        "id": 1,
8
        "name": "external-model-example"
9
    },
10
    "modelVersion": 1,
11
    "created": "2020-01-09T16:25:02.915Z",
12
    "signature": { 
13
        "signatureName": "predict",
14
        "inputs": [
15
            {
16
                "name": "in",
17
                "dtype": "DT_DOUBLE",
18
                "profile": "NUMERICAL",
19
                "shape": {
20
                    "dims": []
21
                }
22
            }
23
        ],
24
        "outputs": [
25
            {
26
                "name": "out",
27
                "dtype": "DT_DOUBLE",
28
                "profile": "NUMERICAL",
29
                "shape": {
30
                    "dims": []
31
                }
32
            }
33
        ]
34
    },
35
    "metadata": { 
36
        "architecture": "Feed-forward neural network",
37
        "description": "Sample external model example",
38
        "author": "Hydrosphere.io",
39
        "training-data": "s3://bucket/external-model-example/data/",
40
        "endpoint": "http://example.com/api/external-model/"
41
    },
42
    "monitoringConfiguration": {
43
        "batchSize": 100
44
    }
45
}
Copied!
Training data upload
To let Hydrosphere calculate the metrics of your requests, you have to submit the training data. You can do so by:
​using CLI​
​using HTTP endpoint​
In each case your training data should be represented as a CSV document, containing fields named exactly as in the interface of your model.
Currently, we support uploading training data as .csv files and utilizing it for NUMERICAL, CATEGORICAL, and TEXT profiles only.
Upload using CLI
Switch to the cluster, suitable for your current flow.
1
$ hs cluster use example-cluster
2
Switched to cluster '{'cluster': {'server': '<hydrosphere>'}, 'name': 'example-cluster'}'
Copied!
If you don't have a defined cluster yet, create one using the following command.
1
$ hs cluster add --server <hydrosphere> --name example-cluster
2
Cluster 'example-cluster' @ <hydrosphere> added successfully
3
$ hs cluster use example-cluster
Copied!
Make sure you have a local copy of the training data that you want to submit.
1
$ head external-model-data.csv
2
in,out
3
0.8744973,0.74737076
4
0.35367096,0.68612554
5
0.12600919,0.23873545
6
0.22988156,0.01602719
7
0.09958467,0.81491237
8
0.50324137,0.23527377
9
0.02184051,0.37468397
10
0.23937149,0.66311923
11
0.48611933,0.65467976
12
0.98475208,0.28292798
Copied!
Submit the training data. You must specify two parameters:
--model-version: A string indicating the model version to which you want to submit the data. The string should be formatted in the following way <model-name>:<model-version>;
--filename: Path to a filename, that you want to submit. 
If you already have your training data uploaded to S3, you can specify a path to that object URI using --s3path parameter instead of --filename. The object behind this URI should be available to the Hydrosphere instance.
1
$ hs profile push \
2
    --model-version external-model-example:1 \
3
    --filename external-model-data.csv
Copied!
Depending on the size of your data, you will have to wait for the data to be uploaded. If you don't want to wait, you can use the --async flag.
Upload using an HTTP endpoint
To upload your data using an HTTP endpoint, stream it to the /monitoring/profiles/batch/<MODEL_VERSION_ID> endpoint.
1
curl -v -D - -X POST -H "Transfer-Encoding: chunked" -H "Content-Type: text/plain" --compressed --data-binary @file.csv <HYDROSPHERE_ADDRESS>/monitoring/profiles/batch/<MODEL_VERSION_ID>
Copied!
You can acquire MODEL_VERSION_ID by sending a GET request to /model/version/<MODEL_NAME>/<MODEL_VERSION> endpoint. The response document will have a similar structure, already defined @refabove.
Custom metrics assignment
This step is optional. If you wish to assign a custom monitoring metric to a model, you can do it by:
using Hydrosphere UI
using HTTP endpoint
Using Hydrosphere UI
To find out how to assign metrics using Hydrosphere UI, refer to this page.
Using HTTP endpoint
To assign metrics using HTTP endpoint, you will have to submit a JSON document, defining a monitoring specification.
Top-level members
The document must contain the following top-level members.
name: The name of the monitoring metric;
modelVersionId: Unique identifier of the model to which you want to assign a metric;
config: Object, representing a configuration of the metric, which will be applied to the model. 
The example below shows how a metric can be defined on the top level.
1
{
2
    "name": "string",
3
    "modelVersionId": 1,
4
    "config": {
5
        ...
6
    }
7
}
Copied!
Config object
config object defines a configuration of the monitoring metric that will monitor the model. The model must contain the following members:
modelVersionId: Unique identifier of the model that will monitor requests;
threshold: Threshold value, against which monitoring values will be compared using a comparison operator;
thresholdCmpOperator: Object, representing a comparison operator. 
The example below shows, how a metric can be defined on a top-level.
1
{
2
    "modelVersionId": 2,
3
    "threshold": 0.5,
4
    "thresholdCmpOperator": {
5
        ...
6
    }
7
}
Copied!
ThresholdCmpOperator object
thresholdCmpOperator object defines the kind of comparison operator that will be used when comparing a value produced by the metric against the threshold. The object must contain the following members:
kind: Kind of comparison operator.
The only valid options for kind are:
Eq;
NotEq;
Greater;
Less;
GreaterEq;
LessEq. 
The example below shows, how a metric can be defined on the top level.
1
{
2
    "kind": "LessEq"
3
}
Copied!
The request below shows an example of assigning a monitoring metric. At this moment, both monitoring and the actual prediction model should be registered/uploaded to the platform.
1
POST /monitoring/metricspec HTTP/1.1
2
Content-Type: application/json
3
Accept: application/json
4
​
5
{
6
    "name": "string",
7
    "modelVersionId": 1,
8
    "config": {
9
        "modelVersionId": 2,
10
        "threshold": 0.5,
11
        "thresholdCmpOperator": {
12
            "kind": "LessEq"
13
        }
14
    }
15
}
Copied!
Analysis invocation
Monitoring service has GRPC API that you can use to send data for analysis. Here is how it works:
1.Need to use compiled GRPC services. We provide libraries with precompiled services. If your language is not there, you need to compile GRPC yourself.
2.Create an ExecutionMetadata message that contains information of the model that was used to process a given request.
3.Create a PredictRequest message that contains the original request passed to the model for prediction.
4.If model responded successfully then create a PredictResponse message that contains inferenced output of the model. If there was an error, then instead of a PredictResponse message  you should prepare an error message.
5.Assemble an ExecutionInformation using the messages above.
6.Submit ExecutionInformation proto to Sonar for analysis. Use the RPC MonitoringService.Analyze method to calculate metrics.
Metrics retrieval
Once triggered, the MonitoringService.Analyze method does not return anything. To fetch calculated metrics from the model version, you have to make a GET request to the /monitoring/checks/all/<MODEL_VERSION_ID> endpoint.
A request must contain the following parameters:
limit: how many requests to fetch;
offset: which offset to make from the beginning.
An example request is shown below.
1
GET /monitoring/checks/all/1?limit=1&offset=0 HTTP/1.1
2
Accept: application/json
Copied!
Calculated metrics have a dynamic structure, which is dependant on the model interface.
Response object structure
A response object contains the original data submitted for prediction, the model's response, calculated metrics and other supplementary metadata. Every field produced by Hydrosphere is prefixed with _hs_ char.
_id: ID of the request, generated internally by Hydrosphere; 
_hs_request_id: ID of the request, specified by user;
_hs_model_name: Name of the model that processed a request;
_hs_model_incremental_version: Version of the model that processed a request; 
_hs_model_version_id: ID of the model version, which processed a request;
_hs_raw_checks: Raw checks calculated by Hydrosphere based on the training data;
_hs_metric_checks: Metrics produced by monitoring models;
_hs_latency: Latency, indicating how much it took to process a request;
_hs_error: Error message that occurred during request processing; 
_hs_score: The number of all successful checks divided by the number of all checks; 
_hs_overall_score: The amount of all successful metric values (not exceeding a specified threshold), divided by the amount of all metric values; 
_hs_timestamp: Timestamp in nanoseconds, when the object was generated; 
_hs_year: Year when the object was generated; 
_hs_month: Month when the object was generated;
_hs_day: Day when the object was generated;
Apart from the fields defined above, each object will have additional fields specific to the particular model version and its interface.
_hs_<field_name>_score: The number of all successful checks calculated for this specific field divided by the total number of all checks calculated for this specific field;  
<field_name>: The value of the field.
Raw checks object
_hs_raw_checks object contains all fields, for which checks have been calculated.
The example below shows, how the _hs_raw_checks_ object can be defined.
1
{
2
    "<field_name>": [
3
        ...
4
    ]
5
}
Copied!
Check object
check object declares the check, that has been calculated for the particular field. The following members will be present in the object.
check: Boolean value indicating, whether the check has been passed;
description: Description of the check that has been calculated;
threshold: Threshold of the check;  
value: Value of the field; 
metricSpecId: Metric specification ID. For each check object this value will be set to null. 
The example below shows, how the check object can be defined.
1
{
2
    "check": true,
3
    "description": "< max",
4
    "threshold": 0.9321230184950273,
5
    "value": 0.2081205412912307,
6
    "metricSpecId": null
7
}
Copied!
Metrics object
_hs_metrics_checks object contains all fields for which metrics have been calculated.
The example below shows how the _hs_metrics_checks object can be defined.
1
{
2
    "<field_name>": {
3
        ...
4
    }
5
}
Copied!
Metric object
metric object declares the metric, that has been calculated for the particular field. The following members will be present in the object.
check: Boolean value indicating, whether the metric has not been fired;
description: Name of the metric that has been calculated;
threshold: Threshold of the metric;  
value: Value of the metric; 
metricSpecId: Metric specification ID.
The example below shows how the metric object can be defined.
1
{
2
    "check": true, 
3
    "description": "string", 
4
    "threshold": 5.0,
5
    "value": 4.0,
6
    "metricSpecId": "bbb34c1f-13e1-4d1c-ad29-6e27c5461c37"
7
}
Copied!
The example below shows a fully composed server response.
1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
​
4
[
5
    {
6
        "_id": "5e1717f687a34b00086f58d8",
7
        "in": 0.2081205412912307,
8
        "out": 0.5551249161117925,
9
        "_hs_in_score": 1.0,
10
        "_hs_out_score": 1.0,
11
        "_hs_raw_checks": {
12
            "in": [
13
                {
14
                    "check": true,
15
                    "description": "< max",
16
                    "threshold": 0.9321230184950273,
17
                    "value": 0.2081205412912307,
18
                    "metricSpecId": null
19
                },
20
                {
21
                    "check": true,
22
                    "description": "> min",
23
                    "threshold": 0.0001208467391203,
24
                    "value": 0.2081205412912307,
25
                    "metricSpecId": null
26
                }
27
            ],
28
            "out": [
29
                {
30
                    "check": true,
31
                    "description": "< max",
32
                    "threshold": 0.9921230184950273,
33
                    "value": 0.5551249161117925,
34
                    "metricSpecId": null
35
                },
36
                {
37
                    "check": true,
38
                    "description": "> min",
39
                    "threshold": 0.0201208467391203,
40
                    "value": 0.5551249161117925,
41
                    "metricSpecId": null
42
                }
43
            ],
44
        },
45
        "_hs_metric_checks": {
46
            "string": {
47
                "check": true, 
48
                "description": "KNN", 
49
                "threshold": 5.0,
50
                "value": 4.0,
51
                "metricSpecId": "bbb34c1f-13e1-4d1c-ad29-6e27c5461c37"
52
            },
53
        },
54
        "_hs_latency": 0.7166033601366634,
55
        "_hs_error": "string",
56
        "_hs_score": 1.0,
57
        "_hs_overall_score": 1.0,
58
        "_hs_model_version_id": 1,
59
        "_hs_model_name": "external-model-example",
60
        "_hs_model_incremental_version": 1,
61
        "_hs_request_id": "395ae721-5e68-46e1-8ed6-74e360c614c1",
62
        "_hs_timestamp": 1578571766000,
63
        "_hs_year": 2020,
64
        "_hs_month": 1,
65
        "_hs_day": 9
66
    }
67
]
Copied!