From 8765f6d47b63449b131cae17b5e4e83c1ee39183 Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Tue, 11 Jul 2023 12:07:22 +0200 Subject: [PATCH] feat(specs): add OpenAPI spec for Monitoring API (#1683) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: ClĂ©ment Vannicatte Co-authored-by: gazconroy --- .github/.cache_version | 2 +- .redocly.yaml | 1 + .../algoliasearch-client-javascript/yarn.lock | 13 ++++ config/openapitools.json | 22 ++++++ .../algolia/codegen/AlgoliaJavaGenerator.java | 7 ++ scripts/buildSpecs.ts | 11 ++- scripts/ci/utils.ts | 2 +- scripts/cts/generate.ts | 4 +- specs/monitoring/common/enums.yml | 64 +++++++++++++++ specs/monitoring/common/parameters.yml | 38 +++++++++ .../common/responses/BadRequestResponse.yml | 13 ++++ .../common/responses/ForbiddenResponse.yml | 13 ++++ .../common/responses/IncidentsResponse.yml | 27 +++++++ .../common/responses/IndexingResponse.yml | 27 +++++++ .../InfrastructureAPIUnauthorized.yml | 15 ++++ .../responses/InfrastructureResponse.yml | 78 +++++++++++++++++++ .../common/responses/InventoryResponse.yml | 36 +++++++++ .../common/responses/LatencyResponse.yml | 27 +++++++ .../common/responses/NotFoundResponse.yml | 8 ++ .../common/responses/ReachabilityResponse.yml | 16 ++++ .../common/responses/StatusResponse.yml | 17 ++++ .../common/responses/UnauthorizedResponse.yml | 10 +++ specs/monitoring/common/schemas/Incident.yml | 9 +++ specs/monitoring/common/schemas/Incidents.yml | 10 +++ .../monitoring/common/schemas/InfraProbes.yml | 4 + specs/monitoring/common/schemas/Probes.yml | 9 +++ .../common/schemas/ProbesMetric.yml | 9 +++ specs/monitoring/common/schemas/Server.yml | 31 ++++++++ specs/monitoring/common/schemas/Time.yml | 12 +++ specs/monitoring/common/schemas/Timestamp.yml | 3 + .../monitoring/paths/getClusterIncidents.yml | 16 ++++ specs/monitoring/paths/getClusterStatus.yml | 16 ++++ specs/monitoring/paths/getIncidents.yml | 12 +++ specs/monitoring/paths/getIndexingTime.yml | 14 ++++ specs/monitoring/paths/getInventory.yml | 23 ++++++ specs/monitoring/paths/getLatency.yml | 14 ++++ specs/monitoring/paths/getMetrics.yml | 14 ++++ specs/monitoring/paths/getReachability.yml | 14 ++++ specs/monitoring/paths/getStatus.yml | 23 ++++++ specs/monitoring/spec.yml | 72 +++++++++++++++++ tests/CTS/client/monitoring/parameters.json | 16 ++++ .../monitoring/getClusterIncidents.json | 12 +++ .../requests/monitoring/getClusterStatus.json | 12 +++ .../requests/monitoring/getIncidents.json | 10 +++ .../requests/monitoring/getIndexingTime.json | 12 +++ .../requests/monitoring/getInventory.json | 10 +++ .../requests/monitoring/getLatency.json | 12 +++ .../requests/monitoring/getMetrics.json | 13 ++++ .../requests/monitoring/getReachability.json | 12 +++ .../requests/monitoring/getStatus.json | 10 +++ 50 files changed, 870 insertions(+), 5 deletions(-) create mode 100644 specs/monitoring/common/enums.yml create mode 100644 specs/monitoring/common/parameters.yml create mode 100644 specs/monitoring/common/responses/BadRequestResponse.yml create mode 100644 specs/monitoring/common/responses/ForbiddenResponse.yml create mode 100644 specs/monitoring/common/responses/IncidentsResponse.yml create mode 100644 specs/monitoring/common/responses/IndexingResponse.yml create mode 100644 specs/monitoring/common/responses/InfrastructureAPIUnauthorized.yml create mode 100644 specs/monitoring/common/responses/InfrastructureResponse.yml create mode 100644 specs/monitoring/common/responses/InventoryResponse.yml create mode 100644 specs/monitoring/common/responses/LatencyResponse.yml create mode 100644 specs/monitoring/common/responses/NotFoundResponse.yml create mode 100644 specs/monitoring/common/responses/ReachabilityResponse.yml create mode 100644 specs/monitoring/common/responses/StatusResponse.yml create mode 100644 specs/monitoring/common/responses/UnauthorizedResponse.yml create mode 100644 specs/monitoring/common/schemas/Incident.yml create mode 100644 specs/monitoring/common/schemas/Incidents.yml create mode 100644 specs/monitoring/common/schemas/InfraProbes.yml create mode 100644 specs/monitoring/common/schemas/Probes.yml create mode 100644 specs/monitoring/common/schemas/ProbesMetric.yml create mode 100644 specs/monitoring/common/schemas/Server.yml create mode 100644 specs/monitoring/common/schemas/Time.yml create mode 100644 specs/monitoring/common/schemas/Timestamp.yml create mode 100644 specs/monitoring/paths/getClusterIncidents.yml create mode 100644 specs/monitoring/paths/getClusterStatus.yml create mode 100644 specs/monitoring/paths/getIncidents.yml create mode 100644 specs/monitoring/paths/getIndexingTime.yml create mode 100644 specs/monitoring/paths/getInventory.yml create mode 100644 specs/monitoring/paths/getLatency.yml create mode 100644 specs/monitoring/paths/getMetrics.yml create mode 100644 specs/monitoring/paths/getReachability.yml create mode 100644 specs/monitoring/paths/getStatus.yml create mode 100644 specs/monitoring/spec.yml create mode 100644 tests/CTS/client/monitoring/parameters.json create mode 100644 tests/CTS/methods/requests/monitoring/getClusterIncidents.json create mode 100644 tests/CTS/methods/requests/monitoring/getClusterStatus.json create mode 100644 tests/CTS/methods/requests/monitoring/getIncidents.json create mode 100644 tests/CTS/methods/requests/monitoring/getIndexingTime.json create mode 100644 tests/CTS/methods/requests/monitoring/getInventory.json create mode 100644 tests/CTS/methods/requests/monitoring/getLatency.json create mode 100644 tests/CTS/methods/requests/monitoring/getMetrics.json create mode 100644 tests/CTS/methods/requests/monitoring/getReachability.json create mode 100644 tests/CTS/methods/requests/monitoring/getStatus.json diff --git a/.github/.cache_version b/.github/.cache_version index bb951c884e..155069a391 100644 --- a/.github/.cache_version +++ b/.github/.cache_version @@ -1 +1 @@ -0.0.34 +0.0.35 diff --git a/.redocly.yaml b/.redocly.yaml index 6bb6c6e0c9..7cc7a5ebbd 100644 --- a/.redocly.yaml +++ b/.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 diff --git a/clients/algoliasearch-client-javascript/yarn.lock b/clients/algoliasearch-client-javascript/yarn.lock index db3d634a6f..79d066dcab 100644 --- a/clients/algoliasearch-client-javascript/yarn.lock +++ b/clients/algoliasearch-client-javascript/yarn.lock @@ -109,6 +109,19 @@ __metadata: languageName: unknown linkType: soft +"@algolia/monitoring@workspace:packages/monitoring": + version: 0.0.0-use.local + resolution: "@algolia/monitoring@workspace:packages/monitoring" + dependencies: + "@algolia/client-common": 5.0.0-alpha.73 + "@algolia/requester-browser-xhr": 5.0.0-alpha.73 + "@algolia/requester-node-http": 5.0.0-alpha.73 + "@types/node": 18.16.18 + rollup: 2.79.1 + typescript: 5.0.4 + languageName: unknown + linkType: soft + "@algolia/predict@workspace:packages/predict": version: 0.0.0-use.local resolution: "@algolia/predict@workspace:packages/predict" diff --git a/config/openapitools.json b/config/openapitools.json index 009dd12123..c2824b365e 100644 --- a/config/openapitools.json +++ b/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": { diff --git a/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java b/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java index 4dfabdce1f..9e041de40b 100644 --- a/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java +++ b/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java @@ -125,6 +125,13 @@ public String toEnumVarName(String value, String datatype) { return super.toEnumVarName(value, datatype); } + // In some cases, the API might accept characters instead of the textual notation, we will + // replace it internally so that it doesn't output the character itself. + switch (value) { + case "*": + return "ALL"; + } + if (!value.matches("[A-Z0-9_]+")) { // convert camelCase77String to CAMEL_CASE_77_STRING return value.replaceAll("-", "_").replaceAll("(.+?)([A-Z]|[0-9])", "$1_$2").toUpperCase(Locale.ROOT); diff --git a/scripts/buildSpecs.ts b/scripts/buildSpecs.ts index c946dd1a14..2aee01f9a4 100644 --- a/scripts/buildSpecs.ts +++ b/scripts/buildSpecs.ts @@ -70,8 +70,15 @@ async function transformBundle({ // Checks that specified tags are well defined at root level for (const tag of docMethod.tags) { - if (tag === clientName || (alias && tag === alias)) { - return; + if (tag === clientName) { + throw new Error( + `Tag name "${tag}" must be different from client name ${clientName}` + ); + } + if (alias && tag === alias) { + throw new Error( + `Tag name "${tag} must be different from alias ${alias}` + ); } const tagExists = tagsDefinitions diff --git a/scripts/ci/utils.ts b/scripts/ci/utils.ts index 4ce6402993..05fd92a0c4 100644 --- a/scripts/ci/utils.ts +++ b/scripts/ci/utils.ts @@ -31,7 +31,7 @@ export async function getNbGitDiff({ return parseInt( ( await run( - `git diff --shortstat ${branch}${checkHead} -- ${path} | wc -l`, + `git add -N . && git diff --shortstat ${branch}${checkHead} -- ${path} | wc -l`, { cwd } ) ).trim(), diff --git a/scripts/cts/generate.ts b/scripts/cts/generate.ts index 6326596a42..2f4a6b98d9 100644 --- a/scripts/cts/generate.ts +++ b/scripts/cts/generate.ts @@ -39,7 +39,9 @@ export async function ctsGenerateMany(generators: Generator[]): Promise { } if (lang === 'javascript') { - await run('yarn install', { cwd: 'tests/output/javascript' }); + await run('YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install', { + cwd: 'tests/output/javascript', + }); } await formatter(lang, toAbsolutePath(`tests/output/${lang}`)); diff --git a/specs/monitoring/common/enums.yml b/specs/monitoring/common/enums.yml new file mode 100644 index 0000000000..2c9f1625ef --- /dev/null +++ b/specs/monitoring/common/enums.yml @@ -0,0 +1,64 @@ +Metric: + type: string + enum: + - avg_build_time + - ssd_usage + - ram_search_usage + - ram_indexing_usage + - cpu_usage + - '*' + example: '*' + +Period: + type: string + enum: + - minute + - hour + - day + - week + - month + example: week + +Region: + title: region + type: string + description: The region where the cluster is located. + enum: + - au + - br + - ca + - de + - eu + - hk + - in + - jp + - sg + - uae + - uk + - usc + - use + - usw + - za + example: de + +Status: + title: status + type: string + description: Status of the cluster. + enum: + - operational + - degraded_performance + - partial_outage + - major_outage + +ServerStatus: + title: status + type: string + enum: + - PRODUCTION + +Type: + title: type + type: string + enum: + - cluster diff --git a/specs/monitoring/common/parameters.yml b/specs/monitoring/common/parameters.yml new file mode 100644 index 0000000000..779955a297 --- /dev/null +++ b/specs/monitoring/common/parameters.yml @@ -0,0 +1,38 @@ +# path +Clusters: + name: clusters + in: path + required: true + description: Subset of clusters, separated by comma. + schema: + # The `correct` (?) schema should be type array/items string, + # But the SDK generator expects a string, because it can't replace a list of strings in the URL. + type: string + example: 'c1-de,c2-de,c3-de' + +MetricInPath: + name: metric + in: path + required: true + description: | + Metric to report. + + For more information about the individual metrics, see the response. + To include all metrics, use `*` as the parameter. + schema: + $ref: './enums.yml#/Metric' + +PeriodInPath: + name: period + in: path + required: true + 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. + schema: + $ref: './enums.yml#/Period' diff --git a/specs/monitoring/common/responses/BadRequestResponse.yml b/specs/monitoring/common/responses/BadRequestResponse.yml new file mode 100644 index 0000000000..998eb165f6 --- /dev/null +++ b/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 diff --git a/specs/monitoring/common/responses/ForbiddenResponse.yml b/specs/monitoring/common/responses/ForbiddenResponse.yml new file mode 100644 index 0000000000..9ac55d8d32 --- /dev/null +++ b/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 diff --git a/specs/monitoring/common/responses/IncidentsResponse.yml b/specs/monitoring/common/responses/IncidentsResponse.yml new file mode 100644 index 0000000000..80987573a8 --- /dev/null +++ b/specs/monitoring/common/responses/IncidentsResponse.yml @@ -0,0 +1,27 @@ +description: OK +content: + application/json: + schema: + title: IncidentsResponse + type: object + properties: + incidents: + type: object + additionalProperties: + x-additionalPropertiesName: cluster + $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 diff --git a/specs/monitoring/common/responses/IndexingResponse.yml b/specs/monitoring/common/responses/IndexingResponse.yml new file mode 100644 index 0000000000..25cc9d2721 --- /dev/null +++ b/specs/monitoring/common/responses/IndexingResponse.yml @@ -0,0 +1,27 @@ +description: OK +content: + application/json: + schema: + title: IndexingTimeResponse + 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 diff --git a/specs/monitoring/common/responses/InfrastructureAPIUnauthorized.yml b/specs/monitoring/common/responses/InfrastructureAPIUnauthorized.yml new file mode 100644 index 0000000000..8480c8316e --- /dev/null +++ b/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. diff --git a/specs/monitoring/common/responses/InfrastructureResponse.yml b/specs/monitoring/common/responses/InfrastructureResponse.yml new file mode 100644 index 0000000000..ccfdfb80a7 --- /dev/null +++ b/specs/monitoring/common/responses/InfrastructureResponse.yml @@ -0,0 +1,78 @@ +description: OK +content: + application/json: + schema: + title: InfrastructureResponse + 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 used for indexing in MB. + additionalProperties: + x-additionalPropertiesName: probes + $ref: '../schemas/InfraProbes.yml' + ram_search_usage: + type: object + description: RAM used for 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 diff --git a/specs/monitoring/common/responses/InventoryResponse.yml b/specs/monitoring/common/responses/InventoryResponse.yml new file mode 100644 index 0000000000..67f9543a05 --- /dev/null +++ b/specs/monitoring/common/responses/InventoryResponse.yml @@ -0,0 +1,36 @@ +description: OK +content: + application/json: + schema: + title: InventoryResponse + 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 diff --git a/specs/monitoring/common/responses/LatencyResponse.yml b/specs/monitoring/common/responses/LatencyResponse.yml new file mode 100644 index 0000000000..fd38ab1f39 --- /dev/null +++ b/specs/monitoring/common/responses/LatencyResponse.yml @@ -0,0 +1,27 @@ +description: OK +content: + application/json: + schema: + title: LatencyResponse + 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 diff --git a/specs/monitoring/common/responses/NotFoundResponse.yml b/specs/monitoring/common/responses/NotFoundResponse.yml new file mode 100644 index 0000000000..31caabdd42 --- /dev/null +++ b/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" diff --git a/specs/monitoring/common/responses/ReachabilityResponse.yml b/specs/monitoring/common/responses/ReachabilityResponse.yml new file mode 100644 index 0000000000..bdb1c0cb9f --- /dev/null +++ b/specs/monitoring/common/responses/ReachabilityResponse.yml @@ -0,0 +1,16 @@ +description: OK +content: + application/json: + schema: + title: ReachabilityResponse + type: object + additionalProperties: + x-additionalPropertiesName: Server + $ref: '../schemas/Probes.yml' + examples: + Success: + value: + c16-de: + sdn-probe-frankfurt: false + monitoring-2: false + sdn-probe-awswest1: false diff --git a/specs/monitoring/common/responses/StatusResponse.yml b/specs/monitoring/common/responses/StatusResponse.yml new file mode 100644 index 0000000000..735d10af24 --- /dev/null +++ b/specs/monitoring/common/responses/StatusResponse.yml @@ -0,0 +1,17 @@ +description: OK +content: + application/json: + schema: + title: StatusResponse + type: object + properties: + status: + type: object + additionalProperties: + x-additionalPropertiesName: status + $ref: '../enums.yml#/Status' + examples: + Success: + value: + status: + c16-de: operational diff --git a/specs/monitoring/common/responses/UnauthorizedResponse.yml b/specs/monitoring/common/responses/UnauthorizedResponse.yml new file mode 100644 index 0000000000..751d9d350d --- /dev/null +++ b/specs/monitoring/common/responses/UnauthorizedResponse.yml @@ -0,0 +1,10 @@ +description: Unauthorized +content: + text/plain: + schema: + type: string + examples: + Unauthorized: + summary: Invalid credentials. + description: Make sure to use the Monitoring API key if you authenticate your API requests. + value: Invalid credentials diff --git a/specs/monitoring/common/schemas/Incident.yml b/specs/monitoring/common/schemas/Incident.yml new file mode 100644 index 0000000000..4418e93494 --- /dev/null +++ b/specs/monitoring/common/schemas/Incident.yml @@ -0,0 +1,9 @@ +title: incident +description: Incident details. +type: object +properties: + title: + type: string + description: Description of the incident. + status: + $ref: '../enums.yml#/Status' diff --git a/specs/monitoring/common/schemas/Incidents.yml b/specs/monitoring/common/schemas/Incidents.yml new file mode 100644 index 0000000000..7d461e1787 --- /dev/null +++ b/specs/monitoring/common/schemas/Incidents.yml @@ -0,0 +1,10 @@ +title: incidents +description: Key-value pairs with the cluster names as keys and the list of incidents reported for this cluster as values. +type: array +items: + type: object + properties: + t: + $ref: './Timestamp.yml' + v: + $ref: './Incident.yml' diff --git a/specs/monitoring/common/schemas/InfraProbes.yml b/specs/monitoring/common/schemas/InfraProbes.yml new file mode 100644 index 0000000000..ced69e45b9 --- /dev/null +++ b/specs/monitoring/common/schemas/InfraProbes.yml @@ -0,0 +1,4 @@ +title: probes +type: array +items: + $ref: './ProbesMetric.yml' diff --git a/specs/monitoring/common/schemas/Probes.yml b/specs/monitoring/common/schemas/Probes.yml new file mode 100644 index 0000000000..b01d3b37d6 --- /dev/null +++ b/specs/monitoring/common/schemas/Probes.yml @@ -0,0 +1,9 @@ +title: probes +description: Probes and their response. +type: object +additionalProperties: + x-additionalPropertiesName: probe + type: boolean + description: >- + Key-value pair with the probe name as the key and the reachability status as + the value. diff --git a/specs/monitoring/common/schemas/ProbesMetric.yml b/specs/monitoring/common/schemas/ProbesMetric.yml new file mode 100644 index 0000000000..2583f24ba7 --- /dev/null +++ b/specs/monitoring/common/schemas/ProbesMetric.yml @@ -0,0 +1,9 @@ +title: metric +type: object +additionalProperties: false +properties: + t: + $ref: './Timestamp.yml' + v: + type: integer + description: Value of the metric. diff --git a/specs/monitoring/common/schemas/Server.yml b/specs/monitoring/common/schemas/Server.yml new file mode 100644 index 0000000000..55f76571f1 --- /dev/null +++ b/specs/monitoring/common/schemas/Server.yml @@ -0,0 +1,31 @@ +title: server +additionalProperties: false +properties: + name: + type: string + description: Server name. + example: c16-de-1 + region: + $ref: '../enums.yml#/Region' + is_slave: + type: boolean + default: false + deprecated: true + description: | + Included to support legacy applications. + Do not rely on this attribute being present in the response. + Use `is_replica` instead. + example: false + is_replica: + type: boolean + default: false + description: Indicates whether this server is a replica of another server. + example: false + cluster: + type: string + description: Name of the cluster to which this server belongs. + example: c16-de + status: + $ref: '../enums.yml#/ServerStatus' + type: + $ref: '../enums.yml#/Type' diff --git a/specs/monitoring/common/schemas/Time.yml b/specs/monitoring/common/schemas/Time.yml new file mode 100644 index 0000000000..cc6def364d --- /dev/null +++ b/specs/monitoring/common/schemas/Time.yml @@ -0,0 +1,12 @@ +title: time +description: Time measured by a probe. +type: array +items: + type: object + additionalProperties: false + properties: + t: + $ref: './Timestamp.yml' + v: + type: integer + description: Time in ms. diff --git a/specs/monitoring/common/schemas/Timestamp.yml b/specs/monitoring/common/schemas/Timestamp.yml new file mode 100644 index 0000000000..6580f60ea8 --- /dev/null +++ b/specs/monitoring/common/schemas/Timestamp.yml @@ -0,0 +1,3 @@ +type: integer +format: int64 +description: Timestamp in [Unix epoch time](https://wikipedia.org/wiki/Unix_time) in milliseconds. diff --git a/specs/monitoring/paths/getClusterIncidents.yml b/specs/monitoring/paths/getClusterIncidents.yml new file mode 100644 index 0000000000..2e2f1a52e3 --- /dev/null +++ b/specs/monitoring/paths/getClusterIncidents.yml @@ -0,0 +1,16 @@ +get: + summary: List incidents for selected clusters. + description: List known incidents for selected clusters. + operationId: getClusterIncidents + tags: + - incidents + security: [] + parameters: + - $ref: '../common/parameters.yml#/Clusters' + responses: + '200': + $ref: '../common/responses/IncidentsResponse.yml' + '401': + $ref: '../common/responses/UnauthorizedResponse.yml' + '404': + $ref: '../common/responses/NotFoundResponse.yml' diff --git a/specs/monitoring/paths/getClusterStatus.yml b/specs/monitoring/paths/getClusterStatus.yml new file mode 100644 index 0000000000..e857bf9605 --- /dev/null +++ b/specs/monitoring/paths/getClusterStatus.yml @@ -0,0 +1,16 @@ +get: + summary: List statuses of selected clusters. + description: Report whether a cluster is operational. + operationId: getClusterStatus + tags: + - status + security: [] + parameters: + - $ref: '../common/parameters.yml#/Clusters' + responses: + '200': + $ref: '../common/responses/StatusResponse.yml' + '401': + $ref: '../common/responses/UnauthorizedResponse.yml' + '404': + $ref: '../common/responses/NotFoundResponse.yml' diff --git a/specs/monitoring/paths/getIncidents.yml b/specs/monitoring/paths/getIncidents.yml new file mode 100644 index 0000000000..b19d371a62 --- /dev/null +++ b/specs/monitoring/paths/getIncidents.yml @@ -0,0 +1,12 @@ +get: + summary: List incidents. + description: List known incidents for all clusters. + operationId: getIncidents + security: [] + tags: + - incidents + responses: + '200': + $ref: '../common/responses/IncidentsResponse.yml' + '401': + $ref: '../common/responses/UnauthorizedResponse.yml' diff --git a/specs/monitoring/paths/getIndexingTime.yml b/specs/monitoring/paths/getIndexingTime.yml new file mode 100644 index 0000000000..4799dc4195 --- /dev/null +++ b/specs/monitoring/paths/getIndexingTime.yml @@ -0,0 +1,14 @@ +get: + summary: Get indexing times. + description: List the average times for indexing operations for selected clusters. + operationId: getIndexingTime + security: [] + tags: + - monitoring-tag + parameters: + - $ref: '../common/parameters.yml#/Clusters' + responses: + '200': + $ref: '../common/responses/IndexingResponse.yml' + '400': + $ref: '../common/responses/BadRequestResponse.yml' diff --git a/specs/monitoring/paths/getInventory.yml b/specs/monitoring/paths/getInventory.yml new file mode 100644 index 0000000000..0a9bcff32e --- /dev/null +++ b/specs/monitoring/paths/getInventory.yml @@ -0,0 +1,23 @@ +get: + summary: List servers. + operationId: getInventory + security: + - appId: [] + - apiKey: [] + description: | + List the servers belonging to clusters. + + The response depends on whether you authenticate your API request: + + - With authentication, the response lists the servers assigned to your + Algolia application's cluster. + + - Without authentication, the response lists the servers for all Algolia + clusters. + tags: + - monitoring-tag + responses: + '200': + $ref: '../common/responses/InventoryResponse.yml' + '403': + $ref: '../common/responses/ForbiddenResponse.yml' diff --git a/specs/monitoring/paths/getLatency.yml b/specs/monitoring/paths/getLatency.yml new file mode 100644 index 0000000000..0f309d9e15 --- /dev/null +++ b/specs/monitoring/paths/getLatency.yml @@ -0,0 +1,14 @@ +get: + summary: Get search latency times. + description: List the average latency for search requests for selected clusters. + operationId: getLatency + security: [] + tags: + - monitoring-tag + parameters: + - $ref: '../common/parameters.yml#/Clusters' + responses: + '200': + $ref: '../common/responses/LatencyResponse.yml' + '400': + $ref: '../common/responses/BadRequestResponse.yml' diff --git a/specs/monitoring/paths/getMetrics.yml b/specs/monitoring/paths/getMetrics.yml new file mode 100644 index 0000000000..dec246abe5 --- /dev/null +++ b/specs/monitoring/paths/getMetrics.yml @@ -0,0 +1,14 @@ +get: + summary: Get metrics for a given period. + description: Report the aggregate value of a metric for a selected period of time. + operationId: getMetrics + tags: + - infrastructure + parameters: + - $ref: '../common/parameters.yml#/MetricInPath' + - $ref: '../common/parameters.yml#/PeriodInPath' + responses: + '200': + $ref: '../common/responses/InfrastructureResponse.yml' + '401': + $ref: '../common/responses/InfrastructureAPIUnauthorized.yml' diff --git a/specs/monitoring/paths/getReachability.yml b/specs/monitoring/paths/getReachability.yml new file mode 100644 index 0000000000..96a5c28ac6 --- /dev/null +++ b/specs/monitoring/paths/getReachability.yml @@ -0,0 +1,14 @@ +get: + summary: Test the reachability of clusters. + description: Test whether clusters are reachable or not. + operationId: getReachability + security: [] + tags: + - monitoring-tag + parameters: + - $ref: '../common/parameters.yml#/Clusters' + responses: + '200': + $ref: '../common/responses/ReachabilityResponse.yml' + '400': + $ref: '../common/responses/BadRequestResponse.yml' diff --git a/specs/monitoring/paths/getStatus.yml b/specs/monitoring/paths/getStatus.yml new file mode 100644 index 0000000000..2f136d9019 --- /dev/null +++ b/specs/monitoring/paths/getStatus.yml @@ -0,0 +1,23 @@ +get: + operationId: getStatus + summary: List cluster statuses. + tags: + - status + security: + - appId: [] + - apiKey: [] + description: | + Report whether clusters are operational. + + The response depends on whether you authenticate your API request. + + - With authentication, the response includes the status of the cluster + assigned to your Algolia application. + + - Without authentication, the response lists the statuses of all public + Algolia clusters. + responses: + '200': + $ref: '../common/responses/StatusResponse.yml' + '401': + $ref: '../common/responses/UnauthorizedResponse.yml' diff --git a/specs/monitoring/spec.yml b/specs/monitoring/spec.yml new file mode 100644 index 0000000000..9eca3d7887 --- /dev/null +++ b/specs/monitoring/spec.yml @@ -0,0 +1,72 @@ +openapi: 3.0.2 +info: + title: Algolia Monitoring API + description: | + The Monitoring API lets you check the status and performance of your Algolia + infrastructure. + + > **Note**: The Monitoring API is available on [Premium + plans](https://www.algolia.com/pricing/) and plans including the Enterprise + add-on. + version: 1.0.0 +servers: + - url: https://status.algolia.com +components: + securitySchemes: + appId: + type: apiKey + in: header + name: X-Algolia-Application-Id + description: Your Algolia application ID. + apiKey: + type: apiKey + in: header + name: X-Algolia-API-Key + description: Your Algolia API key. Make sure to use your Monitoring API key. +tags: + - name: incidents + description: List the known incidents. + x-displayName: Incidents + - name: infrastructure + description: Return information about the Algolia infrastructure used by your application. + x-displayName: Infrastructure + - name: monitoring-tag + description: Report search and indexing times for your clusters, and get a list of servers. + x-displayName: Monitoring + - name: status + description: | + Report the status of your clusters. + + At Algolia, your application is hosted on a [cluster with three + servers](https://www.algolia.com/doc/guides/scaling/servers-clusters/). + + Cluster names follow a pattern: `c{[0-9]+}-{region}` where `{region}` is + one of the supported Algolia regions. + + Server names follow the pattern: `{cluster-name}-{1|2|3}`. + x-displayName: Status +paths: + # ###################### + # ### Custom request ### + # ###################### + /1{path}: + $ref: '../common/paths/customRequest.yml' + + /1/status: + $ref: 'paths/getStatus.yml' + /1/status/{clusters}: + $ref: 'paths/getClusterStatus.yml' + /1/incidents: + $ref: 'paths/getIncidents.yml' + /1/incidents/{clusters}: + $ref: 'paths/getClusterIncidents.yml' + /1/inventory/servers: + $ref: 'paths/getInventory.yml' + /1/latency/{clusters}: + $ref: 'paths/getLatency.yml' + /1/indexing/{clusters}: + $ref: 'paths/getIndexingTime.yml' + /1/reachability/{clusters}/probes: + $ref: 'paths/getReachability.yml' + /1/infrastructure/{metric}/period/{period}: + $ref: 'paths/getMetrics.yml' diff --git a/tests/CTS/client/monitoring/parameters.json b/tests/CTS/client/monitoring/parameters.json new file mode 100644 index 0000000000..b04d866474 --- /dev/null +++ b/tests/CTS/client/monitoring/parameters.json @@ -0,0 +1,16 @@ +[ + { + "testName": "uses the correct region", + "autoCreateClient": false, + "steps": [ + { + "type": "createClient", + "parameters": { + "appId": "my-app-id", + "apiKey": "my-api-key" + }, + "expected": {} + } + ] + } +] diff --git a/tests/CTS/methods/requests/monitoring/getClusterIncidents.json b/tests/CTS/methods/requests/monitoring/getClusterIncidents.json new file mode 100644 index 0000000000..930f2a3aea --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getClusterIncidents.json @@ -0,0 +1,12 @@ +[ + { + "testName": "getClusterIncidents", + "parameters": { + "clusters": "c1-de" + }, + "request": { + "path": "/1/incidents/c1-de", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getClusterStatus.json b/tests/CTS/methods/requests/monitoring/getClusterStatus.json new file mode 100644 index 0000000000..4985489f0b --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getClusterStatus.json @@ -0,0 +1,12 @@ +[ + { + "testName": "getClusterStatus", + "parameters": { + "clusters": "c1-de" + }, + "request": { + "path": "/1/status/c1-de", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getIncidents.json b/tests/CTS/methods/requests/monitoring/getIncidents.json new file mode 100644 index 0000000000..f03dca62cd --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getIncidents.json @@ -0,0 +1,10 @@ +[ + { + "testName": "getIncidents", + "parameters": {}, + "request": { + "path": "/1/incidents", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getIndexingTime.json b/tests/CTS/methods/requests/monitoring/getIndexingTime.json new file mode 100644 index 0000000000..7c17c45909 --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getIndexingTime.json @@ -0,0 +1,12 @@ +[ + { + "testName": "getIndexingTime", + "parameters": { + "clusters": "c1-de" + }, + "request": { + "path": "/1/indexing/c1-de", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getInventory.json b/tests/CTS/methods/requests/monitoring/getInventory.json new file mode 100644 index 0000000000..43e23f7b8d --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getInventory.json @@ -0,0 +1,10 @@ +[ + { + "testName": "getInventory", + "parameters": {}, + "request": { + "path": "/1/inventory/servers", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getLatency.json b/tests/CTS/methods/requests/monitoring/getLatency.json new file mode 100644 index 0000000000..61e389b47b --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getLatency.json @@ -0,0 +1,12 @@ +[ + { + "testName": "getLatency", + "parameters": { + "clusters": "c1-de" + }, + "request": { + "path": "/1/latency/c1-de", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getMetrics.json b/tests/CTS/methods/requests/monitoring/getMetrics.json new file mode 100644 index 0000000000..f9220d5947 --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getMetrics.json @@ -0,0 +1,13 @@ +[ + { + "testName": "getMetrics", + "parameters": { + "metric": "avg_build_time", + "period": "minute" + }, + "request": { + "path": "/1/infrastructure/avg_build_time/period/minute", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getReachability.json b/tests/CTS/methods/requests/monitoring/getReachability.json new file mode 100644 index 0000000000..084cde89a5 --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getReachability.json @@ -0,0 +1,12 @@ +[ + { + "testName": "getReachability", + "parameters": { + "clusters": "c1-de" + }, + "request": { + "path": "/1/reachability/c1-de/probes", + "method": "GET" + } + } +] diff --git a/tests/CTS/methods/requests/monitoring/getStatus.json b/tests/CTS/methods/requests/monitoring/getStatus.json new file mode 100644 index 0000000000..96d66d6810 --- /dev/null +++ b/tests/CTS/methods/requests/monitoring/getStatus.json @@ -0,0 +1,10 @@ +[ + { + "testName": "getStatus", + "parameters": {}, + "request": { + "path": "/1/status", + "method": "GET" + } + } +]