[/api/stats
] Add documentation + small improvement (#79330)
Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Ahmad Bamieh <ahmadbamieh@gmail.com>
This commit is contained in:
parent
3ff90ce709
commit
43493bb0d9
|
@ -325,3 +325,8 @@ By storing these metrics and their counts as key-value pairs, we can add more me
|
|||
to worry about exceeding the 1000-field soft limit in Elasticsearch.
|
||||
|
||||
The only caveat is that it makes it harder to consume in Kibana when analysing each entry in the array separately. In the telemetry team we are working to find a solution to this.
|
||||
|
||||
# Routes registered by this plugin
|
||||
|
||||
- `/api/ui_metric/report`: Used by `ui_metrics` usage collector instances to report their usage data to the server
|
||||
- `/api/stats`: Get the metrics and usage ([details](./server/routes/stats/README.md))
|
||||
|
|
20
src/plugins/usage_collection/server/routes/stats/README.md
Normal file
20
src/plugins/usage_collection/server/routes/stats/README.md
Normal file
|
@ -0,0 +1,20 @@
|
|||
# `/api/stats`
|
||||
|
||||
This API returns the metrics for the Kibana server and usage stats. It allows the [Metricbeat Kibana module](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-module-kibana.html) to collect the [stats metricset](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-metricset-kibana-stats.html).
|
||||
|
||||
By default, it returns the simplest level of stats; consisting of the Kibana server's ops metrics, version, status, and basic config like the server name, host, port, and locale.
|
||||
|
||||
However, the information detailed above can be extended, with the combination of the following 3 query parameters:
|
||||
|
||||
| Query Parameter | Default value | Description |
|
||||
|:----------------|:-------------:|:------------|
|
||||
|`extended`|`false`|When `true`, it adds `clusterUuid` and `usage`. The latter contains the information reported by all the Usage Collectors registered in the Kibana server. It may throw `503 Stats not ready` if any of the collectors is not fully initialized yet.|
|
||||
|`legacy`|`false`|By default, when `extended=true`, the key names of the data in `usage` are transformed into API-friendlier `snake_case` format (i.e.: `clusterUuid` is transformed to `cluster_uuid`). When this parameter is `true`, the data is returned as-is.|
|
||||
|`exclude_usage`|`false`|When `true`, and `extended=true`, it will report `clusterUuid` but no `usage`.|
|
||||
|
||||
## Known use cases
|
||||
|
||||
Metricbeat Kibana' stats metricset ([code](https://github.com/elastic/beats/blob/master/metricbeat/module/kibana/stats/stats.go)) uses this API to collect the metrics (every 10s) and usage (only once every 24h), and then reports them to the Monitoring cluster. They call this API in 2 ways:
|
||||
|
||||
1. Metrics-only collection (every 10 seconds): `GET /api/stats?extended=true&legacy=true&exclude_usage=true`
|
||||
2. Metrics+usage (every 24 hours): `GET /api/stats?extended=true&legacy=true&exclude_usage=false`
|
20
src/plugins/usage_collection/server/routes/stats/index.ts
Normal file
20
src/plugins/usage_collection/server/routes/stats/index.ts
Normal file
|
@ -0,0 +1,20 @@
|
|||
/*
|
||||
* Licensed to Elasticsearch B.V. under one or more contributor
|
||||
* license agreements. See the NOTICE file distributed with
|
||||
* this work for additional information regarding copyright
|
||||
* ownership. Elasticsearch B.V. licenses this file to you under
|
||||
* the Apache License, Version 2.0 (the "License"); you may
|
||||
* not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing,
|
||||
* software distributed under the License is distributed on an
|
||||
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
* KIND, either express or implied. See the License for the
|
||||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
|
||||
export { registerStatsRoute } from './stats';
|
|
@ -30,8 +30,8 @@ import {
|
|||
MetricsServiceSetup,
|
||||
ServiceStatus,
|
||||
ServiceStatusLevels,
|
||||
} from '../../../../core/server';
|
||||
import { CollectorSet } from '../collector';
|
||||
} from '../../../../../core/server';
|
||||
import { CollectorSet } from '../../collector';
|
||||
|
||||
const STATS_NOT_READY_MESSAGE = i18n.translate('usageCollection.stats.notReadyMessage', {
|
||||
defaultMessage: 'Stats are not ready yet. Please try again later.',
|
||||
|
@ -101,10 +101,12 @@ export function registerStatsRoute({
|
|||
if (isExtended) {
|
||||
const callCluster = context.core.elasticsearch.legacy.client.callAsCurrentUser;
|
||||
const esClient = context.core.elasticsearch.client.asCurrentUser;
|
||||
const collectorsReady = await collectorSet.areAllCollectorsReady();
|
||||
|
||||
if (shouldGetUsage && !collectorsReady) {
|
||||
return res.customError({ statusCode: 503, body: { message: STATS_NOT_READY_MESSAGE } });
|
||||
if (shouldGetUsage) {
|
||||
const collectorsReady = await collectorSet.areAllCollectorsReady();
|
||||
if (!collectorsReady) {
|
||||
return res.customError({ statusCode: 503, body: { message: STATS_NOT_READY_MESSAGE } });
|
||||
}
|
||||
}
|
||||
|
||||
const usagePromise = shouldGetUsage ? getUsage(callCluster, esClient) : Promise.resolve({});
|
||||
|
@ -152,9 +154,8 @@ export function registerStatsRoute({
|
|||
}
|
||||
}
|
||||
|
||||
// Guranteed to resolve immediately due to replay effect on getOpsMetrics$
|
||||
// eslint-disable-next-line @typescript-eslint/naming-convention
|
||||
const { collected_at, ...lastMetrics } = await metrics
|
||||
// Guaranteed to resolve immediately due to replay effect on getOpsMetrics$
|
||||
const { collected_at: collectedAt, ...lastMetrics } = await metrics
|
||||
.getOpsMetrics$()
|
||||
.pipe(first())
|
||||
.toPromise();
|
||||
|
@ -173,7 +174,7 @@ export function registerStatsRoute({
|
|||
snapshot: SNAPSHOT_REGEX.test(config.kibanaVersion),
|
||||
status: ServiceStatusToLegacyState[overallStatus.level.toString()],
|
||||
},
|
||||
last_updated: collected_at.toISOString(),
|
||||
last_updated: collectedAt.toISOString(),
|
||||
collection_interval_in_millis: metrics.collectionInterval,
|
||||
});
|
||||
|
Loading…
Reference in a new issue