Update docs for new custom metrics endpoint functionality

Update docs for new custom metrics endpoint functionality

docs/reference/replicated-sdk-apis.md

@@ -99,6 +99,35 @@ Response:
 
 Send custom application metrics. For more information and examples see [Configuring Custom Metrics](/vendor/custom-metrics).
 
+### PATCH /app/custom-metrics
+
+Send partial custom application metrics for upserting. 
+
+```bash
+PATCH http://replicated:3000/api/v1/app/custom-metrics
+```
+Request: 
+
+```json
+{
+  "data": {
+    "numProjects": 20,
+  }
+}
+```
+
+Response: Status `200` OK
+
+### DELETE /app/custom-metrics/\{metric_name\}
+
+Delete an application custom metric. 
+
+```bash
+DELETE http://replicated:3000/api/v1/app/custom-metrics/numProjects
+```
+
+Response: Status `204` No Content 
+
 ### POST /app/instance-tags
 
 Programmatically set new instance tags or overwrite existing tags. Instance tags are key-value pairs, where the key and the value are strings.

docs/vendor/custom-metrics.md

@@ -28,45 +28,29 @@ The following diagram demonstrates how a custom `activeUsers` metric is sent to
 
 ## Requirements
 
-To support the collection of custom metrics in online and air gap environments, the Replicated SDK version 1.0.0-beta.12 or later must be running in the cluster alongside the application instance. For more information about the Replicated SDK, see [About the Replicated SDK](/vendor/replicated-sdk-overview).
+To support the collection of custom metrics in online and air gap environments, the Replicated SDK version 1.0.0-beta.12 or later must be running in the cluster alongside the application instance.
+
+The `PATCH` and `DELETE` methods described below are available in the Replicated SDK version 1.0.0-beta.23 or later.
+
+For more information about the Replicated SDK, see [About the Replicated SDK](/vendor/replicated-sdk-overview).
 
 If you have any customers running earlier versions of the SDK, Replicated recommends that you add logic to your application to gracefully handle a 404 from the in-cluster APIs.
 
 ## Limitations
 
 Custom metrics have the following limitations:
 
-* The label that is used to display metrics in the Vendor Portal cannot be customized. Metrics are sent to the Vendor Portal with the same name that is sent in the POST payload. The Vendor Portal then converts camel case to title case: for example, `activeUsers` is displayed as **Active Users**.
+* The label that is used to display metrics in the Vendor Portal cannot be customized. Metrics are sent to the Vendor Portal with the same name that is sent in the `POST` or `PATCH` payload. The Vendor Portal then converts camel case to title case: for example, `activeUsers` is displayed as **Active Users**.
 
 * The in-cluster APIs accept only JSON scalar values for metrics. Any requests containing nested objects or arrays are rejected.
 
-* The max payload size is 32k. 
-
-* Any payloads sent from an application component must contain all relevant metrics. It is not recommended to configure multiple components to send different sets of metrics because Replicated does not merge sets of metrics. The set of custom metrics present in the Instance Summary API and displayed in the Vendor Portal represent the most recent payload received from any application component.
-
-  For example, if a component of your application sends the following:
-
-  ```json
-  {
-    "numProjects": 5,
-    "activeUsers": 10,
-  }
-  ```
-
-  Then, the component later sends the following:
-
-  ```json
-  {
-    "activeUsers": 10,
-    "usingCustomReports": false
-  }
-  ```
-
-  The instance detail will show `Active Users: 10` and `Using Custom Reports: false`, which represents the most recent payload received. The previously-sent `numProjects` value is discarded from the instance summary and is available in the instance events payload.
+* When using the `POST` method any existing keys that are not included in the payload will be deleted. To create new metrics or update existing ones without sending the entire dataset, simply use the `PATCH` method.
 
 ## Configure Custom Metrics
 
-You can configure your application to POST a set of metrics as key value pairs to the API that is running in the cluster alongside the application instance.
+You can configure your application to `POST` or `PATCH` a set of metrics as key value pairs to the API that is running in the cluster alongside the application instance.  
+
+To remove an existing custom metric use the `DELETE` endpoint with the custom metric name.
 
 The Replicated SDK provides an in-cluster API custom metrics endpoint at `http://replicated:3000/api/v1/app/custom-metrics`.
 
@@ -85,6 +69,69 @@ POST http://replicated:3000/api/v1/app/custom-metrics
 }
 ```
 
+```bash
+PATCH http://replicated:3000/api/v1/app/custom-metrics
+```
+
+```json
+{
+  "data": {
+    "num_projects": 54,
+    "num_error": 2
+  }
+}
+```
+
+```bash
+DELETE http://replicated:3000/api/v1/app/custom-metrics/num_projects
+```
+
+### POST vs PATCH
+
+The `POST` method will always replace the existing data with the most recent payload received. Any existing keys not included in the most recent payload will still be accessible in the instance events API, but they will no longer appear in the instance summary.
+
+The `PATCH` method will accept partial updates or add new custom metrics if a key:value pair that does not currently exist is passed.
+
+In most cases, simply using the `PATCH` method is recommended.
+
+For example, if a component of your application sends the following via the `POST` method:
+
+```json
+{
+  "numProjects": 5,
+  "activeUsers": 10,
+}
+```
+
+Then, the component later sends the following also via the `POST` method:
+
+```json
+{
+  "activeUsers": 10,
+  "usingCustomReports": false
+}
+```
+
+The instance detail will show `Active Users: 10` and `Using Custom Reports: false`, which represents the most recent payload received. The previously-sent `numProjects` value is discarded from the instance summary and is available in the instance events payload.  In order to preseve `numProjects`from the initial payload and upsert `usingCustomReports` and `activeUsers` use the `PATCH` method instead of `POST` on subsequent calls to the endpoint.
+
+For example, if a component of your application initially sends the following via the `POST` method:
+
+```json
+{
+  "numProjects": 5,
+  "activeUsers": 10,
+}
+``` 
+
+Then, the component later sends the following also via the `PATCH` method:
+```json
+{
+  "usingCustomReports": false
+}
+```
+
+The instance detail will show `Num Projects: 5`, `Active Users: 10`, `Using Custom Reports: false`, which represents the merged and upserted payload.
+
 ### NodeJS Example
 
 The following example shows a NodeJS application that sends metrics on a weekly interval to the in-cluster API exposed by the SDK: