1
0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-22 19:07:54 +01:00

docs: Metrics tag openapi docs (#3572)

I've copied most of the descriptions from what we did for batch metrics
under the Edge tag, however there are a couple of top level descriptions
that are "fine" but I'm definitely open to suggestions.

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
This commit is contained in:
Christopher Kolstad 2023-04-26 12:10:57 +02:00 committed by GitHub
parent 3bb09c5ce4
commit 1b248a03e9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 693 additions and 48 deletions

View File

@ -6,7 +6,7 @@ on:
jobs:
build:
runs-on: ubuntu-latest
name: build (14.x) # temporary solution to trick branch protection rules
name: build (18.x) # temporary solution to trick branch protection rules
services:
# Label used to access the service container

View File

@ -148,6 +148,7 @@ import { bulkMetricsSchema } from './spec/bulk-metrics-schema';
import { clientMetricsEnvSchema } from './spec/client-metrics-env-schema';
import { updateTagsSchema } from './spec/update-tags-schema';
import { batchStaleSchema } from './spec/batch-stale-schema';
import { createApplicationSchema } from './spec/create-application-schema';
// Schemas must have an $id property on the form "#/components/schemas/mySchema".
export type SchemaId = typeof schemas[keyof typeof schemas]['$id'];
@ -205,6 +206,7 @@ export const schemas: UnleashSchemas = {
contextFieldSchema,
contextFieldsSchema,
createApiTokenSchema,
createApplicationSchema,
createFeatureSchema,
createFeatureStrategySchema,
createInvitedUserSchema,

View File

@ -81,8 +81,6 @@ const metaRules: Rule[] = [
knownExceptions: [
'apiTokenSchema',
'apiTokensSchema',
'applicationSchema',
'applicationsSchema',
'batchFeaturesSchema',
'batchStaleSchema',
'changePasswordSchema',
@ -90,8 +88,6 @@ const metaRules: Rule[] = [
'clientFeatureSchema',
'clientFeaturesQuerySchema',
'clientFeaturesSchema',
'clientMetricsSchema',
'bulkMetricsSchema',
'cloneFeatureSchema',
'contextFieldSchema',
'createApiTokenSchema',
@ -105,17 +101,14 @@ const metaRules: Rule[] = [
'eventsSchema',
'exportResultSchema',
'exportQuerySchema',
'featureEnvironmentMetricsSchema',
'featureEnvironmentSchema',
'featureEventsSchema',
'featureMetricsSchema',
'featureSchema',
'featuresSchema',
'featureStrategySchema',
'featureStrategySegmentSchema',
'featureTypeSchema',
'featureTypesSchema',
'featureUsageSchema',
'featureVariantsSchema',
'feedbackSchema',
'groupSchema',
@ -206,7 +199,6 @@ const metaRules: Rule[] = [
'clientFeatureSchema',
'clientFeaturesQuerySchema',
'clientFeaturesSchema',
'clientMetricsSchema',
'cloneFeatureSchema',
'contextFieldSchema',
'contextFieldsSchema',
@ -222,15 +214,12 @@ const metaRules: Rule[] = [
'eventsSchema',
'exportResultSchema',
'exportQuerySchema',
'featureEnvironmentMetricsSchema',
'featureEventsSchema',
'featureMetricsSchema',
'featureSchema',
'featuresSchema',
'featureStrategySegmentSchema',
'featureTypeSchema',
'featureTypesSchema',
'featureUsageSchema',
'featureVariantsSchema',
'feedbackSchema',
'groupSchema',

View File

@ -7,31 +7,46 @@ export const applicationSchema = {
required: ['appName'],
properties: {
appName: {
description: 'Name of the application',
type: 'string',
example: 'accounting',
},
sdkVersion: {
description:
'Which SDK and version the application reporting uses. Typically represented as `<identifier>:<version>`',
type: 'string',
example: 'unleash-client-java:8.0.0',
},
strategies: {
description:
'Which [strategies](https://docs.getunleash.io/topics/the-anatomy-of-unleash#activation-strategies) the application has loaded. Useful when trying to figure out if your [custom strategy](https://docs.getunleash.io/reference/custom-activation-strategies) has been loaded in the SDK',
type: 'array',
items: {
type: 'string',
},
example: ['standard', 'gradualRollout', 'mySpecialCustomStrategy'],
},
description: {
description:
'Extra information added about the application reporting the metrics. Only present if added via the Unleash Admin interface',
type: 'string',
example: 'Application for reporting page visits',
},
url: {
description:
'A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application',
type: 'string',
example: 'https://github.com/Unleash/unleash-client-proxy-js',
},
color: {
description: `The CSS color that is used to color the application's entry in the application list`,
type: 'string',
example: 'red',
},
icon: {
description: `An URL to an icon file to be used for the applications's entry in the application list`,
type: 'string',
},
announced: {
type: 'boolean',
example: 'https://github.com/favicon.ico',
},
},
components: {},

View File

@ -3,9 +3,12 @@ import { FromSchema } from 'json-schema-to-ts';
export const applicationsSchema = {
$id: '#/components/schemas/applicationsSchema',
additionalProperties: false,
type: 'object',
properties: {
applications: {
description:
'Contains a list of applications that have connected via an SDK',
type: 'array',
items: {
$ref: '#/components/schemas/applicationSchema',

View File

@ -11,12 +11,15 @@ export const bulkMetricsSchema = {
'A batch of metrics accumulated by Edge (or other compatible applications). Includes both application registrations as well usage metrics from clients',
properties: {
applications: {
description: 'A list of applications registered by an Unleash SDK',
type: 'array',
items: {
$ref: '#/components/schemas/bulkRegistrationSchema',
},
},
metrics: {
description:
'a list of client usage metrics registered by downstream providers. (Typically Unleash Edge)',
type: 'array',
items: {
$ref: '#/components/schemas/clientMetricsEnvSchema',

View File

@ -31,13 +31,15 @@ export const clientMetricsEnvSchema = {
},
yes: {
description: 'How many times the toggle evaluated to true',
type: 'number',
type: 'integer',
example: 974,
minimum: 0,
},
no: {
description: 'How many times the toggle evaluated to false',
type: 'number',
type: 'integer',
example: 50,
minimum: 0,
},
variants: {
description: 'How many times each variant was returned',

View File

@ -5,18 +5,48 @@ export const clientMetricsSchema = {
$id: '#/components/schemas/clientMetricsSchema',
type: 'object',
required: ['appName', 'bucket'],
description:
'Client usage metrics, accumulated in buckets of hour by hour by default',
properties: {
appName: { type: 'string' },
instanceId: { type: 'string' },
environment: { type: 'string' },
appName: {
description:
'The name of the application that is evaluating toggles',
type: 'string',
example: 'insurance-selector',
},
instanceId: {
description:
'A [(somewhat) unique identifier](https://docs.getunleash.io/reference/sdks/node#advanced-usage) for the application',
type: 'string',
example: 'application-name-dacb1234',
},
environment: {
description: 'Which environment the application is running in',
type: 'string',
example: 'development',
},
bucket: {
type: 'object',
required: ['start', 'stop', 'toggles'],
description:
'Holds all metrics gathered over a window of time. Typically 1 hour wide',
properties: {
start: { $ref: '#/components/schemas/dateSchema' },
stop: { $ref: '#/components/schemas/dateSchema' },
start: {
$ref: '#/components/schemas/dateSchema',
description:
'The start of the time window these metrics are valid for. The window is usually 1 hour wide',
example: '1926-05-08T12:00:00.000Z',
},
stop: {
$ref: '#/components/schemas/dateSchema',
description:
'The end of the time window these metrics are valid for. The window is 1 hour wide',
example: '1926-05-08T13:00:00.000Z',
},
toggles: {
type: 'object',
description:
'an object containing feature names with yes/no plus variant usage',
example: {
myCoolToggle: {
yes: 25,
@ -35,14 +65,33 @@ export const clientMetricsSchema = {
additionalProperties: {
type: 'object',
properties: {
yes: { type: 'integer', minimum: 0 },
no: { type: 'integer', minimum: 0 },
yes: {
description:
'How many times the toggle evaluated to true',
type: 'number',
example: 974,
minimum: 0,
},
no: {
description:
'How many times the toggle evaluated to false',
type: 'integer',
example: 50,
minimum: 0,
},
variants: {
description:
'How many times each variant was returned',
type: 'object',
additionalProperties: {
type: 'integer',
minimum: 0,
},
example: {
variantA: 15,
variantB: 25,
variantC: 5,
},
},
},
},

View File

@ -0,0 +1,52 @@
import { FromSchema } from 'json-schema-to-ts';
export const createApplicationSchema = {
$id: '#/components/schemas/createApplicationSchema',
type: 'object',
additionalProperties: true,
description: 'Reported application information from Unleash SDKs',
required: ['appName'],
properties: {
appName: {
description: 'Name of the application',
type: 'string',
example: 'accounting',
},
sdkVersion: {
description:
'Which SDK and version the application reporting uses. Typically represented as `<identifier>:<version>`',
type: 'string',
example: 'unleash-client-java:8.0.0',
},
strategies: {
description:
'Which [strategies](https://docs.getunleash.io/topics/the-anatomy-of-unleash#activation-strategies) the application has loaded. Useful when trying to figure out if your [custom strategy](https://docs.getunleash.io/reference/custom-activation-strategies) has been loaded in the SDK',
type: 'array',
items: {
type: 'string',
},
example: ['standard', 'gradualRollout', 'mySpecialCustomStrategy'],
},
url: {
description:
'A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application',
type: 'string',
example: 'https://github.com/Unleash/unleash-client-proxy-js',
},
color: {
description: `Css color to be used to color the application's entry in the application list`,
type: 'string',
example: 'red',
},
icon: {
description: `An URL to an icon file to be used for the applications's entry in the application list`,
type: 'string',
example: 'https://github.com/favicon.ico',
},
},
components: {},
} as const;
export type CreateApplicationSchema = FromSchema<
typeof createApplicationSchema
>;

View File

@ -1,32 +1,51 @@
import { FromSchema } from 'json-schema-to-ts';
import { dateSchema } from './date-schema';
export const featureEnvironmentMetricsSchema = {
$id: '#/components/schemas/featureEnvironmentMetricsSchema',
type: 'object',
additionalProperties: false,
required: ['environment', 'timestamp', 'yes', 'no'],
description:
'How many times `feautreName` was evaluated to `true` (yes) and `false` (no) for `appName` in `environmnet`',
properties: {
featureName: {
description: 'The name of the feature',
type: 'string',
example: 'my.special.feature',
},
appName: {
description: 'The name of the application the SDK is being used in',
type: 'string',
example: 'accounting',
},
environment: {
description: 'Which environment the SDK is being used in',
type: 'string',
example: 'development',
},
timestamp: {
type: 'string',
format: 'date-time',
description:
'The start of the time window these metrics are valid for. The window is usually 1 hour wide',
example: '1926-05-08T12:00:00.000Z',
$ref: '#/components/schemas/dateSchema',
},
yes: {
type: 'number',
description: 'How many times the toggle evaluated to true',
type: 'integer',
example: 974,
minimum: 0,
},
no: {
type: 'number',
description: 'How many times the toggle evaluated to false',
type: 'integer',
example: 50,
minimum: 0,
},
},
components: {},
components: {
dateSchema,
},
} as const;
export type FeatureEnvironmentMetricsSchema = FromSchema<

View File

@ -1,19 +1,27 @@
import { FromSchema } from 'json-schema-to-ts';
import { featureEnvironmentMetricsSchema } from './feature-environment-metrics-schema';
import { dateSchema } from './date-schema';
export const featureMetricsSchema = {
$id: '#/components/schemas/featureMetricsSchema',
type: 'object',
additionalProperties: false,
required: ['version', 'maturity', 'data'],
description: 'A batch of feature metrics',
properties: {
version: {
type: 'number',
description: 'The version of this schema',
type: 'integer',
minimum: 1,
},
maturity: {
description:
'The maturity level of this API (alpha, beta, stable, deprecated)',
type: 'string',
example: 'stable',
},
data: {
description: 'Metrics gathered per environment',
type: 'array',
items: {
$ref: '#/components/schemas/featureEnvironmentMetricsSchema',
@ -23,6 +31,7 @@ export const featureMetricsSchema = {
components: {
schemas: {
featureEnvironmentMetricsSchema,
dateSchema,
},
},
} as const;

View File

@ -1,10 +1,13 @@
import { FromSchema } from 'json-schema-to-ts';
import { featureEnvironmentMetricsSchema } from './feature-environment-metrics-schema';
import { dateSchema } from './date-schema';
export const featureUsageSchema = {
$id: '#/components/schemas/featureUsageSchema',
type: 'object',
additionalProperties: false,
description:
'How many applications have seen this feature toggle, as well as how this feature was evaluated the last hour',
required: [
'version',
'maturity',
@ -14,30 +17,42 @@ export const featureUsageSchema = {
],
properties: {
version: {
type: 'number',
description: 'The version of this schema',
type: 'integer',
minimum: 1,
},
maturity: {
description:
'The maturity level of this API (alpha, beta, stable, deprecated)',
type: 'string',
example: 'stable',
},
featureName: {
description: 'The name of the feature',
type: 'string',
example: 'my.special.feature',
},
lastHourUsage: {
description:
'Last hour statistics. Accumulated per feature per environment. Contains counts for evaluations to true (yes) and to false (no)',
type: 'array',
items: {
$ref: '#/components/schemas/featureEnvironmentMetricsSchema',
},
},
seenApplications: {
description: 'A list of applications seen using this feature',
type: 'array',
items: {
type: 'string',
},
example: ['accounting', 'billing', 'booking'],
},
},
components: {
schemas: {
featureEnvironmentMetricsSchema,
dateSchema,
},
},
} as const;

View File

@ -16,6 +16,7 @@ import {
featureMetricsSchema,
FeatureMetricsSchema,
} from '../../openapi/spec/feature-metrics-schema';
import { getStandardResponses } from '../../openapi';
interface IName {
name: string;
@ -58,8 +59,11 @@ class ClientMetricsController extends Controller {
openApiService.validPath({
operationId: 'getRawFeatureMetrics',
tags: ['Metrics'],
summary:
'Feature usage metrics for the last 48 hours, grouped by hour',
responses: {
200: createResponseSchema('featureMetricsSchema'),
...getStandardResponses(401, 403, 404),
},
}),
],
@ -74,8 +78,12 @@ class ClientMetricsController extends Controller {
openApiService.validPath({
operationId: 'getFeatureUsageSummary',
tags: ['Metrics'],
summary: `Last hour of usage and a list of applications that have reported seeing this feature toggle`,
description:
'Separate counts for yes (enabled), no (disabled), as well as how many times each variant was selected during the last hour',
responses: {
200: createResponseSchema('featureUsageSchema'),
...getStandardResponses(401, 403, 404),
},
}),
],

View File

@ -9,7 +9,11 @@ import { createRequestSchema } from '../../openapi/util/create-request-schema';
import { createResponseSchema } from '../../openapi/util/create-response-schema';
import { ApplicationSchema } from '../../openapi/spec/application-schema';
import { ApplicationsSchema } from '../../openapi/spec/applications-schema';
import { emptyResponse } from '../../openapi/util/standard-responses';
import {
emptyResponse,
getStandardResponses,
} from '../../openapi/util/standard-responses';
import { CreateApplicationSchema } from '../../openapi/spec/create-application-schema';
class MetricsController extends Controller {
private logger: Logger;
@ -43,10 +47,15 @@ class MetricsController extends Controller {
openApiService.validPath({
tags: ['Metrics'],
operationId: 'createApplication',
summary:
'Create an application to connect reported metrics',
description:
'Is used to report usage as well which sdk the application uses',
responses: {
202: emptyResponse,
...getStandardResponses(400, 401, 403),
},
requestBody: createRequestSchema('applicationSchema'),
requestBody: createRequestSchema('createApplicationSchema'),
}),
],
});
@ -60,8 +69,11 @@ class MetricsController extends Controller {
openApiService.validPath({
tags: ['Metrics'],
operationId: 'deleteApplication',
summary: 'Delete an application',
description: `Delete the application specified in the request URL. Returns 200 OK if the application was successfully deleted or if it didn't exist`,
responses: {
200: emptyResponse,
...getStandardResponses(401, 403),
},
}),
],
@ -74,6 +86,9 @@ class MetricsController extends Controller {
middleware: [
openApiService.validPath({
tags: ['Metrics'],
summary: 'Get all applications',
description:
'Returns all applications registered with Unleash. Applications can be created via metrics reporting or manual creation',
operationId: 'getApplications',
responses: {
200: createResponseSchema('applicationsSchema'),
@ -90,8 +105,12 @@ class MetricsController extends Controller {
openApiService.validPath({
tags: ['Metrics'],
operationId: 'getApplication',
summary: 'Get application data',
description:
'Returns data about the specified application (`appName`). The data contains information on the name of the application, sdkVersion (which sdk reported these metrics, typically `unleash-client-node:3.4.1` or `unleash-client-java:7.1.0`), as well as data about how to display this application in a list.',
responses: {
200: createResponseSchema('applicationSchema'),
...getStandardResponses(404),
},
}),
],
@ -117,7 +136,7 @@ class MetricsController extends Controller {
}
async createApplication(
req: Request<{ appName: string }, unknown, ApplicationSchema>,
req: Request<{ appName: string }, unknown, CreateApplicationSchema>,
res: Response,
): Promise<void> {
const input = {

View File

@ -703,31 +703,46 @@ The provider you choose for your addon dictates what properties the \`parameters
"applicationSchema": {
"additionalProperties": false,
"properties": {
"announced": {
"type": "boolean",
},
"appName": {
"description": "Name of the application",
"example": "accounting",
"type": "string",
},
"color": {
"description": "The CSS color that is used to color the application's entry in the application list",
"example": "red",
"type": "string",
},
"description": {
"description": "Extra information added about the application reporting the metrics. Only present if added via the Unleash Admin interface",
"example": "Application for reporting page visits",
"type": "string",
},
"icon": {
"description": "An URL to an icon file to be used for the applications's entry in the application list",
"example": "https://github.com/favicon.ico",
"type": "string",
},
"sdkVersion": {
"description": "Which SDK and version the application reporting uses. Typically represented as \`<identifier>:<version>\`",
"example": "unleash-client-java:8.0.0",
"type": "string",
},
"strategies": {
"description": "Which [strategies](https://docs.getunleash.io/topics/the-anatomy-of-unleash#activation-strategies) the application has loaded. Useful when trying to figure out if your [custom strategy](https://docs.getunleash.io/reference/custom-activation-strategies) has been loaded in the SDK",
"example": [
"standard",
"gradualRollout",
"mySpecialCustomStrategy",
],
"items": {
"type": "string",
},
"type": "array",
},
"url": {
"description": "A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application",
"example": "https://github.com/Unleash/unleash-client-proxy-js",
"type": "string",
},
},
@ -737,8 +752,10 @@ The provider you choose for your addon dictates what properties the \`parameters
"type": "object",
},
"applicationsSchema": {
"additionalProperties": false,
"properties": {
"applications": {
"description": "Contains a list of applications that have connected via an SDK",
"items": {
"$ref": "#/components/schemas/applicationSchema",
},
@ -783,12 +800,14 @@ The provider you choose for your addon dictates what properties the \`parameters
"description": "A batch of metrics accumulated by Edge (or other compatible applications). Includes both application registrations as well usage metrics from clients",
"properties": {
"applications": {
"description": "A list of applications registered by an Unleash SDK",
"items": {
"$ref": "#/components/schemas/bulkRegistrationSchema",
},
"type": "array",
},
"metrics": {
"description": "a list of client usage metrics registered by downstream providers. (Typically Unleash Edge)",
"items": {
"$ref": "#/components/schemas/clientMetricsEnvSchema",
},
@ -1075,7 +1094,8 @@ The provider you choose for your addon dictates what properties the \`parameters
"no": {
"description": "How many times the toggle evaluated to false",
"example": 50,
"type": "number",
"minimum": 0,
"type": "integer",
},
"timestamp": {
"$ref": "#/components/schemas/dateSchema",
@ -1098,7 +1118,8 @@ The provider you choose for your addon dictates what properties the \`parameters
"yes": {
"description": "How many times the toggle evaluated to true",
"example": 974,
"type": "number",
"minimum": 0,
"type": "integer",
},
},
"required": [
@ -1109,22 +1130,32 @@ The provider you choose for your addon dictates what properties the \`parameters
"type": "object",
},
"clientMetricsSchema": {
"description": "Client usage metrics, accumulated in buckets of hour by hour by default",
"properties": {
"appName": {
"description": "The name of the application that is evaluating toggles",
"example": "insurance-selector",
"type": "string",
},
"bucket": {
"description": "Holds all metrics gathered over a window of time. Typically 1 hour wide",
"properties": {
"start": {
"$ref": "#/components/schemas/dateSchema",
"description": "The start of the time window these metrics are valid for. The window is usually 1 hour wide",
"example": "1926-05-08T12:00:00.000Z",
},
"stop": {
"$ref": "#/components/schemas/dateSchema",
"description": "The end of the time window these metrics are valid for. The window is 1 hour wide",
"example": "1926-05-08T13:00:00.000Z",
},
"toggles": {
"additionalProperties": {
"properties": {
"no": {
"description": "How many times the toggle evaluated to false",
"example": 50,
"minimum": 0,
"type": "integer",
},
@ -1133,15 +1164,24 @@ The provider you choose for your addon dictates what properties the \`parameters
"minimum": 0,
"type": "integer",
},
"description": "How many times each variant was returned",
"example": {
"variantA": 15,
"variantB": 25,
"variantC": 5,
},
"type": "object",
},
"yes": {
"description": "How many times the toggle evaluated to true",
"example": 974,
"minimum": 0,
"type": "integer",
"type": "number",
},
},
"type": "object",
},
"description": "an object containing feature names with yes/no plus variant usage",
"example": {
"myCoolToggle": {
"no": 42,
@ -1168,9 +1208,13 @@ The provider you choose for your addon dictates what properties the \`parameters
"type": "object",
},
"environment": {
"description": "Which environment the application is running in",
"example": "development",
"type": "string",
},
"instanceId": {
"description": "A [(somewhat) unique identifier](https://docs.getunleash.io/reference/sdks/node#advanced-usage) for the application",
"example": "application-name-dacb1234",
"type": "string",
},
},
@ -1332,6 +1376,53 @@ The provider you choose for your addon dictates what properties the \`parameters
],
"type": "object",
},
"createApplicationSchema": {
"additionalProperties": true,
"description": "Reported application information from Unleash SDKs",
"properties": {
"appName": {
"description": "Name of the application",
"example": "accounting",
"type": "string",
},
"color": {
"description": "Css color to be used to color the application's entry in the application list",
"example": "red",
"type": "string",
},
"icon": {
"description": "An URL to an icon file to be used for the applications's entry in the application list",
"example": "https://github.com/favicon.ico",
"type": "string",
},
"sdkVersion": {
"description": "Which SDK and version the application reporting uses. Typically represented as \`<identifier>:<version>\`",
"example": "unleash-client-java:8.0.0",
"type": "string",
},
"strategies": {
"description": "Which [strategies](https://docs.getunleash.io/topics/the-anatomy-of-unleash#activation-strategies) the application has loaded. Useful when trying to figure out if your [custom strategy](https://docs.getunleash.io/reference/custom-activation-strategies) has been loaded in the SDK",
"example": [
"standard",
"gradualRollout",
"mySpecialCustomStrategy",
],
"items": {
"type": "string",
},
"type": "array",
},
"url": {
"description": "A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application",
"example": "https://github.com/Unleash/unleash-client-proxy-js",
"type": "string",
},
},
"required": [
"appName",
],
"type": "object",
},
"createFeatureSchema": {
"properties": {
"description": {
@ -1849,25 +1940,39 @@ The provider you choose for your addon dictates what properties the \`parameters
},
"featureEnvironmentMetricsSchema": {
"additionalProperties": false,
"description": "How many times \`feautreName\` was evaluated to \`true\` (yes) and \`false\` (no) for \`appName\` in \`environmnet\`",
"properties": {
"appName": {
"description": "The name of the application the SDK is being used in",
"example": "accounting",
"type": "string",
},
"environment": {
"description": "Which environment the SDK is being used in",
"example": "development",
"type": "string",
},
"featureName": {
"description": "The name of the feature",
"example": "my.special.feature",
"type": "string",
},
"no": {
"type": "number",
"description": "How many times the toggle evaluated to false",
"example": 50,
"minimum": 0,
"type": "integer",
},
"timestamp": {
"format": "date-time",
"type": "string",
"$ref": "#/components/schemas/dateSchema",
"description": "The start of the time window these metrics are valid for. The window is usually 1 hour wide",
"example": "1926-05-08T12:00:00.000Z",
},
"yes": {
"type": "number",
"description": "How many times the toggle evaluated to true",
"example": 974,
"minimum": 0,
"type": "integer",
},
},
"required": [
@ -1960,18 +2065,24 @@ The provider you choose for your addon dictates what properties the \`parameters
},
"featureMetricsSchema": {
"additionalProperties": false,
"description": "A batch of feature metrics",
"properties": {
"data": {
"description": "Metrics gathered per environment",
"items": {
"$ref": "#/components/schemas/featureEnvironmentMetricsSchema",
},
"type": "array",
},
"maturity": {
"description": "The maturity level of this API (alpha, beta, stable, deprecated)",
"example": "stable",
"type": "string",
},
"version": {
"type": "number",
"description": "The version of this schema",
"minimum": 1,
"type": "integer",
},
},
"required": [
@ -2245,27 +2356,41 @@ The provider you choose for your addon dictates what properties the \`parameters
},
"featureUsageSchema": {
"additionalProperties": false,
"description": "How many applications have seen this feature toggle, as well as how this feature was evaluated the last hour",
"properties": {
"featureName": {
"description": "The name of the feature",
"example": "my.special.feature",
"type": "string",
},
"lastHourUsage": {
"description": "Last hour statistics. Accumulated per feature per environment. Contains counts for evaluations to true (yes) and to false (no)",
"items": {
"$ref": "#/components/schemas/featureEnvironmentMetricsSchema",
},
"type": "array",
},
"maturity": {
"description": "The maturity level of this API (alpha, beta, stable, deprecated)",
"example": "stable",
"type": "string",
},
"seenApplications": {
"description": "A list of applications seen using this feature",
"example": [
"accounting",
"billing",
"booking",
],
"items": {
"type": "string",
},
"type": "array",
},
"version": {
"type": "number",
"description": "The version of this schema",
"minimum": 1,
"type": "integer",
},
},
"required": [
@ -5913,6 +6038,7 @@ Note: passing \`null\` as a value for the description property will set it to an
},
"/api/admin/client-metrics/features/{name}": {
"get": {
"description": "Separate counts for yes (enabled), no (disabled), as well as how many times each variant was selected during the last hour",
"operationId": "getFeatureUsageSummary",
"parameters": [
{
@ -5935,7 +6061,89 @@ Note: passing \`null\` as a value for the description property will set it to an
},
"description": "featureUsageSchema",
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
"404": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "Could not find the addon with ID "12345".",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NotFoundError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The requested resource was not found.",
},
},
"summary": "Last hour of usage and a list of applications that have reported seeing this feature toggle",
"tags": [
"Metrics",
],
@ -5965,7 +6173,89 @@ Note: passing \`null\` as a value for the description property will set it to an
},
"description": "featureMetricsSchema",
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
"404": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "Could not find the addon with ID "12345".",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NotFoundError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The requested resource was not found.",
},
},
"summary": "Feature usage metrics for the last 48 hours, grouped by hour",
"tags": [
"Metrics",
],
@ -8202,6 +8492,7 @@ If the provided project does not exist, the list of events will be empty.",
},
"/api/admin/metrics/applications": {
"get": {
"description": "Returns all applications registered with Unleash. Applications can be created via metrics reporting or manual creation",
"operationId": "getApplications",
"responses": {
"200": {
@ -8215,6 +8506,7 @@ If the provided project does not exist, the list of events will be empty.",
"description": "applicationsSchema",
},
},
"summary": "Get all applications",
"tags": [
"Metrics",
],
@ -8222,6 +8514,7 @@ If the provided project does not exist, the list of events will be empty.",
},
"/api/admin/metrics/applications/{appName}": {
"delete": {
"description": "Delete the application specified in the request URL. Returns 200 OK if the application was successfully deleted or if it didn't exist",
"operationId": "deleteApplication",
"parameters": [
{
@ -8237,12 +8530,68 @@ If the provided project does not exist, the list of events will be empty.",
"200": {
"description": "This response has no body.",
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
},
"summary": "Delete an application",
"tags": [
"Metrics",
],
},
"get": {
"description": "Returns data about the specified application (\`appName\`). The data contains information on the name of the application, sdkVersion (which sdk reported these metrics, typically \`unleash-client-node:3.4.1\` or \`unleash-client-java:7.1.0\`), as well as data about how to display this application in a list.",
"operationId": "getApplication",
"parameters": [
{
@ -8265,12 +8614,41 @@ If the provided project does not exist, the list of events will be empty.",
},
"description": "applicationSchema",
},
"404": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "Could not find the addon with ID "12345".",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NotFoundError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The requested resource was not found.",
},
},
"summary": "Get application data",
"tags": [
"Metrics",
],
},
"post": {
"description": "Is used to report usage as well which sdk the application uses",
"operationId": "createApplication",
"parameters": [
{
@ -8286,18 +8664,100 @@ If the provided project does not exist, the list of events will be empty.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/applicationSchema",
"$ref": "#/components/schemas/createApplicationSchema",
},
},
},
"description": "applicationSchema",
"description": "createApplicationSchema",
"required": true,
},
"responses": {
"202": {
"description": "This response has no body.",
},
"400": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "ValidationError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The request data does not match what we expect.",
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
},
"summary": "Create an application to connect reported metrics",
"tags": [
"Metrics",
],