feat(specs): add OpenAPI spec for Monitoring API

.redocly.yaml

@@ -3,6 +3,7 @@ apis:
   analytics: specs/analytics/spec.yml
   ingestion: specs/ingestion/spec.yml
   insights: specs/insights/spec.yml
+  monitoring: specs/monitoring/spec.yml
   personalization: specs/personalization/spec.yml
   query-suggestions: specs/query-suggestions/spec.yml
   recommend: specs/recommend/spec.yml

config/openapitools.json

@@ -75,6 +75,13 @@
           "packageName": "ingestion"
         }
       },
+      "javascript-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/monitoring",
+        "additionalProperties": {
+          "packageVersion": "1.0.0-alpha.1",
+          "packageName": "monitoring"
+        }
+      },
       "java-search": {
         "output": "#{cwd}/clients/algoliasearch-client-java-2"
       },
@@ -96,6 +103,9 @@
       "java-query-suggestions": {
         "output": "#{cwd}/clients/algoliasearch-client-java-2"
       },
+      "java-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-java-2"
+      },
       "php-search": {
         "output": "#{cwd}/clients/algoliasearch-client-php"
       },
@@ -117,6 +127,9 @@
       "php-query-suggestions": {
         "output": "#{cwd}/clients/algoliasearch-client-php"
       },
+      "php-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-php"
+      },
       "go-analytics": {
         "output": "#{cwd}/clients/algoliasearch-client-go",
         "additionalProperties": {
@@ -165,6 +178,12 @@
           "packageName": "predict"
         }
       },
+      "go-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-go",
+        "additionalProperties": {
+          "packageName": "monitoring"
+        }
+      },
       "kotlin-search": {
         "output": "#{cwd}/clients/algoliasearch-client-kotlin"
       },
@@ -192,6 +211,9 @@
       "kotlin-ingestion": {
         "output": "#{cwd}/clients/algoliasearch-client-kotlin"
       },
+      "kotlin-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-kotlin"
+      },
       "dart-algoliasearch": {
         "output": "#{cwd}/clients/algoliasearch-client-dart/packages/algoliasearch",
         "additionalProperties": {
@@ -209,6 +231,12 @@
         "additionalProperties": {
           "packageVersion": "0.1.1+2"
         }
+      },
+      "dart-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-dart/packages/monitoring",
+        "additionalProperties": {
+          "packageVersion": "0.1.1+1"
+        }
       }
     }
   }

specs/monitoring/common/parameters.yml

@@ -0,0 +1,63 @@
+# path
+Clusters:
+  name: clusters
+  in: path
+  required: true
+  schema:
+    type: array
+    items:
+      type: string
+      title: Cluster names
+      description: List of clusters to test.
+      example:
+        - c1-de
+        - c2-de
+        - c3-de
+
+MetricInPath:
+  name: metric
+  in: path
+  required: true
+  schema:
+    $ref: '#/Metric'
+
+Metric:
+  type: string
+  description: |
+    Metric to report.
+
+    For more information about the individual metrics, see the response.
+    To include all metrics, use `*` as parameter.
+  enum:
+    - avg_build_time
+    - ssd_usage
+    - ram_search_usage
+    - ram_indexing_usage
+    - cpu_usage
+    - '*'
+  example: '*'
+
+PeriodInPath:
+  name: period
+  in: path
+  required: true
+  schema:
+    $ref: '#/Period'
+
+Period:
+  type: string
+  description: |
+    Period over which to aggregate the metrics:
+
+    - `minute`. Aggregate the last minute. 1 data point per 10 seconds.
+    - `hour`. Aggregate the last hour. 1 data point per minute.
+    - `day`. Aggregate the last day. 1 data point per 10 minutes.
+    - `week`. Aggregate the last week. 1 data point per hour.
+    - `month`. Aggregate the last month. 1 data point per day.
+  enum:
+    - minute
+    - hour
+    - day
+    - week
+    - month
+  example: week

specs/monitoring/common/responses/BadRequestResponse.yml

@@ -0,0 +1,13 @@
+description: Bad Request.
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+    examples:
+      BadRequest:
+        value:
+          reason: Unknown servers

specs/monitoring/common/responses/ForbiddenResponse.yml

@@ -0,0 +1,13 @@
+description: Forbidden
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+    examples:
+      Forbidden:
+        value:
+          reason: invalid credentials

specs/monitoring/common/responses/IncidentsResponse.yml

@@ -0,0 +1,26 @@
+description: OK
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        incidents:
+          type: object
+          additionalProperties:
+            x-additionalPropertiesName: incidents
+            $ref: '../schemas/Incidents.yml'
+    examples:
+      success:
+        value:
+          incidents:
+            m134-de:
+              - t: 1687441685000
+                v:
+                  title: 'Incident on cluster m134-de: Everything operating normally.'
+                  status: operational
+              - t: 1687441579000
+                v:
+                  title: >-
+                    Incident on cluster m134-de: We are encountering a major
+                    issue that impact all API calls.
+                  status: major_outage

