Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-05-31 01:16:01 +02:00
Code Issues Projects Releases Wiki Activity

docs: Instance admin (#3961)

Browse Source 
### What
Adds the documentation for the instance admin endpoints.

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
This commit is contained in:
Christopher Kolstad 2023-06-13 14:10:21 +02:00 committed by GitHub
parent 555f77463d
commit 5f3e5729b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 239 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib/openapi/meta-schema-rules.test.ts
View File

@ -113,7 +113,6 @@ const metaRules: Rule[] = [
'groupsSchema',
'groupUserModelSchema',
'idSchema',
'instanceAdminStatsSchema',
'legalValueSchema',
'loginSchema',
'maintenanceSchema',
@ -217,7 +216,6 @@ const metaRules: Rule[] = [
'groupsSchema',
'groupUserModelSchema',
'idSchema',
'instanceAdminStatsSchema',
'legalValueSchema',
'loginSchema',
'maintenanceSchema',

79
src/lib/openapi/spec/instance-admin-stats-schema.ts
View File

@ -4,57 +4,132 @@ export const instanceAdminStatsSchema = {
$id: '#/components/schemas/instanceAdminStatsSchema',
type: 'object',
additionalProperties: false,
description:
'Information about an instance and statistics about usage of various features of Unleash',
required: ['instanceId'],
properties: {
instanceId: {
type: 'string',
description:
'A unique identifier for this instance. Generated by the database migration scripts at first run. Typically a UUID.',
example: 'ed3861ae-78f9-4e8c-8e57-b57efc15f82b',
},
timestamp: {
type: 'string',
format: 'date-time',
nullable: true,
description: 'When these statistics were produced',
example: '2023-06-12T12:25:06Z',
},
versionOSS: {
type: 'string',
description:
'The version of Unleash OSS that is bundled in this instance',
example: '5.1.7',
},
versionEnterprise: {
type: 'string',
description:
'The version of Unleash Enterprise that is bundled in this instance',
example: '5.1.7',
},
users: {
type: 'number',
description: 'The number of users this instance has',
example: 8,
minimum: 0,
},
featureToggles: {
type: 'number',
description: 'The number of feature-toggles this instance has',
example: 47,
minimum: 0,
},
projects: {
type: 'number',
description: 'The number of projects defined in this instance.',
example: 3,
minimum: 0,
},
contextFields: {
type: 'number',
description:
'The number of context fields defined in this instance.',
example: 7,
minimum: 0,
},
roles: {
type: 'number',
description: 'The number of roles defined in this instance',
example: 5,
minimum: 0,
},
groups: {
type: 'number',
description: 'The number of groups defined in this instance',
example: 12,
minimum: 0,
},
environments: {
type: 'number',
description: 'The number of environments defined in this instance',
example: 3,
minimum: 0,
},
segments: {
type: 'number',
description: 'The number of segments defined in this instance',
example: 19,
minimum: 0,
},
strategies: {
type: 'number',
description: 'The number of strategies defined in this instance',
example: 8,
minimum: 0,
},
SAMLenabled: {
type: 'number',
type: 'boolean',
description:
'Whether or not SAML authentication is enabled for this instance',
example: false,
},
OIDCenabled: {
type: 'number',
type: 'boolean',
description:
'Whether or not OIDC authentication is enabled for this instance',
example: true,
},
clientApps: {
type: 'array',
description:
'A count of connected applications in the last week, last month and all time since last restart',
items: {
type: 'object',
description:
'An entry describing how many client applications has been observed over the defined range',
properties: {
range: {
type: 'string',
description: 'A description of a time range',
enum: ['allTime', '30d', '7d'],
example: '30d',
},
count: {
type: 'number',
description:
'The number of client applications that have been observed in this period',
example: 1,
},
},
},
},
sum: {
type: 'string',
description:
'A SHA-256 checksum of the instance statistics to be used to verify that the data in this object has not been tampered with',
example:
'b023323477abb1eb145bebf3cdb30a1c2063e3edc1f7ae474ed8ed6c80de9a3b',
},
},
components: {},

9
src/lib/openapi/util/create-response-schema.ts
View File

@ -36,6 +36,15 @@ export const createResponseSchema = (
});
};
export const createCsvResponseSchema = (
schemaName: string,
example: string,
): OpenAPIV3.ResponseObject => {
return createResponseSchemas(schemaName, {
'text/csv': { example, ...schemaTyped('string') },
});
};
export const resourceCreatedResponseSchema = (
schemaName: string,
): OpenAPIV3.ResponseObject => {

58
src/lib/routes/admin-api/instance-admin.ts
View File

@ -9,15 +9,21 @@ import { UiConfigSchema } from '../../openapi/spec/ui-config-schema';
import {
InstanceStats,
InstanceStatsService,
InstanceStatsSigned,
} from '../../services/instance-stats-service';
import { OpenApiService } from '../../services/openapi-service';
import { createResponseSchema } from '../../openapi/util/create-response-schema';
import {
createCsvResponseSchema,
createResponseSchema,
} from '../../openapi/util/create-response-schema';
class InstanceAdminController extends Controller {
private instanceStatsService: InstanceStatsService;
private openApiService: OpenApiService;
private jsonCsvParser: Parser;
constructor(
config: IUnleashConfig,
{
@ -26,7 +32,7 @@ class InstanceAdminController extends Controller {
}: Pick<IUnleashServices, 'instanceStatsService' | 'openApiService'>,
) {
super(config);
this.jsonCsvParser = new Parser();
this.openApiService = openApiService;
this.instanceStatsService = instanceStatsService;
@ -35,6 +41,23 @@ class InstanceAdminController extends Controller {
path: '/statistics/csv',
handler: this.getStatisticsCSV,
permission: NONE,
middleware: [
openApiService.validPath({
tags: ['Instance Admin'],
summary: 'Instance usage statistics',
description:
'Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.',
operationId: 'getInstanceAdminStatsCsv',
responses: {
200: createCsvResponseSchema(
'instanceAdminStatsSchemaCsv',
this.jsonCsvParser.parse(
this.instanceStatsExample(),
),
),
},
}),
],
});
this.route({
@ -46,6 +69,9 @@ class InstanceAdminController extends Controller {
openApiService.validPath({
tags: ['Instance Admin'],
operationId: 'getInstanceAdminStats',
summary: 'Instance usage statistics',
description:
'Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.',
responses: {
200: createResponseSchema('instanceAdminStatsSchema'),
},
@ -55,6 +81,34 @@ class InstanceAdminController extends Controller {
});
}
instanceStatsExample(): InstanceStatsSigned {
return {
OIDCenabled: true,
SAMLenabled: false,
clientApps: [
{ range: 'allTime', count: 15 },
{ range: '30d', count: 9 },
{ range: '7d', count: 5 },
],
contextFields: 6,
environments: 2,
featureExports: 0,
featureImports: 0,
featureToggles: 29,
groups: 3,
instanceId: 'ed3861ae-78f9-4e8c-8e57-b57efc15f82b',
projects: 1,
roles: 5,
segments: 2,
strategies: 8,
sum: 'some-sha256-hash',
timestamp: new Date(2023, 6, 12, 10, 0, 0, 0),
users: 10,
versionEnterprise: '5.1.7',
versionOSS: '5.1.7',
};
}
async getStatistics(
req: AuthedRequest,
res: Response<InstanceStats>,

4
src/lib/services/instance-stats-service.ts
View File

@ -19,7 +19,7 @@ import VersionService from './version-service';
import { ISettingStore } from '../types/stores/settings-store';
import { FEATURES_EXPORTED, FEATURES_IMPORTED } from '../types';
type TimeRange = 'allTime' | '30d' | '7d';
export type TimeRange = 'allTime' | '30d' | '7d';
export interface InstanceStats {
instanceId: string;
@ -42,7 +42,7 @@ export interface InstanceStats {
clientApps: { range: TimeRange; count: number }[];
}
interface InstanceStatsSigned extends InstanceStats {
export interface InstanceStatsSigned extends InstanceStats {
sum: string;
}

97
src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap
View File

@ -3043,55 +3043,122 @@ The provider you choose for your addon dictates what properties the \`parameters
},
"instanceAdminStatsSchema": {
"additionalProperties": false,
"description": "Information about an instance and statistics about usage of various features of Unleash",
"properties": {
"OIDCenabled": {
"type": "number",
"description": "Whether or not OIDC authentication is enabled for this instance",
"example": true,
"type": "boolean",
},
"SAMLenabled": {
"type": "number",
"description": "Whether or not SAML authentication is enabled for this instance",
"example": false,
"type": "boolean",
},
"clientApps": {
"description": "A count of connected applications in the last week, last month and all time since last restart",
"items": {
"description": "An entry describing how many client applications has been observed over the defined range",
"properties": {
"count": {
"description": "The number of client applications that have been observed in this period",
"example": 1,
"type": "number",
},
"range": {
"description": "A description of a time range",
"enum": [
"allTime",
"30d",
"7d",
],
"example": "30d",
"type": "string",
},
},
"type": "object",
},
"type": "array",
},
"contextFields": {
"description": "The number of context fields defined in this instance.",
"example": 7,
"minimum": 0,
"type": "number",
},
"environments": {
"description": "The number of environments defined in this instance",
"example": 3,
"minimum": 0,
"type": "number",
},
"featureToggles": {
"description": "The number of feature-toggles this instance has",
"example": 47,
"minimum": 0,
"type": "number",
},
"groups": {
"description": "The number of groups defined in this instance",
"example": 12,
"minimum": 0,
"type": "number",
},
"instanceId": {
"description": "A unique identifier for this instance. Generated by the database migration scripts at first run. Typically a UUID.",
"example": "ed3861ae-78f9-4e8c-8e57-b57efc15f82b",
"type": "string",
},
"projects": {
"description": "The number of projects defined in this instance.",
"example": 3,
"minimum": 0,
"type": "number",
},
"roles": {
"description": "The number of roles defined in this instance",
"example": 5,
"minimum": 0,
"type": "number",
},
"segments": {
"description": "The number of segments defined in this instance",
"example": 19,
"minimum": 0,
"type": "number",
},
"strategies": {
"description": "The number of strategies defined in this instance",
"example": 8,
"minimum": 0,
"type": "number",
},
"sum": {
"description": "A SHA-256 checksum of the instance statistics to be used to verify that the data in this object has not been tampered with",
"example": "b023323477abb1eb145bebf3cdb30a1c2063e3edc1f7ae474ed8ed6c80de9a3b",
"type": "string",
},
"timestamp": {
"description": "When these statistics were produced",
"example": "2023-06-12T12:25:06Z",
"format": "date-time",
"nullable": true,
"type": "string",
},
"users": {
"description": "The number of users this instance has",
"example": 8,
"minimum": 0,
"type": "number",
},
"versionEnterprise": {
"description": "The version of Unleash Enterprise that is bundled in this instance",
"example": "5.1.7",
"type": "string",
},
"versionOSS": {
"description": "The version of Unleash OSS that is bundled in this instance",
"example": "5.1.7",
"type": "string",
},
},
@ -8310,6 +8377,7 @@ If the provided project does not exist, the list of events will be empty.",
"/api/admin/instance-admin/statistics": {
"get": {
"deprecated": true,
"description": "Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.",
"operationId": "getInstanceAdminStats",
"responses": {
"200": {
@ -8323,6 +8391,31 @@ If the provided project does not exist, the list of events will be empty.",
"description": "instanceAdminStatsSchema",
},
},
"summary": "Instance usage statistics",
"tags": [
"Instance Admin",
],
},
},
"/api/admin/instance-admin/statistics/csv": {
"get": {
"description": "Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.",
"operationId": "getInstanceAdminStatsCsv",
"responses": {
"200": {
"content": {
"text/csv": {
"example": ""OIDCenabled","SAMLenabled","clientApps","contextFields","environments","featureExports","featureImports","featureToggles","groups","instanceId","projects","roles","segments","strategies","sum","timestamp","users","versionEnterprise","versionOSS"
true,false,"[{""range"":""allTime"",""count"":15},{""range"":""30d"",""count"":9},{""range"":""7d"",""count"":5}]",6,2,0,0,29,3,"ed3861ae-78f9-4e8c-8e57-b57efc15f82b",1,5,2,8,"some-sha256-hash","2023-07-12T10:00:00.000Z",10,"5.1.7","5.1.7"",
"schema": {
"type": "string",
},
},
},
"description": "instanceAdminStatsSchemaCsv",
},
},
"summary": "Instance usage statistics",
"tags": [
"Instance Admin",
],