@supersdk/supercli 0.5.13-staging.125 → 0.5.13-staging.126
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/api/experimentClient.js +27 -0
- package/dist/api/experimentClient.js.map +1 -1
- package/dist/commands/experiment.js +562 -77
- package/dist/commands/experiment.js.map +1 -1
- package/dist/template/android/supersdk-default.config.json +1 -1
- package/dist/template/web/scripts/web_package.py +3 -1
- package/dist/template/web/src/js/supersdk.js +1 -1
- package/dist/template/web/src/js/supersdk.provenance.json +3 -3
- package/package.json +1 -1
|
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.defaultExperimentDeps = exports.EXPERIMENT_LIST_MAX_PAGES = void 0;
|
|
36
|
+
exports.METRIC_QUERY_DEFAULT_TIME_ZONE = exports.defaultExperimentDeps = exports.EXPERIMENT_LIST_MAX_PAGES = void 0;
|
|
37
37
|
exports.validExperimentKey = validExperimentKey;
|
|
38
38
|
exports.percentToBasisPoints = percentToBasisPoints;
|
|
39
39
|
exports.parseExpectedVersion = parseExpectedVersion;
|
|
@@ -53,9 +53,26 @@ exports.runExperimentOverridesGet = runExperimentOverridesGet;
|
|
|
53
53
|
exports.parseOverrideDevices = parseOverrideDevices;
|
|
54
54
|
exports.runExperimentOverridesSet = runExperimentOverridesSet;
|
|
55
55
|
exports.runExperimentMetricsList = runExperimentMetricsList;
|
|
56
|
-
exports.
|
|
56
|
+
exports.buildMetricSettings = buildMetricSettings;
|
|
57
|
+
exports.parseMetricKeys = parseMetricKeys;
|
|
58
|
+
exports.buildMetricsAddBody = buildMetricsAddBody;
|
|
57
59
|
exports.runExperimentMetricsAdd = runExperimentMetricsAdd;
|
|
60
|
+
exports.runExperimentMetricsUpdate = runExperimentMetricsUpdate;
|
|
58
61
|
exports.runExperimentMetricsRemove = runExperimentMetricsRemove;
|
|
62
|
+
exports.buildMetricDefinition = buildMetricDefinition;
|
|
63
|
+
exports.buildMetricDefCreateBody = buildMetricDefCreateBody;
|
|
64
|
+
exports.buildMetricDefUpdateBody = buildMetricDefUpdateBody;
|
|
65
|
+
exports.runMetricDefsList = runMetricDefsList;
|
|
66
|
+
exports.runMetricDefsGet = runMetricDefsGet;
|
|
67
|
+
exports.runMetricDefsCreate = runMetricDefsCreate;
|
|
68
|
+
exports.runMetricDefsUpdate = runMetricDefsUpdate;
|
|
69
|
+
exports.runMetricDefsSetStatus = runMetricDefsSetStatus;
|
|
70
|
+
exports.runMetricDefsDelete = runMetricDefsDelete;
|
|
71
|
+
exports.zonedMidnightMs = zonedMidnightMs;
|
|
72
|
+
exports.parseQueryRange = parseQueryRange;
|
|
73
|
+
exports.buildMetricAnalysisRequest = buildMetricAnalysisRequest;
|
|
74
|
+
exports.runMetricDefsQuery = runMetricDefsQuery;
|
|
75
|
+
exports.runExperimentMetricsQuery = runExperimentMetricsQuery;
|
|
59
76
|
exports.runExperimentResults = runExperimentResults;
|
|
60
77
|
exports.runExperimentLookup = runExperimentLookup;
|
|
61
78
|
exports.runExperimentVids = runExperimentVids;
|
|
@@ -71,6 +88,7 @@ exports.emitExperimentOutcome = emitExperimentOutcome;
|
|
|
71
88
|
exports.registerExperimentCommand = registerExperimentCommand;
|
|
72
89
|
const fs = __importStar(require("node:fs"));
|
|
73
90
|
const experimentClient_1 = require("../api/experimentClient");
|
|
91
|
+
const insightsClient_1 = require("../api/insightsClient");
|
|
74
92
|
const tokenAuth_1 = require("../auth/tokenAuth");
|
|
75
93
|
const environments_1 = require("../config/environments");
|
|
76
94
|
const resultPrinter_1 = require("../output/resultPrinter");
|
|
@@ -84,6 +102,8 @@ const PERCENT_PATTERN = /^\d{1,3}(?:\.\d{1,2})?$/;
|
|
|
84
102
|
const METRIC_KINDS = ['conversion', 'count', 'sum', 'avg', 'pct', 'retention'];
|
|
85
103
|
const METRIC_ROLES = ['metric', 'guardrail'];
|
|
86
104
|
const METRIC_DIRECTIONS = ['up', 'down'];
|
|
105
|
+
const METRIC_DEF_STATUSES = ['active', 'deprecated'];
|
|
106
|
+
const METRIC_DEF_NAME_MAX_CHARS = 80;
|
|
87
107
|
function isOutcome(value) {
|
|
88
108
|
return value !== null && typeof value === 'object' && 'ok' in value && typeof value.ok === 'boolean';
|
|
89
109
|
}
|
|
@@ -107,6 +127,7 @@ exports.defaultExperimentDeps = {
|
|
|
107
127
|
getStoredToken: storedToken,
|
|
108
128
|
markNeedsLogin: accountStore_1.markAccountNeedsLogin,
|
|
109
129
|
createClient: (apiOrigin) => new experimentClient_1.ExperimentClient(apiOrigin),
|
|
130
|
+
createInsightsClient: (apiOrigin) => new insightsClient_1.InsightsClient(apiOrigin),
|
|
110
131
|
readFile: (file) => fs.readFileSync(file),
|
|
111
132
|
};
|
|
112
133
|
function resolveAuth(deps) {
|
|
@@ -292,6 +313,12 @@ function failureResult(code, extra) {
|
|
|
292
313
|
result.current_version = record.version;
|
|
293
314
|
return result;
|
|
294
315
|
}
|
|
316
|
+
const METRIC_ERROR_HINTS = {
|
|
317
|
+
EXP_METRIC_IN_USE: 'an experiment uses this library metric; create a new one with `experiment metric-defs create` and deprecate this one',
|
|
318
|
+
EXP_METRIC_LOCKED: 'the experiment has started (only --core / --no-core can change), and definitions never change through an experiment',
|
|
319
|
+
EXP_METRIC_DEPRECATED: 'the library metric is deprecated; `experiment metric-defs activate` it or pick another',
|
|
320
|
+
EXP_METRIC_LIBRARY_REQUIRED: 'add metrics with --metric <library key>; create them with `experiment metric-defs create`',
|
|
321
|
+
};
|
|
295
322
|
function experimentFailure(outcome, action, key) {
|
|
296
323
|
switch (outcome.kind) {
|
|
297
324
|
case 'business_error': {
|
|
@@ -309,6 +336,9 @@ function experimentFailure(outcome, action, key) {
|
|
|
309
336
|
// (held + free in the layer; for reopen continue = reclaimable width).
|
|
310
337
|
message += ` (layer ${str(capacity.layer_key)}: at most ${pct(capacity.available_bp)} available, ${pct(capacity.requested_bp)} requested)`;
|
|
311
338
|
}
|
|
339
|
+
const hint = METRIC_ERROR_HINTS[outcome.code];
|
|
340
|
+
if (hint)
|
|
341
|
+
message += ` — ${hint}`;
|
|
312
342
|
const base = { ok: false, kind: 'business_error', publicCode: outcome.code, message };
|
|
313
343
|
return extra ? { ...base, result: extra } : base;
|
|
314
344
|
}
|
|
@@ -816,7 +846,12 @@ async function runExperimentOverridesSet(keyRaw, opts, requestId, deps = exports
|
|
|
816
846
|
const count = Array.isArray(data?.overrides) ? data.overrides.length : devices.length;
|
|
817
847
|
return ok(withScope(scope, { key, overrides: outcome.data }), `overrides replaced: ${count} device(s) · version ${str(data?.version)}`);
|
|
818
848
|
}
|
|
819
|
-
// ── metrics
|
|
849
|
+
// ── metrics (experiment side: selected from the project metric library) ──────────────────
|
|
850
|
+
function metricsResult(key, data) {
|
|
851
|
+
// Pass the server body through (`metrics`, `locked`, …); `key` names the experiment.
|
|
852
|
+
const record = asRecord(data);
|
|
853
|
+
return record ? { ...record, key } : { key, metrics: data };
|
|
854
|
+
}
|
|
820
855
|
async function runExperimentMetricsList(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
821
856
|
const key = validExperimentKey(keyRaw);
|
|
822
857
|
if (isOutcome(key))
|
|
@@ -830,20 +865,27 @@ async function runExperimentMetricsList(keyRaw, opts, deps = exports.defaultExpe
|
|
|
830
865
|
const outcome = await ctx.client.listMetrics(ctx.token, scope, key);
|
|
831
866
|
if (outcome.kind !== 'success')
|
|
832
867
|
return handleFailure(outcome, ctx.auth, deps, 'metrics list', key);
|
|
833
|
-
return ok(withScope(scope,
|
|
868
|
+
return ok(withScope(scope, metricsResult(key, outcome.data)), metricsSummary(outcome.data));
|
|
834
869
|
}
|
|
835
870
|
function metricsSummary(data) {
|
|
836
|
-
const
|
|
871
|
+
const record = asRecord(data);
|
|
872
|
+
const metrics = record?.metrics;
|
|
837
873
|
if (!Array.isArray(metrics))
|
|
838
874
|
return JSON.stringify(data, null, 2);
|
|
839
|
-
|
|
840
|
-
return 'no metrics';
|
|
841
|
-
return metrics.map((raw) => {
|
|
875
|
+
const lines = metrics.map((raw) => {
|
|
842
876
|
const metric = asRecord(raw) ?? {};
|
|
843
877
|
const core = metric.is_core === true ? ' core' : '';
|
|
844
878
|
const tolerance = typeof metric.tolerance_pct === 'number' ? ` tolerance ${metric.tolerance_pct}%` : '';
|
|
845
|
-
|
|
846
|
-
|
|
879
|
+
const library = metric.library_key === null || metric.library_key === undefined
|
|
880
|
+
? 'library -'
|
|
881
|
+
: `library ${str(metric.library_key)}${metric.library_status === 'deprecated' ? ' (deprecated)' : ''}`;
|
|
882
|
+
return `${str(metric.metric_key)}\t${str(metric.role)}${core}\t${str(metric.kind)}\t${str(metric.event_name)}\t${str(metric.direction)}${tolerance}\t${library}`;
|
|
883
|
+
});
|
|
884
|
+
if (lines.length === 0)
|
|
885
|
+
lines.push('no metrics');
|
|
886
|
+
if (record?.locked === true)
|
|
887
|
+
lines.push('locked: the experiment has started; only the core flag can change');
|
|
888
|
+
return lines.join('\n');
|
|
847
889
|
}
|
|
848
890
|
function pickEnum(raw, allowed, flag) {
|
|
849
891
|
if (raw === undefined)
|
|
@@ -853,58 +895,165 @@ function pickEnum(raw, allowed, flag) {
|
|
|
853
895
|
return usage(`${flag} must be one of ${allowed.join(', ')}`);
|
|
854
896
|
return value;
|
|
855
897
|
}
|
|
856
|
-
function
|
|
857
|
-
const
|
|
858
|
-
if (
|
|
859
|
-
return
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
return usage('--event is required');
|
|
898
|
+
function validMetricKey(raw, label = 'metric key') {
|
|
899
|
+
const key = raw?.trim() ?? '';
|
|
900
|
+
if (!experimentClient_1.EXPERIMENT_METRIC_KEY_PATTERN.test(key))
|
|
901
|
+
return usage(`${label} must match ^[a-z][a-z0-9_]{1,39}$`);
|
|
902
|
+
return key;
|
|
903
|
+
}
|
|
904
|
+
/** Per-experiment settings shared by `metrics add` (applied to every --metric) and `metrics update`. */
|
|
905
|
+
function buildMetricSettings(opts) {
|
|
865
906
|
const role = pickEnum(opts.role, METRIC_ROLES, '--role');
|
|
866
907
|
if (isOutcome(role))
|
|
867
908
|
return role;
|
|
868
909
|
const direction = pickEnum(opts.direction, METRIC_DIRECTIONS, '--direction');
|
|
869
910
|
if (isOutcome(direction))
|
|
870
911
|
return direction;
|
|
871
|
-
const
|
|
872
|
-
if (opts.metricKey !== undefined) {
|
|
873
|
-
const metricKey = validExperimentKey(opts.metricKey, '--metric-key');
|
|
874
|
-
if (isOutcome(metricKey))
|
|
875
|
-
return metricKey;
|
|
876
|
-
metric.metric_key = metricKey;
|
|
877
|
-
}
|
|
912
|
+
const settings = {};
|
|
878
913
|
if (role)
|
|
879
|
-
|
|
880
|
-
if (opts.core === true)
|
|
881
|
-
metric.is_core = true;
|
|
914
|
+
settings.role = role;
|
|
882
915
|
if (direction)
|
|
883
|
-
|
|
884
|
-
if (opts.tolerance !== undefined) {
|
|
885
|
-
const tolerance = Number(opts.tolerance.trim());
|
|
886
|
-
if (!/^\d+(?:\.\d+)?$/.test(opts.tolerance.trim()) || !Number.isFinite(tolerance)) {
|
|
887
|
-
return usage('--tolerance must be a non-negative percentage, e.g. 5 or 2.5');
|
|
888
|
-
}
|
|
889
|
-
metric.tolerance_pct = tolerance;
|
|
890
|
-
}
|
|
916
|
+
settings.direction = direction;
|
|
891
917
|
const window = parseBoundedInt(opts.windowDays, '--window-days', 1, 60);
|
|
892
918
|
if (isOutcome(window))
|
|
893
919
|
return window;
|
|
894
920
|
if (window !== undefined)
|
|
895
|
-
|
|
921
|
+
settings.window_days = window;
|
|
922
|
+
if (opts.tolerance !== undefined) {
|
|
923
|
+
const raw = opts.tolerance.trim();
|
|
924
|
+
const tolerance = Number(raw);
|
|
925
|
+
if (!/^\d+(?:\.\d+)?$/.test(raw) || !Number.isFinite(tolerance)) {
|
|
926
|
+
return usage('--tolerance must be a non-negative percentage, e.g. 5 or 2.5');
|
|
927
|
+
}
|
|
928
|
+
settings.tolerance_pct = tolerance;
|
|
929
|
+
}
|
|
930
|
+
if (opts.core !== undefined)
|
|
931
|
+
settings.is_core = opts.core;
|
|
932
|
+
return settings;
|
|
933
|
+
}
|
|
934
|
+
/** `--metric a --metric b,c` → [a, b, c]; duplicates are a usage error. */
|
|
935
|
+
function parseMetricKeys(raw) {
|
|
936
|
+
const keys = [];
|
|
937
|
+
for (const item of raw ?? []) {
|
|
938
|
+
for (const part of item.split(',')) {
|
|
939
|
+
const key = validMetricKey(part, '--metric');
|
|
940
|
+
if (isOutcome(key))
|
|
941
|
+
return key;
|
|
942
|
+
if (keys.includes(key))
|
|
943
|
+
return usage(`duplicate --metric ${key}`);
|
|
944
|
+
keys.push(key);
|
|
945
|
+
}
|
|
946
|
+
}
|
|
947
|
+
if (keys.length === 0)
|
|
948
|
+
return usage('--metric <library key> is required (repeatable or comma-separated); see `supercli experiment metric-defs list`');
|
|
949
|
+
return keys;
|
|
950
|
+
}
|
|
951
|
+
function buildMetricsAddBody(opts) {
|
|
952
|
+
const keys = parseMetricKeys(opts.metric);
|
|
953
|
+
if (isOutcome(keys))
|
|
954
|
+
return keys;
|
|
955
|
+
// `--core` on add only ever sets the flag; `false` is the server default.
|
|
956
|
+
const settings = buildMetricSettings({ ...opts, core: opts.core === true ? true : undefined });
|
|
957
|
+
if (isOutcome(settings))
|
|
958
|
+
return settings;
|
|
959
|
+
return { metrics: keys.map((library_key) => ({ library_key, ...settings })) };
|
|
960
|
+
}
|
|
961
|
+
async function runExperimentMetricsAdd(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
962
|
+
const key = validExperimentKey(keyRaw);
|
|
963
|
+
if (isOutcome(key))
|
|
964
|
+
return key;
|
|
965
|
+
const body = buildMetricsAddBody(opts);
|
|
966
|
+
if (isOutcome(body))
|
|
967
|
+
return body;
|
|
968
|
+
const scope = resolveEnvScope(opts);
|
|
969
|
+
if (isOutcome(scope))
|
|
970
|
+
return scope;
|
|
971
|
+
const ctx = begin(deps, requestId);
|
|
972
|
+
if (isOutcome(ctx))
|
|
973
|
+
return ctx;
|
|
974
|
+
const outcome = await ctx.client.addMetrics(ctx.token, scope, key, body);
|
|
975
|
+
if (outcome.kind !== 'success')
|
|
976
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics add', key);
|
|
977
|
+
return ok(withScope(scope, metricsResult(key, outcome.data)), metricsSummary(outcome.data));
|
|
978
|
+
}
|
|
979
|
+
async function runExperimentMetricsUpdate(keyRaw, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
980
|
+
const key = validExperimentKey(keyRaw);
|
|
981
|
+
if (isOutcome(key))
|
|
982
|
+
return key;
|
|
983
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
984
|
+
if (isOutcome(metricKey))
|
|
985
|
+
return metricKey;
|
|
986
|
+
const body = buildMetricSettings(opts);
|
|
987
|
+
if (isOutcome(body))
|
|
988
|
+
return body;
|
|
989
|
+
if (Object.keys(body).length === 0) {
|
|
990
|
+
return usage('nothing to update — pass at least one of --role, --direction, --window-days, --tolerance, --core, --no-core');
|
|
991
|
+
}
|
|
992
|
+
const scope = resolveEnvScope(opts);
|
|
993
|
+
if (isOutcome(scope))
|
|
994
|
+
return scope;
|
|
995
|
+
const ctx = begin(deps, requestId);
|
|
996
|
+
if (isOutcome(ctx))
|
|
997
|
+
return ctx;
|
|
998
|
+
const outcome = await ctx.client.patchMetric(ctx.token, scope, key, metricKey, body);
|
|
999
|
+
if (outcome.kind !== 'success')
|
|
1000
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics update', key);
|
|
1001
|
+
return ok(withScope(scope, metricsResult(key, outcome.data)), `updated ${metricKey}\n${metricsSummary(outcome.data)}`);
|
|
1002
|
+
}
|
|
1003
|
+
async function runExperimentMetricsRemove(keyRaw, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1004
|
+
const key = validExperimentKey(keyRaw);
|
|
1005
|
+
if (isOutcome(key))
|
|
1006
|
+
return key;
|
|
1007
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
1008
|
+
if (isOutcome(metricKey))
|
|
1009
|
+
return metricKey;
|
|
1010
|
+
const scope = resolveEnvScope(opts);
|
|
1011
|
+
if (isOutcome(scope))
|
|
1012
|
+
return scope;
|
|
1013
|
+
const ctx = begin(deps, requestId);
|
|
1014
|
+
if (isOutcome(ctx))
|
|
1015
|
+
return ctx;
|
|
1016
|
+
const outcome = await ctx.client.removeMetric(ctx.token, scope, key, metricKey);
|
|
1017
|
+
if (outcome.kind !== 'success')
|
|
1018
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics remove', key);
|
|
1019
|
+
return ok(withScope(scope, { ...metricsResult(key, outcome.data), removed: metricKey }), `removed ${metricKey}\n${metricsSummary(outcome.data)}`);
|
|
1020
|
+
}
|
|
1021
|
+
/**
|
|
1022
|
+
* Definition fields of a library metric. On create `--kind` / `--event` are required and the
|
|
1023
|
+
* kind-specific fields are checked; on update every field is optional (the server merges and
|
|
1024
|
+
* re-validates, and rejects definition changes on a used metric with EXP_METRIC_IN_USE).
|
|
1025
|
+
*/
|
|
1026
|
+
function buildMetricDefinition(opts, deps, mode) {
|
|
1027
|
+
const kind = pickEnum(opts.kind, METRIC_KINDS, '--kind');
|
|
1028
|
+
if (isOutcome(kind))
|
|
1029
|
+
return kind;
|
|
1030
|
+
if (mode === 'create' && !kind)
|
|
1031
|
+
return usage(`--kind is required (${METRIC_KINDS.join(', ')})`);
|
|
1032
|
+
const def = {};
|
|
1033
|
+
if (kind)
|
|
1034
|
+
def.kind = kind;
|
|
1035
|
+
if (opts.event !== undefined || mode === 'create') {
|
|
1036
|
+
const event = opts.event?.trim();
|
|
1037
|
+
if (!event)
|
|
1038
|
+
return usage('--event is required and must not be empty');
|
|
1039
|
+
def.event_name = event;
|
|
1040
|
+
}
|
|
896
1041
|
const retentionDay = parseBoundedInt(opts.retentionDay, '--retention-day', 1, 30);
|
|
897
1042
|
if (isOutcome(retentionDay))
|
|
898
1043
|
return retentionDay;
|
|
899
1044
|
if (retentionDay !== undefined)
|
|
900
|
-
|
|
901
|
-
if (kind === 'retention' && retentionDay === undefined)
|
|
1045
|
+
def.retention_day = retentionDay;
|
|
1046
|
+
if (mode === 'create' && kind === 'retention' && retentionDay === undefined) {
|
|
902
1047
|
return usage('--retention-day is required for --kind retention (1-30)');
|
|
1048
|
+
}
|
|
903
1049
|
const percentile = parseBoundedInt(opts.percentile, '--percentile', 1, 99);
|
|
904
1050
|
if (isOutcome(percentile))
|
|
905
1051
|
return percentile;
|
|
906
1052
|
if (percentile !== undefined)
|
|
907
|
-
|
|
1053
|
+
def.percentile = percentile;
|
|
1054
|
+
if (mode === 'create' && kind === 'pct' && percentile === undefined) {
|
|
1055
|
+
return usage('--percentile is required for --kind pct (1-99)');
|
|
1056
|
+
}
|
|
908
1057
|
if (opts.property !== undefined) {
|
|
909
1058
|
const name = opts.property.trim();
|
|
910
1059
|
const valueType = opts.propertyType?.trim() ?? 'float';
|
|
@@ -912,10 +1061,17 @@ function buildMetricInput(opts, deps) {
|
|
|
912
1061
|
return usage('--property must name a numeric event property');
|
|
913
1062
|
if (valueType !== 'int' && valueType !== 'float')
|
|
914
1063
|
return usage('--property-type must be int or float');
|
|
915
|
-
|
|
1064
|
+
const columnKind = opts.propertyColumn?.trim();
|
|
1065
|
+
if (columnKind !== undefined && columnKind !== 'dynamic' && columnKind !== 'fixed') {
|
|
1066
|
+
return usage('--property-column must be dynamic or fixed');
|
|
1067
|
+
}
|
|
1068
|
+
def.property = { name, value_type: valueType, ...(columnKind ? { column_kind: columnKind } : {}) };
|
|
1069
|
+
}
|
|
1070
|
+
else if (opts.propertyType !== undefined || opts.propertyColumn !== undefined) {
|
|
1071
|
+
return usage('--property-type / --property-column need --property');
|
|
916
1072
|
}
|
|
917
|
-
if ((kind === 'sum' || kind === 'avg' || kind === 'pct') &&
|
|
918
|
-
return usage(`--property is required for --kind ${kind}`);
|
|
1073
|
+
if (mode === 'create' && (kind === 'sum' || kind === 'avg' || kind === 'pct') && def.property === undefined) {
|
|
1074
|
+
return usage(`--property is required for --kind ${String(kind)}`);
|
|
919
1075
|
}
|
|
920
1076
|
if (opts.filters !== undefined) {
|
|
921
1077
|
const filters = readJsonSource(opts.filters, '--filters', deps);
|
|
@@ -923,45 +1079,323 @@ function buildMetricInput(opts, deps) {
|
|
|
923
1079
|
return filters;
|
|
924
1080
|
if (!Array.isArray(filters.value))
|
|
925
1081
|
return usage('--filters must be a JSON array of {name, value_type, operator, values}');
|
|
926
|
-
|
|
1082
|
+
def.filters = filters.value;
|
|
927
1083
|
}
|
|
928
|
-
return
|
|
1084
|
+
return def;
|
|
929
1085
|
}
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
1086
|
+
function metricDefText(opts, body) {
|
|
1087
|
+
if (opts.name !== undefined) {
|
|
1088
|
+
const name = opts.name.trim();
|
|
1089
|
+
if (!name)
|
|
1090
|
+
return usage('--name must not be empty');
|
|
1091
|
+
if ([...name].length > METRIC_DEF_NAME_MAX_CHARS)
|
|
1092
|
+
return usage(`--name must be at most ${METRIC_DEF_NAME_MAX_CHARS} characters`);
|
|
1093
|
+
body.name = name;
|
|
1094
|
+
}
|
|
1095
|
+
const description = validDescription(opts.description, false);
|
|
1096
|
+
if (isOutcome(description))
|
|
1097
|
+
return description;
|
|
1098
|
+
if (description !== undefined)
|
|
1099
|
+
body.description = description;
|
|
1100
|
+
const direction = pickEnum(opts.direction, METRIC_DIRECTIONS, '--direction');
|
|
1101
|
+
if (isOutcome(direction))
|
|
1102
|
+
return direction;
|
|
1103
|
+
if (direction)
|
|
1104
|
+
body.direction = direction;
|
|
1105
|
+
return undefined;
|
|
1106
|
+
}
|
|
1107
|
+
function buildMetricDefCreateBody(opts, deps) {
|
|
1108
|
+
const body = {};
|
|
1109
|
+
if (opts.key !== undefined) {
|
|
1110
|
+
const key = validMetricKey(opts.key, '--key');
|
|
1111
|
+
if (isOutcome(key))
|
|
1112
|
+
return key;
|
|
1113
|
+
body.metric_key = key;
|
|
1114
|
+
}
|
|
1115
|
+
const text = metricDefText(opts, body);
|
|
1116
|
+
if (text)
|
|
1117
|
+
return text;
|
|
1118
|
+
const def = buildMetricDefinition(opts, deps, 'create');
|
|
1119
|
+
if (isOutcome(def))
|
|
1120
|
+
return def;
|
|
1121
|
+
return { ...body, ...def };
|
|
1122
|
+
}
|
|
1123
|
+
function buildMetricDefUpdateBody(opts, deps) {
|
|
1124
|
+
const body = {};
|
|
1125
|
+
const text = metricDefText(opts, body);
|
|
1126
|
+
if (text)
|
|
1127
|
+
return text;
|
|
1128
|
+
const def = buildMetricDefinition(opts, deps, 'update');
|
|
1129
|
+
if (isOutcome(def))
|
|
1130
|
+
return def;
|
|
1131
|
+
const merged = { ...body, ...def };
|
|
1132
|
+
if (Object.keys(merged).length === 0) {
|
|
1133
|
+
return usage('nothing to update — pass at least one of --name, --description, --direction, --kind, --event, --property, --percentile, --retention-day, --filters');
|
|
1134
|
+
}
|
|
1135
|
+
return merged;
|
|
1136
|
+
}
|
|
1137
|
+
function metricDefLine(raw) {
|
|
1138
|
+
const metric = asRecord(raw) ?? {};
|
|
1139
|
+
return `${str(metric.metric_key)}\t${str(metric.status)}\t${str(metric.kind)}\t${str(metric.event_name)}\t${str(metric.direction)}\tused by ${str(metric.usage_count)}\t${str(metric.name)}`;
|
|
1140
|
+
}
|
|
1141
|
+
function metricDefDetail(raw) {
|
|
1142
|
+
const lines = [metricDefLine(raw)];
|
|
1143
|
+
const usedBy = asRecord(raw)?.used_by;
|
|
1144
|
+
if (Array.isArray(usedBy)) {
|
|
1145
|
+
for (const item of usedBy) {
|
|
1146
|
+
const row = asRecord(item) ?? {};
|
|
1147
|
+
lines.push(` - ${str(row.env)} ${str(row.experiment_key)} (${str(row.status)}) ${str(row.experiment_name)}`);
|
|
1148
|
+
}
|
|
1149
|
+
}
|
|
1150
|
+
return lines.join('\n');
|
|
1151
|
+
}
|
|
1152
|
+
function metricDefsSummary(data) {
|
|
1153
|
+
const metrics = asRecord(data)?.metrics;
|
|
1154
|
+
if (!Array.isArray(metrics))
|
|
1155
|
+
return JSON.stringify(data, null, 2);
|
|
1156
|
+
return metrics.map(metricDefLine).join('\n') || 'no library metrics';
|
|
1157
|
+
}
|
|
1158
|
+
async function runMetricDefsList(opts, deps = exports.defaultExperimentDeps) {
|
|
1159
|
+
const status = pickEnum(opts.status, METRIC_DEF_STATUSES, '--status');
|
|
1160
|
+
if (isOutcome(status))
|
|
1161
|
+
return status;
|
|
1162
|
+
const project = resolveProject(opts);
|
|
1163
|
+
if (isOutcome(project))
|
|
1164
|
+
return project;
|
|
1165
|
+
const ctx = begin(deps);
|
|
1166
|
+
if (isOutcome(ctx))
|
|
1167
|
+
return ctx;
|
|
1168
|
+
const outcome = await ctx.client.listMetricDefs(ctx.token, project, status);
|
|
1169
|
+
if (outcome.kind !== 'success')
|
|
1170
|
+
return handleFailure(outcome, ctx.auth, deps, 'metric-defs list');
|
|
1171
|
+
const record = asRecord(outcome.data);
|
|
1172
|
+
return ok(withScope(project, record ? { ...record } : { metrics: outcome.data }), metricDefsSummary(outcome.data));
|
|
1173
|
+
}
|
|
1174
|
+
async function runMetricDefsGet(metricKeyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
1175
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
1176
|
+
if (isOutcome(metricKey))
|
|
1177
|
+
return metricKey;
|
|
1178
|
+
const project = resolveProject(opts);
|
|
1179
|
+
if (isOutcome(project))
|
|
1180
|
+
return project;
|
|
1181
|
+
const ctx = begin(deps);
|
|
1182
|
+
if (isOutcome(ctx))
|
|
1183
|
+
return ctx;
|
|
1184
|
+
const outcome = await ctx.client.getMetricDef(ctx.token, project, metricKey);
|
|
1185
|
+
if (outcome.kind !== 'success')
|
|
1186
|
+
return handleFailure(outcome, ctx.auth, deps, 'metric-defs get');
|
|
1187
|
+
return ok(withScope(project, { metric: outcome.data }), metricDefDetail(outcome.data));
|
|
1188
|
+
}
|
|
1189
|
+
async function runMetricDefsCreate(opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1190
|
+
const body = buildMetricDefCreateBody(opts, deps);
|
|
1191
|
+
if (isOutcome(body))
|
|
1192
|
+
return body;
|
|
1193
|
+
const project = resolveProject(opts);
|
|
1194
|
+
if (isOutcome(project))
|
|
1195
|
+
return project;
|
|
940
1196
|
const ctx = begin(deps, requestId);
|
|
941
1197
|
if (isOutcome(ctx))
|
|
942
1198
|
return ctx;
|
|
943
|
-
const outcome = await ctx.client.
|
|
1199
|
+
const outcome = await ctx.client.createMetricDef(ctx.token, project, body);
|
|
944
1200
|
if (outcome.kind !== 'success')
|
|
945
|
-
return handleFailure(outcome, ctx.auth, deps, '
|
|
946
|
-
return ok(withScope(
|
|
1201
|
+
return handleFailure(outcome, ctx.auth, deps, 'metric-defs create');
|
|
1202
|
+
return ok(withScope(project, { metric: outcome.data }), `created library metric\n${metricDefLine(outcome.data)}`);
|
|
947
1203
|
}
|
|
948
|
-
async function
|
|
1204
|
+
async function patchMetricDef(metricKeyRaw, opts, body, action, verb, requestId, deps) {
|
|
1205
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
1206
|
+
if (isOutcome(metricKey))
|
|
1207
|
+
return metricKey;
|
|
1208
|
+
if (isOutcome(body))
|
|
1209
|
+
return body;
|
|
1210
|
+
const project = resolveProject(opts);
|
|
1211
|
+
if (isOutcome(project))
|
|
1212
|
+
return project;
|
|
1213
|
+
const ctx = begin(deps, requestId);
|
|
1214
|
+
if (isOutcome(ctx))
|
|
1215
|
+
return ctx;
|
|
1216
|
+
const outcome = await ctx.client.updateMetricDef(ctx.token, project, metricKey, body);
|
|
1217
|
+
if (outcome.kind !== 'success')
|
|
1218
|
+
return handleFailure(outcome, ctx.auth, deps, action);
|
|
1219
|
+
return ok(withScope(project, { metric: outcome.data }), `${verb}\n${metricDefLine(outcome.data)}`);
|
|
1220
|
+
}
|
|
1221
|
+
function runMetricDefsUpdate(metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1222
|
+
return patchMetricDef(metricKeyRaw, opts, buildMetricDefUpdateBody(opts, deps), 'metric-defs update', 'updated library metric', requestId, deps);
|
|
1223
|
+
}
|
|
1224
|
+
function runMetricDefsSetStatus(status, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1225
|
+
const action = status === 'deprecated' ? 'deprecate' : 'activate';
|
|
1226
|
+
return patchMetricDef(metricKeyRaw, opts, { status }, `metric-defs ${action}`, `${action}d library metric`, requestId, deps);
|
|
1227
|
+
}
|
|
1228
|
+
async function runMetricDefsDelete(metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
|
|
1229
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
1230
|
+
if (isOutcome(metricKey))
|
|
1231
|
+
return metricKey;
|
|
1232
|
+
const project = resolveProject(opts);
|
|
1233
|
+
if (isOutcome(project))
|
|
1234
|
+
return project;
|
|
1235
|
+
const ctx = begin(deps, requestId);
|
|
1236
|
+
if (isOutcome(ctx))
|
|
1237
|
+
return ctx;
|
|
1238
|
+
const outcome = await ctx.client.deleteMetricDef(ctx.token, project, metricKey);
|
|
1239
|
+
if (outcome.kind !== 'success')
|
|
1240
|
+
return handleFailure(outcome, ctx.auth, deps, 'metric-defs delete');
|
|
1241
|
+
// DELETE returns the remaining `{ metrics, limit }`; passed through.
|
|
1242
|
+
const record = asRecord(outcome.data);
|
|
1243
|
+
return ok(withScope(project, { ...(record ?? { metrics: outcome.data }), deleted: true, metric_key: metricKey }), `deleted library metric ${metricKey}`);
|
|
1244
|
+
}
|
|
1245
|
+
// ── metric → analysis query (reuses the console analytics routes behind `analytics events-query` / `retention`) ──
|
|
1246
|
+
const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
|
|
1247
|
+
const DAY_MS = 86_400_000;
|
|
1248
|
+
exports.METRIC_QUERY_DEFAULT_TIME_ZONE = 'Asia/Shanghai';
|
|
1249
|
+
/** Experiment metric kind → event-analysis algorithm (same mapping as the console). */
|
|
1250
|
+
const ANALYTICS_KIND = { conversion: 'uv', count: 'pv', sum: 'sum', avg: 'avg', pct: 'pct' };
|
|
1251
|
+
function zoneOffsetMs(timeZone, utcMs) {
|
|
1252
|
+
const parts = new Intl.DateTimeFormat('en-US', {
|
|
1253
|
+
timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
|
|
1254
|
+
}).formatToParts(new Date(utcMs));
|
|
1255
|
+
const get = (type) => Number(parts.find((part) => part.type === type)?.value);
|
|
1256
|
+
return Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'), get('second')) - utcMs;
|
|
1257
|
+
}
|
|
1258
|
+
/** Midnight of a calendar day in an IANA zone, as epoch ms. */
|
|
1259
|
+
function zonedMidnightMs(year, month, day, timeZone) {
|
|
1260
|
+
const wall = Date.UTC(year, month - 1, day);
|
|
1261
|
+
const first = wall - zoneOffsetMs(timeZone, wall);
|
|
1262
|
+
return wall - zoneOffsetMs(timeZone, first);
|
|
1263
|
+
}
|
|
1264
|
+
/** `--from` / `--to` are inclusive calendar days in `--time-zone`; the end is the next midnight (exclusive). */
|
|
1265
|
+
function parseQueryRange(opts) {
|
|
1266
|
+
const timeZone = opts.timeZone?.trim() || exports.METRIC_QUERY_DEFAULT_TIME_ZONE;
|
|
1267
|
+
try {
|
|
1268
|
+
new Intl.DateTimeFormat('en-US', { timeZone });
|
|
1269
|
+
}
|
|
1270
|
+
catch {
|
|
1271
|
+
return usage(`--time-zone ${JSON.stringify(timeZone)} is not an IANA time zone`);
|
|
1272
|
+
}
|
|
1273
|
+
const days = [];
|
|
1274
|
+
for (const [flag, raw] of [['--from', opts.from], ['--to', opts.to]]) {
|
|
1275
|
+
const match = DATE_PATTERN.exec(raw?.trim() ?? '');
|
|
1276
|
+
const parts = match ? [Number(match[1]), Number(match[2]), Number(match[3])] : [];
|
|
1277
|
+
const check = match ? new Date(Date.UTC(parts[0], parts[1] - 1, parts[2])) : undefined;
|
|
1278
|
+
if (!check || check.getUTCMonth() !== parts[1] - 1 || check.getUTCDate() !== parts[2]) {
|
|
1279
|
+
return usage(`${flag} is required and must be a date YYYY-MM-DD`);
|
|
1280
|
+
}
|
|
1281
|
+
days.push(parts);
|
|
1282
|
+
}
|
|
1283
|
+
const start = zonedMidnightMs(days[0][0], days[0][1], days[0][2], timeZone);
|
|
1284
|
+
const next = new Date(Date.UTC(days[1][0], days[1][1] - 1, days[1][2]) + DAY_MS);
|
|
1285
|
+
const end = zonedMidnightMs(next.getUTCFullYear(), next.getUTCMonth() + 1, next.getUTCDate(), timeZone);
|
|
1286
|
+
if (end <= start)
|
|
1287
|
+
return usage('--to must not be before --from');
|
|
1288
|
+
return { start_time_ms: start, end_time_ms: end, time_zone: timeZone };
|
|
1289
|
+
}
|
|
1290
|
+
/**
|
|
1291
|
+
* Build the analytics request body for a metric definition (library or experiment copy):
|
|
1292
|
+
* retention → `/analytics/retention` (n_days = retention_day, all users); every other kind →
|
|
1293
|
+
* one event with one algorithm in `/analytics/events/query`, filters attached to the event.
|
|
1294
|
+
* `spid` / `env` are filled in when the query is sent.
|
|
1295
|
+
*/
|
|
1296
|
+
function buildMetricAnalysisRequest(definition, range) {
|
|
1297
|
+
const def = asRecord(definition);
|
|
1298
|
+
const kind = typeof def?.kind === 'string' ? def.kind : '';
|
|
1299
|
+
const eventName = typeof def?.event_name === 'string' ? def.event_name : '';
|
|
1300
|
+
if (!def || !eventName)
|
|
1301
|
+
return { ok: false, kind: 'infra_error', message: 'metric definition is missing kind / event_name' };
|
|
1302
|
+
const filters = Array.isArray(def.filters) ? def.filters : [];
|
|
1303
|
+
if (kind === 'retention') {
|
|
1304
|
+
return {
|
|
1305
|
+
command: 'retention',
|
|
1306
|
+
request: {
|
|
1307
|
+
event_name: eventName,
|
|
1308
|
+
user_type: 'all',
|
|
1309
|
+
n_days: typeof def.retention_day === 'number' ? def.retention_day : 7,
|
|
1310
|
+
filters,
|
|
1311
|
+
...range,
|
|
1312
|
+
},
|
|
1313
|
+
};
|
|
1314
|
+
}
|
|
1315
|
+
const analyticsKind = ANALYTICS_KIND[kind];
|
|
1316
|
+
if (!analyticsKind)
|
|
1317
|
+
return { ok: false, kind: 'infra_error', message: `metric kind ${JSON.stringify(kind)} has no analysis mapping` };
|
|
1318
|
+
const metric = { kind: analyticsKind };
|
|
1319
|
+
if (analyticsKind === 'sum' || analyticsKind === 'avg' || analyticsKind === 'pct')
|
|
1320
|
+
metric.property = def.property ?? null;
|
|
1321
|
+
if (analyticsKind === 'pct')
|
|
1322
|
+
metric.percentile = def.percentile ?? null;
|
|
1323
|
+
return {
|
|
1324
|
+
command: 'events-query',
|
|
1325
|
+
request: { level: 'day', ...range, events: [{ event_name: eventName, metrics: [metric], filters }] },
|
|
1326
|
+
};
|
|
1327
|
+
}
|
|
1328
|
+
async function runMetricAnalysis(ctx, deps, scope, label, definition, range, printSpec, action) {
|
|
1329
|
+
const built = buildMetricAnalysisRequest(definition, range);
|
|
1330
|
+
if (isOutcome(built))
|
|
1331
|
+
return built;
|
|
1332
|
+
if (printSpec) {
|
|
1333
|
+
return ok(withScope(scope, { ...label, analysis: built.command, request: built.request }), `${JSON.stringify(built.request, null, 2)}\n\nsave it as a file and run: supercli analytics ${built.command} --config <super.json> --env <env> --file <file>`);
|
|
1334
|
+
}
|
|
1335
|
+
const insights = (deps.createInsightsClient ?? ((origin) => new insightsClient_1.InsightsClient(origin)))(ctx.auth.apiOrigin);
|
|
1336
|
+
const payload = { ...built.request, spid: scope.spid, ...(scope.env ? { env: scope.env } : {}) };
|
|
1337
|
+
const outcome = built.command === 'retention'
|
|
1338
|
+
? await insights.retention({ token: ctx.auth.token }, payload)
|
|
1339
|
+
: await insights.eventsQuery({ token: ctx.auth.token }, payload);
|
|
1340
|
+
if (outcome.kind !== 'success')
|
|
1341
|
+
return handleFailure(outcome, ctx.auth, deps, action);
|
|
1342
|
+
const resultKey = built.command === 'retention' ? 'retention' : 'query';
|
|
1343
|
+
return ok(withScope(scope, { ...label, analysis: built.command, request: built.request, [resultKey]: outcome.data }), JSON.stringify(outcome.data, null, 2));
|
|
1344
|
+
}
|
|
1345
|
+
function optionalEnv(raw) {
|
|
1346
|
+
if (raw === undefined)
|
|
1347
|
+
return undefined;
|
|
1348
|
+
const env = raw.trim();
|
|
1349
|
+
if (!ENV_NAME_PATTERN.test(env))
|
|
1350
|
+
return usage('--env must be 1-10 lowercase letters or digits');
|
|
1351
|
+
return env;
|
|
1352
|
+
}
|
|
1353
|
+
async function runMetricDefsQuery(metricKeyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
1354
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
1355
|
+
if (isOutcome(metricKey))
|
|
1356
|
+
return metricKey;
|
|
1357
|
+
const range = parseQueryRange(opts);
|
|
1358
|
+
if (isOutcome(range))
|
|
1359
|
+
return range;
|
|
1360
|
+
const env = optionalEnv(opts.env);
|
|
1361
|
+
if (isOutcome(env))
|
|
1362
|
+
return env;
|
|
1363
|
+
const project = resolveProject(opts);
|
|
1364
|
+
if (isOutcome(project))
|
|
1365
|
+
return project;
|
|
1366
|
+
const ctx = begin(deps);
|
|
1367
|
+
if (isOutcome(ctx))
|
|
1368
|
+
return ctx;
|
|
1369
|
+
const outcome = await ctx.client.getMetricDef(ctx.token, project, metricKey);
|
|
1370
|
+
if (outcome.kind !== 'success')
|
|
1371
|
+
return handleFailure(outcome, ctx.auth, deps, 'metric-defs query');
|
|
1372
|
+
return runMetricAnalysis(ctx, deps, { ...project, ...(env ? { env } : {}) }, { metric_key: metricKey }, outcome.data, range, opts.printSpec === true, 'metric-defs query');
|
|
1373
|
+
}
|
|
1374
|
+
async function runExperimentMetricsQuery(keyRaw, metricKeyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
949
1375
|
const key = validExperimentKey(keyRaw);
|
|
950
1376
|
if (isOutcome(key))
|
|
951
1377
|
return key;
|
|
952
|
-
const metricKey = metricKeyRaw
|
|
953
|
-
if (
|
|
954
|
-
return
|
|
1378
|
+
const metricKey = validMetricKey(metricKeyRaw);
|
|
1379
|
+
if (isOutcome(metricKey))
|
|
1380
|
+
return metricKey;
|
|
1381
|
+
const range = parseQueryRange(opts);
|
|
1382
|
+
if (isOutcome(range))
|
|
1383
|
+
return range;
|
|
955
1384
|
const scope = resolveEnvScope(opts);
|
|
956
1385
|
if (isOutcome(scope))
|
|
957
1386
|
return scope;
|
|
958
|
-
const ctx = begin(deps
|
|
1387
|
+
const ctx = begin(deps);
|
|
959
1388
|
if (isOutcome(ctx))
|
|
960
1389
|
return ctx;
|
|
961
|
-
const outcome = await ctx.client.
|
|
1390
|
+
const outcome = await ctx.client.listMetrics(ctx.token, scope, key);
|
|
962
1391
|
if (outcome.kind !== 'success')
|
|
963
|
-
return handleFailure(outcome, ctx.auth, deps, 'metrics
|
|
964
|
-
|
|
1392
|
+
return handleFailure(outcome, ctx.auth, deps, 'metrics query', key);
|
|
1393
|
+
const metrics = asRecord(outcome.data)?.metrics;
|
|
1394
|
+
const found = Array.isArray(metrics) ? metrics.find((raw) => asRecord(raw)?.metric_key === metricKey) : undefined;
|
|
1395
|
+
if (!found) {
|
|
1396
|
+
return { ok: false, kind: 'business_error', publicCode: 'EXP_METRIC_NOT_FOUND', message: `experiment ${key} has no metric ${metricKey} — see \`supercli experiment metrics list ${key}\`` };
|
|
1397
|
+
}
|
|
1398
|
+
return runMetricAnalysis(ctx, deps, scope, { key, metric_key: metricKey }, found, range, opts.printSpec === true, 'metrics query');
|
|
965
1399
|
}
|
|
966
1400
|
async function runExperimentResults(keyRaw, opts, deps = exports.defaultExperimentDeps) {
|
|
967
1401
|
const key = validExperimentKey(keyRaw);
|
|
@@ -1298,23 +1732,74 @@ function registerExperimentCommand(program, deps = exports.defaultExperimentDeps
|
|
|
1298
1732
|
const metrics = experiment.command('metrics').description('Experiment metrics and guardrails.');
|
|
1299
1733
|
envLeaf(metrics, 'list <key>', 'List metrics and guardrails.')
|
|
1300
1734
|
.action(act((_p, key, opts) => runExperimentMetricsList(key, opts, deps)));
|
|
1301
|
-
envLeaf(metrics, 'add <key>', 'Add
|
|
1302
|
-
.
|
|
1303
|
-
.requiredOption('--event <name>', 'event name')
|
|
1304
|
-
.option('--metric-key <key>', 'metric key (derived from kind + event when omitted)')
|
|
1735
|
+
envLeaf(metrics, 'add <key>', 'Add metrics or guardrails from the project metric library (does not change the experiment version).')
|
|
1736
|
+
.option('--metric <libraryKey>', 'library metric key (repeatable or comma-separated); see `experiment metric-defs list`', collect, [])
|
|
1305
1737
|
.option('--role <role>', 'metric (default) | guardrail')
|
|
1306
1738
|
.option('--core', 'mark as the core metric')
|
|
1307
|
-
.option('--direction <dir>', 'up | down:
|
|
1739
|
+
.option('--direction <dir>', 'up | down (default: the library metric direction)')
|
|
1308
1740
|
.option('--tolerance <percent>', 'guardrail tolerance in percent')
|
|
1309
1741
|
.option('--window-days <n>', 'observation window after exposure, 1-60 (default 7)')
|
|
1310
|
-
.option('--retention-day <n>', 'retention day N for --kind retention, 1-30')
|
|
1311
|
-
.option('--property <name>', 'numeric property for sum / avg / pct')
|
|
1312
|
-
.option('--property-type <type>', 'int | float (default float)')
|
|
1313
|
-
.option('--percentile <n>', 'percentile for --kind pct, 1-99')
|
|
1314
|
-
.option('--filters <json|@file>', 'JSON array of event filters {name, value_type, operator, values}')
|
|
1315
1742
|
.action(act((printer, key, opts) => runExperimentMetricsAdd(key, opts, printer.requestId, deps)));
|
|
1743
|
+
envLeaf(metrics, 'update <key> <metricKey>', 'Change role / direction / window / tolerance (draft only) or the core flag (any time).')
|
|
1744
|
+
.option('--role <role>', 'metric | guardrail')
|
|
1745
|
+
.option('--core', 'mark as the core metric')
|
|
1746
|
+
.option('--no-core', 'clear the core mark')
|
|
1747
|
+
.option('--direction <dir>', 'up | down')
|
|
1748
|
+
.option('--tolerance <percent>', 'guardrail tolerance in percent')
|
|
1749
|
+
.option('--window-days <n>', 'observation window after exposure, 1-60')
|
|
1750
|
+
.action(act((printer, key, metricKey, opts) => runExperimentMetricsUpdate(key, metricKey, opts, printer.requestId, deps)));
|
|
1751
|
+
envLeaf(metrics, 'query <key> <metricKey>', 'Run the experiment\'s copy of a metric definition as an analysis query (or --print-spec).')
|
|
1752
|
+
.requiredOption('--from <date>', 'first day, YYYY-MM-DD (inclusive, in --time-zone)')
|
|
1753
|
+
.requiredOption('--to <date>', 'last day, YYYY-MM-DD (inclusive, in --time-zone)')
|
|
1754
|
+
.option('--time-zone <iana>', `IANA time zone (default ${exports.METRIC_QUERY_DEFAULT_TIME_ZONE})`)
|
|
1755
|
+
.option('--print-spec', 'only print the analytics request body (for `supercli analytics events-query|retention --file`)')
|
|
1756
|
+
.action(act((_p, key, metricKey, opts) => runExperimentMetricsQuery(key, metricKey, opts, deps)));
|
|
1316
1757
|
envLeaf(metrics, 'remove <key> <metricKey>', 'Remove one metric or guardrail.')
|
|
1317
1758
|
.action(act((printer, key, metricKey, opts) => runExperimentMetricsRemove(key, metricKey, opts, printer.requestId, deps)));
|
|
1759
|
+
const defs = experiment.command('metric-defs')
|
|
1760
|
+
.description('Project-level metric library (shared by every environment); experiments add metrics from it.');
|
|
1761
|
+
const projectLeaf = (spec, description) => defs.command(spec)
|
|
1762
|
+
.description(description)
|
|
1763
|
+
.option('--config <path>', 'explicit super.json path');
|
|
1764
|
+
const definitionFlags = (cmd) => cmd
|
|
1765
|
+
.option('--direction <dir>', 'up | down: which direction is better (default up)')
|
|
1766
|
+
.option('--property <name>', 'numeric property for sum / avg / pct')
|
|
1767
|
+
.option('--property-type <type>', 'int | float (default float)')
|
|
1768
|
+
.option('--property-column <kind>', 'dynamic (default) | fixed (preset column)')
|
|
1769
|
+
.option('--percentile <n>', 'percentile for --kind pct, 1-99')
|
|
1770
|
+
.option('--retention-day <n>', 'retention day N for --kind retention, 1-30')
|
|
1771
|
+
.option('--filters <json|@file>', 'JSON array of event filters {name, value_type, operator, values}');
|
|
1772
|
+
projectLeaf('list', 'List library metrics.')
|
|
1773
|
+
.option('--status <status>', 'active | deprecated')
|
|
1774
|
+
.action(act((_p, opts) => runMetricDefsList(opts, deps)));
|
|
1775
|
+
projectLeaf('get <metricKey>', 'Show one library metric and the experiments using it.')
|
|
1776
|
+
.action(act((_p, metricKey, opts) => runMetricDefsGet(metricKey, opts, deps)));
|
|
1777
|
+
definitionFlags(projectLeaf('create', 'Create a library metric (source: api).')
|
|
1778
|
+
.requiredOption('--kind <kind>', 'conversion | count | sum | avg | pct | retention')
|
|
1779
|
+
.requiredOption('--event <name>', 'event name')
|
|
1780
|
+
.option('--key <metricKey>', 'library key (derived from kind + event when omitted)')
|
|
1781
|
+
.option('--name <text>', 'display name (default: the key; at most 80 characters)')
|
|
1782
|
+
.option('--description <text>', 'description (at most 200 characters)'))
|
|
1783
|
+
.action(act((printer, opts) => runMetricDefsCreate(opts, printer.requestId, deps)));
|
|
1784
|
+
definitionFlags(projectLeaf('update <metricKey>', 'Edit a library metric. Definition and direction are frozen once any experiment uses it.')
|
|
1785
|
+
.option('--name <text>', 'display name (at most 80 characters)')
|
|
1786
|
+
.option('--description <text>', 'description (at most 200 characters; empty string clears it)')
|
|
1787
|
+
.option('--kind <kind>', 'conversion | count | sum | avg | pct | retention')
|
|
1788
|
+
.option('--event <name>', 'event name'))
|
|
1789
|
+
.action(act((printer, metricKey, opts) => runMetricDefsUpdate(metricKey, opts, printer.requestId, deps)));
|
|
1790
|
+
projectLeaf('query <metricKey>', 'Run a library metric definition as an analysis query (or --print-spec).')
|
|
1791
|
+
.option('--env <env>', 'project environment to query (server default: prod)')
|
|
1792
|
+
.requiredOption('--from <date>', 'first day, YYYY-MM-DD (inclusive, in --time-zone)')
|
|
1793
|
+
.requiredOption('--to <date>', 'last day, YYYY-MM-DD (inclusive, in --time-zone)')
|
|
1794
|
+
.option('--time-zone <iana>', `IANA time zone (default ${exports.METRIC_QUERY_DEFAULT_TIME_ZONE})`)
|
|
1795
|
+
.option('--print-spec', 'only print the analytics request body (for `supercli analytics events-query|retention --file`)')
|
|
1796
|
+
.action(act((_p, metricKey, opts) => runMetricDefsQuery(metricKey, opts, deps)));
|
|
1797
|
+
projectLeaf('deprecate <metricKey>', 'Deprecate a library metric: no new experiment can add it; existing ones keep it.')
|
|
1798
|
+
.action(act((printer, metricKey, opts) => runMetricDefsSetStatus('deprecated', metricKey, opts, printer.requestId, deps)));
|
|
1799
|
+
projectLeaf('activate <metricKey>', 'Re-activate a deprecated library metric.')
|
|
1800
|
+
.action(act((printer, metricKey, opts) => runMetricDefsSetStatus('active', metricKey, opts, printer.requestId, deps)));
|
|
1801
|
+
projectLeaf('delete <metricKey>', 'Delete a library metric no experiment uses.')
|
|
1802
|
+
.action(act((printer, metricKey, opts) => runMetricDefsDelete(metricKey, opts, printer.requestId, deps)));
|
|
1318
1803
|
envLeaf(experiment, 'results <key>', 'Show experiment results (may recompute on the server; waits up to 150 s).')
|
|
1319
1804
|
.option('--refresh', 'ask the server to recompute (throttled to once a minute)')
|
|
1320
1805
|
.option('--time-zone <iana>', 'IANA time zone, only used the first time results are computed')
|