@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/telemetry/telemetry.module.js

@@ -0,0 +1,249 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var TelemetryModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryModule = void 0;
+const common_1 = require("@nestjs/common");
+const telemetry_ai_enabled_guard_1 = require("./assistant/telemetry-ai-enabled.guard");
+const telemetry_assistant_controller_1 = require("./assistant/telemetry-assistant.controller");
+const telemetry_assistant_service_1 = require("./assistant/telemetry-assistant.service");
+const telemetry_connection_admin_service_1 = require("./connection/telemetry-connection-admin.service");
+const telemetry_connection_test_service_1 = require("./connection/telemetry-connection-test.service");
+const telemetry_connection_controller_1 = require("./connection/telemetry-connection.controller");
+const telemetry_connection_service_1 = require("./connection/telemetry-connection.service");
+const telemetry_dashboard_controller_1 = require("./dashboard/telemetry-dashboard.controller");
+const telemetry_dashboard_service_1 = require("./dashboard/telemetry-dashboard.service");
+const telemetry_dashboard_panel_service_1 = require("./dashboard/panels/telemetry-dashboard-panel.service");
+const telemetry_export_service_1 = require("./export/telemetry-export.service");
+const greptime_client_1 = require("./stores/greptime/greptime.client");
+const greptime_dialect_1 = require("./stores/greptime/greptime.dialect");
+const telemetry_store_controller_1 = require("./stores/telemetry-store.controller");
+const telemetry_store_resolver_1 = require("./stores/telemetry-store.resolver");
+const telemetry_store_settings_service_1 = require("./stores/telemetry-store-settings.service");
+const telemetry_store_1 = require("./stores/telemetry-store");
+const telemetry_retention_handler_1 = require("./handlers/telemetry-retention.handler");
+const telemetry_query_service_1 = require("./query/telemetry-query.service");
+const telemetry_schema_service_1 = require("./query/telemetry-schema.service");
+const stack_agent_client_1 = require("./stack/stack-agent.client");
+const telemetry_stack_deploy_handler_1 = require("./stack/telemetry-stack-deploy.handler");
+const telemetry_stack_controller_1 = require("./stack/telemetry-stack.controller");
+const telemetry_stack_service_1 = require("./stack/telemetry-stack.service");
+const telemetry_retention_task_1 = require("./tasks/telemetry-retention.task");
+const telemetry_admin_controller_1 = require("./telemetry-admin.controller");
+const telemetry_config_controller_1 = require("./telemetry-config.controller");
+const telemetry_explorer_controller_1 = require("./telemetry-explorer.controller");
+const telemetry_settings_service_1 = require("./telemetry-settings.service");
+const telemetry_status_service_1 = require("./telemetry-status.service");
+const telemetry_support_bundle_section_1 = require("./telemetry-support-bundle.section");
+const telemetry_connection_doctor_check_1 = require("./doctor/telemetry-connection.doctor-check");
+const greptimedb_egress_contributor_1 = require("./doctor/egress/greptimedb.egress.contributor");
+const telemetry_export_doctor_check_1 = require("./doctor/telemetry-export.doctor-check");
+const telemetry_freshness_doctor_check_1 = require("./doctor/telemetry-freshness.doctor-check");
+const telemetry_reachable_doctor_check_1 = require("./doctor/telemetry-reachable.doctor-check");
+const telemetry_tables_doctor_check_1 = require("./doctor/telemetry-tables.doctor-check");
+const metric_group_registry_service_1 = require("./metrics/metric-group-registry.service");
+const metric_group_registry_1 = require("./metrics/metric-group.registry");
+const verdict_policy_1 = require("./dashboard/verdict-policy");
+const telemetry_options_1 = require("./telemetry.options");
+// =============================================================================
+// TelemetryModule (issue #534, epic #528; packaged as
+// `@marinoscar/platform-api/telemetry` by #703)
+// =============================================================================
+//
+// The API side of observability: the `telemetry` settings (and the runtime
+// export gate they drive), the GreptimeDB client, the store's status, and the
+// server-only `telemetry.retention.apply` job with its enqueue-only cron.
+//
+// PACKAGED (#703). Nothing here imports the app: every app capability comes
+// through a host port (./ports.ts) the app binds in `forRoot({ imports })`,
+// and every route through the controller-factory recipe with the app's
+// access decorators (`forRoot({ host })`).
+//
+// The explorer (#535): `TelemetryQueryService` (the one entry point for
+// caller-supplied SQL: guard, row cap, timeout, audit), `TelemetrySchemaService`
+// (tables and columns) and `TelemetryExportService` (csv/ndjson/xlsx/parquet),
+// behind `TelemetryExplorerController` on `telemetry:query`.
+//
+// The assistant (#536, #571): `TelemetryAssistantService` runs a
+// troubleshooting agent's tool loop through the `TELEMETRY_AI` port (the
+// app's `AiService.forUser`);
+// every statement its tools run — the model's and the ones it builds itself
+// (`assistant/telemetry-assistant.sql.ts`) — goes through
+// `TelemetryQueryService.run` with `source: 'assistant'`, so it is held to
+// exactly the explorer's guard and bounds; `TelemetrySchemaService` lists and
+// describes tables, and the `TELEMETRY_SETTINGS_STORE` port gives the
+// allowlisted feature flags `get_app_context` reports. Streamed by
+// `TelemetryAssistantController`.
+//
+// The connection (#558): `TelemetryConnectionService` resolves the GreptimeDB
+// connection at runtime — the one saved at /admin/settings/telemetry (a
+// `telemetry_connection` system-settings row plus two passwords in the
+// credential store, the `TELEMETRY_CREDENTIAL_STORE` port), else the `GREPTIME_*`
+// deployment default. `GreptimeClient` builds its pools from it and rebuilds
+// them when it changes. `TelemetryConnectionController` is the admin surface.
+//
+// The services (#567): on a VPS, `StackAgentClient` talks to the
+// `stack-agent` sidecar (STACK_AGENT_URL/TOKEN) to report the telemetry
+// containers' state and to start them through the server-only
+// `telemetry.stack.deploy` job. `TelemetryStackController` is the admin
+// surface, under /api/admin/telemetry/stack.
+//
+// The dashboard (#577): `TelemetryDashboardService` runs the fixed,
+// server-authored statements of `dashboard/telemetry-dashboard.sql.ts` (no
+// caller SQL) on the reader pool, with a 15 s result cache, behind
+// `TelemetryDashboardController` on `telemetry:query`.
+//
+// `GreptimeClient`, `TelemetrySettingsService` and the two query services are
+// exported for it.
+//
+// The store (PP-14.11): every service reads the telemetry store through the
+// `TELEMETRY_STORE` port and its SQL spelling through `TELEMETRY_SQL_DIALECT`,
+// never through `GreptimeClient`. `forRoot({ store })` selects the
+// implementation (default `greptime`): the built-in binds the port to
+// `GreptimeClient` (its connection stays the runtime-configured
+// `TelemetryConnectionService` one); any other registered store is built by
+// `TelemetryStoreResolver` from its `telemetry_store` settings and its secrets.
+// =============================================================================
+const PROVIDERS = [
+    // Rung 2 (#703): the metric-group registry, injectable; frozen on bootstrap.
+    metric_group_registry_service_1.MetricGroupRegistry,
+    telemetry_connection_service_1.TelemetryConnectionService,
+    telemetry_connection_admin_service_1.TelemetryConnectionAdminService,
+    telemetry_connection_test_service_1.TelemetryConnectionTestService,
+    greptime_client_1.GreptimeClient,
+    telemetry_settings_service_1.TelemetrySettingsService,
+    telemetry_status_service_1.TelemetryStatusService,
+    telemetry_retention_handler_1.TelemetryRetentionHandler,
+    telemetry_retention_task_1.TelemetryRetentionTask,
+    telemetry_query_service_1.TelemetryQueryService,
+    telemetry_schema_service_1.TelemetrySchemaService,
+    telemetry_export_service_1.TelemetryExportService,
+    telemetry_assistant_service_1.TelemetryAssistantService,
+    telemetry_ai_enabled_guard_1.TelemetryAiEnabledGuard,
+    stack_agent_client_1.StackAgentClient,
+    telemetry_stack_service_1.TelemetryStackService,
+    telemetry_stack_deploy_handler_1.TelemetryStackDeployHandler,
+    telemetry_dashboard_service_1.TelemetryDashboardService,
+    // The registered dashboard panels, read behind the guarded query facade (PP-14.18).
+    telemetry_dashboard_panel_service_1.TelemetryDashboardPanelService,
+    // Doctor checks (#634): read-only — never the connection test (it
+    // audits) and never the dashboard service's audited reads. Each registers
+    // itself with the Doctor's DoctorCheckRegistry (`@marinoscar/platform-api/doctor`).
+    telemetry_export_doctor_check_1.TelemetryExportDoctorCheck,
+    telemetry_connection_doctor_check_1.TelemetryConnectionDoctorCheck,
+    telemetry_reachable_doctor_check_1.TelemetryReachableDoctorCheck,
+    telemetry_tables_doctor_check_1.TelemetryTablesDoctorCheck,
+    telemetry_freshness_doctor_check_1.TelemetryFreshnessDoctorCheck,
+    // Egress inventory (#773): the GreptimeDB host.
+    greptimedb_egress_contributor_1.GreptimeDbEgressContributor,
+    // Support-bundle section (#772): telemetry health as aggregates only,
+    // gated on telemetry:query. Registers itself with SupportBundleRegistry.
+    telemetry_support_bundle_section_1.TelemetrySupportBundleSection,
+    // The settings and secrets of a non-built-in store (PP-14.11).
+    telemetry_store_settings_service_1.TelemetryStoreSettingsService,
+];
+/**
+ * The telemetry slice: settings and the export gate, the GreptimeDB
+ * connection and client, the explorer, the assistant, the dashboard, the
+ * stack-agent surface, the two server-only job types, five Doctor checks, an
+ * egress contributor and a support-bundle section.
+ *
+ * @stability experimental
+ */
+let TelemetryModule = TelemetryModule_1 = class TelemetryModule {
+    /**
+     * The slice for one app: its routes guarded by `options.host`, its host
+     * ports bound by `options.imports`.
+     *
+     * @param options - the module options.
+     * @returns the dynamic module. It exports `GreptimeClient`, `TELEMETRY_STORE`, `TELEMETRY_SQL_DIALECT`,
+     *   `TelemetrySettingsService`, `TelemetryQueryService`, `TelemetrySchemaService`,
+     *   `MetricGroupRegistry`, `DefaultVerdictPolicy`, `VERDICT_POLICY` and
+     *   `TELEMETRY_VERDICT_THRESHOLDS`.
+     * @throws Error when an option is invalid (a bad verdict threshold names the
+     *   field; a `store` nobody registered names the registered ids); RegistryError when an extra metric group is refused (a duplicate id
+     *   or family key fails boot here).
+     *
+     * @example
+     * ```ts
+     * TelemetryModule.forRoot({ host: platformHost, imports: [TelemetryHostModule] });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options) {
+        const resolved = (0, telemetry_options_1.resolveTelemetryModuleOptions)(options);
+        // Extra groups go in BEFORE the controllers are created, so the dashboard
+        // route's documented `group` enum includes them. Re-registering the very
+        // same definition (a second forRoot in one process) is a no-op.
+        (0, metric_group_registry_1.registerMetricGroups)(resolved.metricGroups.filter((group) => metric_group_registry_1.metricGroupRegistry.get(group.id) !== group));
+        return {
+            module: TelemetryModule_1,
+            imports: [...resolved.imports],
+            controllers: [
+                (0, telemetry_admin_controller_1.createTelemetryAdminController)(resolved),
+                (0, telemetry_config_controller_1.createTelemetryConfigController)(resolved),
+                (0, telemetry_explorer_controller_1.createTelemetryExplorerController)(resolved),
+                (0, telemetry_assistant_controller_1.createTelemetryAssistantController)(resolved),
+                (0, telemetry_connection_controller_1.createTelemetryConnectionController)(resolved),
+                (0, telemetry_stack_controller_1.createTelemetryStackController)(resolved),
+                (0, telemetry_dashboard_controller_1.createTelemetryDashboardController)(resolved),
+                (0, telemetry_store_controller_1.createTelemetryStoreController)(resolved),
+            ],
+            providers: [
+                { provide: telemetry_options_1.TELEMETRY_OPTIONS, useValue: resolved },
+                // Rung 1: the resolved, frozen thresholds every reader injects.
+                { provide: telemetry_options_1.TELEMETRY_VERDICT_THRESHOLDS, useValue: resolved.verdictThresholds },
+                // Rung 1: the metric groups' freshness window (`metrics.freshMs`).
+                { provide: telemetry_options_1.TELEMETRY_METRIC_FRESH_MS, useValue: resolved.metricFreshMs },
+                // Rung 1: the developers' notes for the assistant's system prompt (`assistant.extraInstructions`).
+                { provide: telemetry_options_1.TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS, useValue: resolved.assistantExtraInstructions },
+                // Rung 3: the verdict policy. The default is always provided, so an
+                // app policy can inject it and delegate.
+                verdict_policy_1.DefaultVerdictPolicy,
+                { provide: verdict_policy_1.VERDICT_POLICY, ...(resolved.verdictPolicy ?? { useExisting: verdict_policy_1.DefaultVerdictPolicy }) },
+                // The store port (PP-14.11): the built-in is the GreptimeClient; any
+                // other registered store is built from its settings by the resolver.
+                ...(resolved.store === telemetry_store_1.BUILTIN_TELEMETRY_STORE_ID
+                    ? [
+                        { provide: telemetry_store_1.TELEMETRY_STORE, useExisting: greptime_client_1.GreptimeClient },
+                        { provide: telemetry_store_1.TELEMETRY_SQL_DIALECT, useValue: greptime_dialect_1.GREPTIME_SQL_DIALECT },
+                    ]
+                    : [
+                        telemetry_store_resolver_1.TelemetryStoreResolver,
+                        { provide: telemetry_store_1.TELEMETRY_STORE, useExisting: telemetry_store_resolver_1.TelemetryStoreResolver },
+                        {
+                            provide: telemetry_store_1.TELEMETRY_SQL_DIALECT,
+                            useFactory: (resolver) => (0, telemetry_store_resolver_1.delegatingDialect)(resolver),
+                            inject: [telemetry_store_resolver_1.TelemetryStoreResolver],
+                        },
+                    ]),
+                ...PROVIDERS,
+            ],
+            exports: [
+                greptime_client_1.GreptimeClient,
+                telemetry_store_1.TELEMETRY_STORE,
+                telemetry_store_1.TELEMETRY_SQL_DIALECT,
+                telemetry_settings_service_1.TelemetrySettingsService,
+                telemetry_query_service_1.TelemetryQueryService,
+                telemetry_schema_service_1.TelemetrySchemaService,
+                metric_group_registry_service_1.MetricGroupRegistry,
+                verdict_policy_1.DefaultVerdictPolicy,
+                verdict_policy_1.VERDICT_POLICY,
+                telemetry_options_1.TELEMETRY_VERDICT_THRESHOLDS,
+                telemetry_options_1.TELEMETRY_METRIC_FRESH_MS,
+            ],
+        };
+    }
+};
+exports.TelemetryModule = TelemetryModule;
+exports.TelemetryModule = TelemetryModule = TelemetryModule_1 = __decorate([
+    (0, common_1.Module)({})
+], TelemetryModule);
+//# sourceMappingURL=telemetry.module.js.map

package/dist/telemetry/telemetry.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.module.js","sourceRoot":"","sources":["../../src/telemetry/telemetry.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAsE;AAEtE,uFAAiF;AACjF,+FAAgG;AAChG,yFAAoF;AACpF,wGAAkG;AAClG,sGAAgG;AAChG,kGAAmG;AACnG,4FAAuF;AACvF,+FAAgG;AAChG,yFAAoF;AACpF,4GAAsG;AACtG,gFAA2E;AAC3E,uEAAmE;AACnE,yEAA0E;AAC1E,oFAAqF;AACrF,gFAA8F;AAC9F,gGAA0F;AAC1F,8DAA8G;AAC9G,wFAAmF;AACnF,6EAAwE;AACxE,+EAA0E;AAC1E,mEAA8D;AAC9D,2FAAqF;AACrF,mFAAoF;AACpF,6EAAwE;AACxE,+EAA0E;AAC1E,6EAA8E;AAC9E,+EAAgF;AAChF,mFAAoF;AACpF,6EAAwE;AACxE,yEAAoE;AACpE,yFAAmF;AACnF,kGAA4F;AAC5F,iGAA4F;AAC5F,0FAAoF;AACpF,gGAA0F;AAC1F,gGAA0F;AAC1F,0FAAoF;AACpF,2FAA8E;AAC9E,2EAA4F;AAC5F,+DAAkF;AAClF,2DAO6B;AAE7B,gFAAgF;AAChF,sDAAsD;AACtD,gDAAgD;AAChD,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,uEAAuE;AACvE,2CAA2C;AAC3C,EAAE;AACF,wEAAwE;AACxE,iFAAiF;AACjF,+EAA+E;AAC/E,6DAA6D;AAC7D,EAAE;AACF,iEAAiE;AACjE,yEAAyE;AACzE,8BAA8B;AAC9B,4EAA4E;AAC5E,0DAA0D;AAC1D,2EAA2E;AAC3E,8EAA8E;AAC9E,sEAAsE;AACtE,mEAAmE;AACnE,kCAAkC;AAClC,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,uEAAuE;AACvE,kFAAkF;AAClF,6EAA6E;AAC7E,8EAA8E;AAC9E,EAAE;AACF,iEAAiE;AACjE,wEAAwE;AACxE,8DAA8D;AAC9D,wEAAwE;AACxE,6CAA6C;AAC7C,EAAE;AACF,oEAAoE;AACpE,2EAA2E;AAC3E,mEAAmE;AACnE,uDAAuD;AACvD,EAAE;AACF,8EAA8E;AAC9E,mBAAmB;AACnB,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,mEAAmE;AACnE,sEAAsE;AACtE,gEAAgE;AAChE,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAEhF,MAAM,SAAS,GAAG;IAChB,6EAA6E;IAC7E,mDAAmB;IACnB,yDAA0B;IAC1B,oEAA+B;IAC/B,kEAA8B;IAC9B,gCAAc;IACd,qDAAwB;IACxB,iDAAsB;IACtB,uDAAyB;IACzB,iDAAsB;IACtB,+CAAqB;IACrB,iDAAsB;IACtB,iDAAsB;IACtB,uDAAyB;IACzB,oDAAuB;IACvB,qCAAgB;IAChB,+CAAqB;IACrB,4DAA2B;IAC3B,uDAAyB;IACzB,oFAAoF;IACpF,kEAA8B;IAC9B,kEAAkE;IAClE,0EAA0E;IAC1E,oFAAoF;IACpF,0DAA0B;IAC1B,kEAA8B;IAC9B,gEAA6B;IAC7B,0DAA0B;IAC1B,gEAA6B;IAC7B,gDAAgD;IAChD,2DAA2B;IAC3B,sEAAsE;IACtE,yEAAyE;IACzE,gEAA6B;IAC7B,+DAA+D;IAC/D,gEAA6B;CAC9B,CAAC;AAEF;;;;;;;GAOG;AAEI,IAAM,eAAe,uBAArB,MAAM,eAAe;IAC1B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,OAA+B;QAC5C,MAAM,QAAQ,GAAG,IAAA,iDAA6B,EAAC,OAAO,CAAC,CAAC;QAExD,0EAA0E;QAC1E,yEAAyE;QACzE,gEAAgE;QAChE,IAAA,4CAAoB,EAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,2CAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;QAE3G,OAAO;YACL,MAAM,EAAE,iBAAe;YACvB,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC;YAC9B,WAAW,EAAE;gBACX,IAAA,2DAA8B,EAAC,QAAQ,CAAC;gBACxC,IAAA,6DAA+B,EAAC,QAAQ,CAAC;gBACzC,IAAA,iEAAiC,EAAC,QAAQ,CAAC;gBAC3C,IAAA,mEAAkC,EAAC,QAAQ,CAAC;gBAC5C,IAAA,qEAAmC,EAAC,QAAQ,CAAC;gBAC7C,IAAA,2DAA8B,EAAC,QAAQ,CAAC;gBACxC,IAAA,mEAAkC,EAAC,QAAQ,CAAC;gBAC5C,IAAA,2DAA8B,EAAC,QAAQ,CAAC;aACzC;YACD,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,qCAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE;gBAClD,gEAAgE;gBAChE,EAAE,OAAO,EAAE,gDAA4B,EAAE,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,EAAE;gBAC/E,mEAAmE;gBACnE,EAAE,OAAO,EAAE,6CAAyB,EAAE,QAAQ,EAAE,QAAQ,CAAC,aAAa,EAAE;gBACxE,mGAAmG;gBACnG,EAAE,OAAO,EAAE,0DAAsC,EAAE,QAAQ,EAAE,QAAQ,CAAC,0BAA0B,EAAE;gBAClG,oEAAoE;gBACpE,yCAAyC;gBACzC,qCAAoB;gBACpB,EAAE,OAAO,EAAE,+BAAc,EAAE,GAAG,CAAC,QAAQ,CAAC,aAAa,IAAI,EAAE,WAAW,EAAE,qCAAoB,EAAE,CAAC,EAAc;gBAC7G,qEAAqE;gBACrE,qEAAqE;gBACrE,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,4CAA0B;oBAC/C,CAAC,CAAC;wBACE,EAAE,OAAO,EAAE,iCAAe,EAAE,WAAW,EAAE,gCAAc,EAAE;wBACzD,EAAE,OAAO,EAAE,uCAAqB,EAAE,QAAQ,EAAE,uCAAoB,EAAE;qBACnE;oBACH,CAAC,CAAC;wBACE,iDAAsB;wBACtB,EAAE,OAAO,EAAE,iCAAe,EAAE,WAAW,EAAE,iDAAsB,EAAE;wBACjE;4BACE,OAAO,EAAE,uCAAqB;4BAC9B,UAAU,EAAE,CAAC,QAAgC,EAAE,EAAE,CAAC,IAAA,4CAAiB,EAAC,QAAQ,CAAC;4BAC7E,MAAM,EAAE,CAAC,iDAAsB,CAAC;yBACjC;qBACF,CAAC;gBACN,GAAG,SAAS;aACb;YACD,OAAO,EAAE;gBACP,gCAAc;gBACd,iCAAe;gBACf,uCAAqB;gBACrB,qDAAwB;gBACxB,+CAAqB;gBACrB,iDAAsB;gBACtB,mDAAmB;gBACnB,qCAAoB;gBACpB,+BAAc;gBACd,gDAA4B;gBAC5B,6CAAyB;aAC1B;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AAxFY,0CAAe;0BAAf,eAAe;IAD3B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,eAAe,CAwF3B"}

package/dist/telemetry/telemetry.options.d.ts

@@ -0,0 +1,236 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type PlatformHost, type PortBinding } from '../core/index';
+import { type VerdictThresholds } from './dashboard/telemetry-dashboard.verdict';
+import type { VerdictPolicy } from './dashboard/verdict-policy';
+import type { MetricGroupDef } from './metrics/metric-group.registry';
+import './stores/greptime/greptime.store';
+/**
+ * A partial {@link VerdictThresholds}: any field, at any depth, may be left out
+ * and keeps its default.
+ *
+ * @stability experimental
+ */
+export type VerdictThresholdsOverride = {
+    -readonly [K in keyof VerdictThresholds]?: VerdictThresholds[K] extends object ? {
+        -readonly [L in keyof VerdictThresholds[K]]?: VerdictThresholds[K][L];
+    } : VerdictThresholds[K];
+};
+/**
+ * The dashboard's options.
+ *
+ * @example
+ * ```ts
+ * TelemetryModule.forRoot({ host, imports, dashboard: { verdictThresholds: { noDataMinutes: 10 } } });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface TelemetryDashboardOptions {
+    /** Deep-merged over `DEFAULT_VERDICT_THRESHOLDS`; validated at boot. */
+    verdictThresholds?: VerdictThresholdsOverride;
+    /** What `VERDICT_POLICY` is bound to; default `{ useClass: DefaultVerdictPolicy }`. Its own dependencies come from `imports`. */
+    verdictPolicy?: PortBinding<VerdictPolicy>;
+}
+/**
+ * The dashboard metric groups' options.
+ *
+ * @example
+ * ```ts
+ * TelemetryModule.forRoot({ host, imports, metrics: { freshMs: 300_000 } });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface TelemetryMetricsOptions {
+    /**
+     * The freshness window, in milliseconds: a per-key table cell read as `last`
+     * (and an uptime check) older than its table's newest reading by more than
+     * this is not current. A whole number from 1 000 (1 s) to 86 400 000 (24 h);
+     * default `METRIC_FRESH_MS` (150 000, 150 s). Raise it when the app's
+     * metrics export interval is longer than the default's 60 s.
+     */
+    freshMs?: number;
+}
+/**
+ * The assistant's options.
+ *
+ * @example
+ * ```ts
+ * TelemetryModule.forRoot({ host, imports, assistant: { extraInstructions: 'Checkout is the revenue path: weigh its errors first.' } });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface TelemetryAssistantOptions {
+    /**
+     * Notes from the app's developers, appended to the system prompt under
+     * "APPLICATION NOTES", above the hard rules, the untrusted-data rule and the
+     * answer format, which they cannot override. At most
+     * `TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS_MAX` (4 000) characters of text; a
+     * control character other than a newline or a tab fails boot. This is code,
+     * set at deploy time: no setting, request or viewer can change it.
+     */
+    extraInstructions?: string;
+}
+/**
+ * Options of `TelemetryModule.forRoot()`.
+ *
+ * @example
+ * ```ts
+ * TelemetryModule.forRoot({ host: platformHost, imports: [TelemetryHostModule] });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface TelemetryModuleOptions {
+    /** The app's access decorators (`definePlatformHost`); required: a platform route is never public. */
+    host: PlatformHost;
+    /** Modules that export the host-port providers (`TELEMETRY_AUDIT_SINK`, `TELEMETRY_SETTINGS_STORE`, ...): the app's adapters. */
+    imports: NonNullable<ModuleMetadata['imports']>;
+    /** Extra metric groups, registered after the six platform groups when `forRoot` runs. */
+    metricGroups?: readonly MetricGroupDef[];
+    /**
+     * Reads the caller's user id off the framework request. Defaults to
+     * `request.requestUser.id`, else `request.user.id`.
+     *
+     * @param request - the framework request.
+     * @returns the user id, or `undefined` for an anonymous request (the access decorators refuse those first).
+     */
+    actorId?: (request: unknown) => string | undefined;
+    /** The dashboard's verdict thresholds and policy. */
+    dashboard?: TelemetryDashboardOptions;
+    /** The dashboard metric groups' freshness window. */
+    metrics?: TelemetryMetricsOptions;
+    /** The assistant's system-prompt notes. */
+    assistant?: TelemetryAssistantOptions;
+    /**
+     * The id of the telemetry store the explorer, the dashboard, the status page,
+     * the retention job and the Doctor use. Default `greptime` (the built-in).
+     * An app's own store is registered with `registerTelemetryStore` at import
+     * time (before `forRoot` runs) and selected here.
+     *
+     * @example
+     * ```ts
+     * TelemetryModule.forRoot({ host, imports, store: 'memory' });
+     * ```
+     */
+    store?: string;
+}
+/**
+ * The options after validation and defaults, as the slice's providers and
+ * controller factories receive them.
+ *
+ * @stability experimental
+ */
+export interface ResolvedTelemetryModuleOptions {
+    /** The validated, frozen host. */
+    readonly host: PlatformHost;
+    /** The host-port modules. */
+    readonly imports: NonNullable<ModuleMetadata['imports']>;
+    /** The extra metric groups (possibly empty). */
+    readonly metricGroups: readonly MetricGroupDef[];
+    /** The caller resolver. */
+    readonly actorId: (request: unknown) => string | undefined;
+    /** A parameter decorator injecting `actorId(request)` into a route handler. */
+    readonly actorIdParam: () => ParameterDecorator;
+    /** The resolved, frozen verdict thresholds (`TELEMETRY_VERDICT_THRESHOLDS`). */
+    readonly verdictThresholds: VerdictThresholds;
+    /** The binding of `VERDICT_POLICY`, or `undefined` for the default policy. */
+    readonly verdictPolicy: PortBinding<VerdictPolicy> | undefined;
+    /** The metric groups' freshness window in milliseconds (`TELEMETRY_METRIC_FRESH_MS`). */
+    readonly metricFreshMs: number;
+    /** The id of the selected telemetry store (registered; default `greptime`). */
+    readonly store: string;
+    /** The developers' notes for the assistant's system prompt, or `null` (`TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS`). */
+    readonly assistantExtraInstructions: string | null;
+}
+/**
+ * Injection token of the {@link ResolvedTelemetryModuleOptions}.
+ *
+ * @stability experimental
+ */
+export declare const TELEMETRY_OPTIONS: unique symbol;
+/**
+ * Injection token of the resolved {@link VerdictThresholds}: the defaults with
+ * the app's `dashboard.verdictThresholds` deep-merged over them, frozen. Every
+ * reader of a threshold injects this.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const TELEMETRY_VERDICT_THRESHOLDS: unique symbol;
+/**
+ * Injection token of the metric groups' freshness window in milliseconds: the
+ * app's `metrics.freshMs`, else `METRIC_FRESH_MS`. The dashboard's `/metrics`
+ * route reads it and reports it as the response's `freshMs`.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const TELEMETRY_METRIC_FRESH_MS: unique symbol;
+/**
+ * Injection token of the developers' notes appended to the assistant's system
+ * prompt: the app's `assistant.extraInstructions`, or `null`.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS: unique symbol;
+/**
+ * The freshness window for an override: validated, else the default.
+ *
+ * @param metrics - the app's `metrics`, or `undefined`.
+ * @returns the window in milliseconds.
+ * @throws Error when `metrics` is not an object or `freshMs` is not a whole number from 1 000 to 86 400 000.
+ *
+ * @stability experimental
+ */
+export declare function resolveMetricFreshMs(metrics: TelemetryMetricsOptions | undefined): number;
+/**
+ * The verdict thresholds for an override: validated, deep-merged over
+ * {@link DEFAULT_VERDICT_THRESHOLDS} and frozen.
+ *
+ * @param override - the app's `dashboard.verdictThresholds`, or `undefined`.
+ * @returns the resolved thresholds.
+ * @throws Error naming every invalid field, or a degraded bound beyond its critical one.
+ *
+ * @stability experimental
+ */
+export declare function resolveVerdictThresholds(override: VerdictThresholdsOverride | undefined): VerdictThresholds;
+/**
+ * The assistant's extra instructions for an override: validated, trimmed, else `null`.
+ *
+ * @param assistant - the app's `assistant` option, or `undefined`.
+ * @returns the notes, or `null` when there are none.
+ * @throws Error when `assistant` is not an object, or `extraInstructions` is not a string of at most
+ *   `TELEMETRY_ASSISTANT_EXTRA_INSTRUCTIONS_MAX` characters without control characters.
+ *
+ * @stability experimental
+ */
+export declare function resolveAssistantExtraInstructions(assistant: TelemetryAssistantOptions | undefined): string | null;
+/**
+ * The default caller resolver: the authenticated user's `id`, from
+ * `request.requestUser` (set by the app's guards) or `request.user` (the JWT
+ * strategy's user).
+ *
+ * @param request - the framework request.
+ * @returns the user id, or `undefined`.
+ *
+ * @stability experimental
+ */
+export declare function defaultTelemetryActorId(request: unknown): string | undefined;
+/**
+ * Validates `options` and applies the defaults.
+ *
+ * @param options - what the app passed to `forRoot`.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the bad option.
+ *
+ * @stability experimental
+ */
+export declare function resolveTelemetryModuleOptions(options: TelemetryModuleOptions): ResolvedTelemetryModuleOptions;
+//# sourceMappingURL=telemetry.options.d.ts.map

package/dist/telemetry/telemetry.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.options.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.options.ts"],"names":[],"mappings":"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"}