specs/monitoring/common/responses/IndexingResponse.yml

@@ -0,0 +1,26 @@
+description: OK
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        metrics:
+          type: object
+          additionalProperties: false
+          properties:
+            indexing:
+              additionalProperties:
+                x-additionalPropertiesName: times
+                $ref: '../schemas/Time.yml'
+    examples:
+      Success:
+        value:
+          metrics:
+            indexing:
+              c16-de:
+                - t: 1688056200000
+                  v: 1562
+                - t: 1688056800000
+                  v: 1637
+                - t: 1688057400000
+                  v: 1754

specs/monitoring/common/responses/InfrastructureAPIUnauthorized.yml

@@ -0,0 +1,15 @@
+description: Unauthorized
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+    examples:
+      Unauthorized:
+        value:
+          reason: >-
+            The infrastructure usage API is only available on Enterprise plans.
+            Please contact enterprise@algolia.com for more detail.

specs/monitoring/common/responses/InfrastructureResponse.yml

@@ -0,0 +1,77 @@
+description: OK
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        metrics:
+          type: object
+          additionalProperties: false
+          properties:
+            cpu_usage:
+              type: object
+              description: CPU idleness in %.
+              additionalProperties:
+                x-additionalPropertiesName: probes
+                $ref: '../schemas/InfraProbes.yml'
+            ram_indexing_usage:
+              type: object
+              description: RAM usage for the indexing in MB.
+              additionalProperties:
+                x-additionalPropertiesName: probes
+                $ref: '../schemas/InfraProbes.yml'
+            ram_search_usage:
+              type: object
+              description: RAM usage for the search in MB.
+              additionalProperties:
+                x-additionalPropertiesName: probes
+                $ref: '../schemas/InfraProbes.yml'
+            ssd_usage:
+              type: object
+              description: >
+                Solid-state disk (SSD) usage expressed as % of RAM. 
+
+                0% means no SSD usage. A value of 50% indicates 32 GB SSD
+                usage for a machine with 64 RAM.
+              additionalProperties:
+                x-additionalPropertiesName: probes
+                $ref: '../schemas/InfraProbes.yml'
+            avg_build_time:
+              type: object
+              description: Average build time of the indices in seconds.
+              additionalProperties:
+                x-additionalPropertiesName: probes
+                $ref: '../schemas/InfraProbes.yml'
+    examples:
+      success:
+        value:
+          metrics:
+            cpu_usage:
+              s4-fr:
+                - t: 1455101280
+                  v: 46
+                - t: 1455101290
+                  v: 46
+                - t: 1455101300
+                  v: 46
+              c3-use-1:
+                - t: 1455101280
+                  v: 42
+                - t: 1455101290
+                  v: 42
+                - t: 1455101300
+                  v: 42
+                - t: 1455101310
+                  v: 37
+              c3-use-2:
+                - t: 1455101280
+                  v: 56
+                - t: 1455101290
+                  v: 56
+                - t: 1455101300
+                  v: 56
+                - t: 1455101310
+                  v: 56
+                - t: 1455101320
+                  v: 51

specs/monitoring/common/responses/InventoryResponse.yml

@@ -0,0 +1,35 @@
+description: OK
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        inventory:
+          type: array
+          items:
+            $ref: '../schemas/Server.yml'
+    examples:
+      Success:
+        value:
+          inventory:
+            - name: c16-de-3
+              region: de
+              is_slave: false
+              is_replica: false
+              cluster: c16-de
+              status: PRODUCTION
+              type: cluster
+            - name: c16-de-2
+              region: de
+              is_slave: false
+              is_replica: false
+              cluster: c16-de
+              status: PRODUCTION
+              type: cluster
+            - name: c16-de-1
+              region: de
+              is_slave: false
+              is_replica: false
+              cluster: c16-de
+              status: PRODUCTION
+              type: cluster

specs/monitoring/common/responses/LatencyResponse.yml

@@ -0,0 +1,26 @@
+description: OK
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        metrics:
+          type: object
+          additionalProperties: false
+          properties:
+            latency:
+              additionalProperties:
+                x-additionalPropertiesName: latencies
+                $ref: '../schemas/Time.yml'
+    examples:
+      Success:
+        value:
+          metrics:
+            latency:
+              c16-de:
+                - t: 1688056200000
+                  v: 64
+                - t: 1688056800000
+                  v: 59
+                - t: 1688057400000
+                  v: 55

specs/monitoring/common/responses/NotFoundResponse.yml

@@ -0,0 +1,8 @@
+description: Not Found.
+content:
+  text/plain:
+    schema:
+      type: string
+    examples:
+      NotFound:
+        value: Unknown cluster "test"