phanle1010/binoculars

binoculars's Issues

End to End Flow

Modify the users' application code

1. Users' application implements logic to get the users' consent to collect opt-in telemetry.
2. If the users' application is using Golang, they can import our provide client package. The client package is safe for calling concurrently by multiple goroutines. It is also safe to call start() or stop() on the same client object multiple times. Calling start() on already started client or calling stop() on already stopped() client are no-op. Application can call start() and stop() the Binoculars client when users' consent is changed.
3. User's application implements the MetricHandler interface and passes it into the Binoculars client so the Binoculars client knows how to gather metrics and process the response. See example package for an example
4. The Binoculars client starts sending updated metrics to the Binoculars server in the following JSON format:

   [   
       {
           "name": "storage_capacity",
           "tags": {"instance_uuid": "123e4567-e89b-12d3-a456-426614174000"},
           "fields": {"value": 1000000000000}
       },
       {
           "name": "enabled_feature",
           "tags": {"instance_uuid": "123e4567-e89b-12d3-a456-426614174000"},
           "fields": {"node_selector": 1, "data_locality": 1}
       }
   ]
   

5. The Binoculars client will receive a response from the Binoculars server that contains the time duration that the client should send the next metric update to the server, RequestIntervalInMinutes.

Binoculars server

1. Binoculars server creates a database with the name APPLICATION_NAME_binoculars in the InfluxDB instance to store all related telemetrics for the users' application.

2. Parse the metric request
   The Binoculars server receive the metrics in the following JSON format

   [   
       {
           "name": "storage_capacity",
           "tags": {"instance_uuid": "123e4567-e89b-12d3-a456-426614174000"},
           "fields": {"value": 1000000000000}
       },
       {
           "name": "enabled_feature",
           "tags": {"instance_uuid": "123e4567-e89b-12d3-a456-426614174000"},
           "fields": {"node_selector": 1, "data_locality": 1}
       }
   ]
   

   The server parses the metrics and creates a point for each metric in the JSON request's body as follows:

   • name is the name of measurement (table) of the point in the InfluxDB
   • tags are tags of the point in the InfluxDB
   • fields are fields of the point in the InfluxDB

   The server then stores the points to the InfluxDB. With the above example request, the server stores 2 points in the InfluxDB:

   > select * from  storage_capacity
   name: storage_capacity
   time                instance_uuid                        value
   ----                -------------                        -----
   1622017251731519223 123e4567-e89b-12d3-a456-426614174000 1000000000000
   
   > select * from enabled_feature
   name: enabled_feature
   time                auto_salvage data_locality instance_uuid
   ----                ------------ ------------- -------------
   1622017251731530324 1            1             123e4567-e89b-12d3-a456-426614174000
   

   The server returns the time duration that it wants the client to send the next metric update, RequestIntervalInMinutes, in the response's body.

InfluxDB queries

Now that we have the raw data in the storage_capacity and enabled_feature measurements, it is time for the application developers to use their InfluxDB expertise to get useful information out of the raw data.

Let's take a look at the enabled_feature metric. The goal of this metric is so that the application developers can know which features of the application are most used and which features are not used so the developers can plan their development plan. In this example, assume that the query-period is 1 hour so the Binoculars server is getting the updated metric from the client every hour.

First, create a continuous query that counts the number of each enabled feature every 1h

CREATE CONTINUOUS QUERY cq_enabled_feature_downsampling ON <APPLICATION_NAME>_binoculars 
BEGIN 
SELECT sum(*) INTO enabled_feature_downsampling 
FROM enabled_feature 
GROUP BY time(1h) 
END

The following measurement is created in the InfluxDB (note that I changed the grouping time to 5 mins to save testing time)

> select * from enabled_feature_downsampling
name: enabled_feature_downsampling
time                sum_auto_salvage sum_data_locality sum_node_selector sum_toleration
----                ---------------- ----------------- ----------------- --------------
1621971600000000000                  1                                   
1621971900000000000 3                4                 3                 1
1621973400000000000 2                6                                   4
1621978500000000000 4                8                                   3
1621978800000000000 6                9                                   8
1621979100000000000 6                6                                   6
1621979400000000000 11               14                                  5

Grafana panels

1. Create a data source that points to the database <APPLICATION_NAME>_binoculars in the InfluxDB instance.
2. Continue on the enabled_feature metric from the previous section. In Grafana, the application developers can use this query to create a panel from the enabled_feature_downsampling (Note that I actually group by 5m to save testing time):

   SELECT last(*) FROM "enabled_feature_downsampling" WHERE $timeFilter GROUP BY time(1h) fill(null)