@juice-js/observability 0.0.0-stage → 1.0.0-alpha.1

package/types/juice-js-observability.d.ts

@@ -0,0 +1,387 @@
+import * as i0 from "@angular/core";
+import { EnvironmentProviders, InjectionToken, PipeTransform } from "@angular/core";
+import { Observable } from "rxjs";
+import { Params, Routes } from "@angular/router";
+import { Menus } from "@juice-js/core";
+/** How the host app mounts Juice Observability. */
+export interface ObservabilityOptions {
+  /** The Juice API origin; empty when the API serves the app (same origin). */
+  apiBase: string;
+  /** Where the host mounts {@link OBSERVABILITY_ROUTES}: `/` for the whole app, or a path such as `/observability`. */
+  basePath: string;
+}
+export declare const OBSERVABILITY_OPTIONS: InjectionToken<ObservabilityOptions>;
+/** Configures the pages: where the API is and where the host mounted the routes. */
+export declare function provideJuiceObservability(options?: Partial<ObservabilityOptions>): EnvironmentProviders;
+/** `/observability/` → `/observability`; `` and `/` → `/`. */
+export declare function normalizeBasePath(basePath: string): string;
+/** Router links to the pages, under the host's mount path. */
+export declare class ObservabilityLinks {
+  readonly base: string;
+  /** `to('services', id)` → `['/observability', 'services', id]`. */
+  to(...segments: unknown[]): unknown[];
+  static ɵfac: i0.ɵɵFactoryDeclaration<ObservabilityLinks, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** `['services', id] | jcLink`: the same as {@link ObservabilityLinks.to} in a template. */
+export declare class LinkPipe implements PipeTransform {
+  private readonly links;
+  transform(segments: unknown[]): unknown[];
+  static ɵfac: i0.ɵɵFactoryDeclaration<LinkPipe, never>;
+  static ɵpipe: i0.ɵɵPipeDeclaration<LinkPipe, "jcLink", true>;
+}
+export interface Page<T> {
+  items: T[];
+  nextCursor: string | null;
+}
+export interface TelemetryPage<T> {
+  items: T[];
+  truncated: boolean;
+  nextCursor?: string | null;
+}
+export interface Tenant {
+  id: string;
+  key: string;
+  displayName: string;
+}
+export interface DeploymentEnvironment {
+  id: string;
+  key: string;
+  type: string;
+  firstSeen: string;
+  lastSeen: string;
+}
+export interface Application {
+  id: string;
+  key: string;
+  displayName: string;
+  services: number;
+  firstSeen: string;
+  lastSeen: string;
+}
+export interface ResourceSummary {
+  id: string;
+  type: string;
+  key: string;
+  displayName: string;
+  firstSeen: string;
+  lastSeen: string;
+}
+export type HealthState = 'Healthy' | 'Degraded' | 'Unhealthy' | 'Critical' | 'Offline' | 'Unknown';
+export interface Health {
+  subjectType: string;
+  subjectId: string;
+  subjectName: string;
+  environment: string | null;
+  state: HealthState;
+  reasons: string[];
+  policyVersion: string;
+  evaluatedAt: string;
+  evidenceFrom: string;
+  evidenceTo: string;
+  lastEvidenceAt: string | null;
+  since: string;
+  stale: boolean;
+}
+export interface Instance {
+  id: string;
+  environment: string;
+  instanceKey: string;
+  keySource: string;
+  serviceVersion: string | null;
+  state: string;
+  hostResourceId: string | null;
+  firstSeen: string;
+  lastSeen: string;
+  health: HealthState | null;
+}
+export interface IntegrationLink {
+  integration: string;
+  title: string;
+  url: string;
+}
+export interface ResourceDetail {
+  id: string;
+  type: string;
+  key: string;
+  displayName: string;
+  firstSeen: string;
+  lastSeen: string;
+  namespace: string | null;
+  name: string | null;
+  applicationId: string | null;
+  attributes: Record<string, string>;
+  instances: Instance[];
+  instancesTruncated: boolean;
+  health: Health[];
+  links: IntegrationLink[];
+}
+export interface TopologyNode {
+  id: string;
+  type: string;
+  displayName: string;
+  health: HealthState | null;
+}
+export interface TopologyEdge {
+  id: string;
+  source: string;
+  target: string;
+  relation: string;
+  confidence: string;
+  evidenceSource: string;
+  spanCount: number;
+  firstSeen: string;
+  lastSeen: string;
+}
+export interface Topology {
+  environment: string | null;
+  nodes: TopologyNode[];
+  edges: TopologyEdge[];
+  truncated: boolean;
+}
+export interface Alert {
+  id: string;
+  rule: string;
+  subjectKey: string;
+  subjectType: string;
+  subjectId: string | null;
+  environment: string | null;
+  severity: string;
+  state: string;
+  breachStartedAt: string | null;
+  firedAt: string | null;
+  resolvedAt: string | null;
+  lastEvaluatedAt: string;
+  lastValue: number | null;
+  noData: boolean;
+  acknowledgedAt: string | null;
+  acknowledgedBy: string | null;
+}
+export interface AlertTransition {
+  from: string | null;
+  to: string;
+  at: string;
+  value: number | null;
+  reason: string;
+}
+export interface AlertDetail {
+  alert: Alert;
+  evidence: Record<string, string>;
+  acknowledgeComment: string | null;
+  history: AlertTransition[];
+  subjectHealth: Health[];
+  links: IntegrationLink[];
+}
+export interface Rule {
+  key: string;
+  name: string;
+  template: string;
+  severity: string;
+  enabled: boolean;
+  definition: Record<string, unknown>;
+  loadedAt: string;
+}
+export interface TraceSummary {
+  traceId: string;
+  startedAt: string;
+  durationMs: number;
+  rootService: string;
+  rootOperation: string;
+  environment: string | null;
+  rootInstance: string | null;
+  rootHost: string | null;
+  spanCount: number;
+  errorCount: number;
+  services: string[];
+}
+export interface SpanEvent {
+  name: string;
+  at: string;
+  attributes: Record<string, string>;
+}
+export interface SpanTarget {
+  kind: 'service' | 'resource';
+  id: string;
+  name: string;
+}
+export interface Span {
+  spanId: string;
+  parentSpanId: string | null;
+  serviceId: string | null;
+  service: string;
+  environment: string | null;
+  instance: string | null;
+  host: string | null;
+  name: string;
+  kind: string;
+  startedAt: string;
+  durationMs: number;
+  status: string;
+  statusMessage: string | null;
+  scope: string | null;
+  scopeVersion: string | null;
+  attributes: Record<string, string>;
+  events: SpanEvent[];
+  links: {
+    traceId: string;
+    spanId: string;
+  }[];
+  target: SpanTarget | null;
+}
+export interface Trace {
+  traceId: string;
+  spans: Span[];
+  truncated: boolean;
+}
+export interface LogRecord {
+  timestamp: string;
+  severity: string;
+  severityNumber: number;
+  service: string;
+  environment: string | null;
+  instance: string | null;
+  body: string;
+  bodyTruncated: boolean;
+  traceId: string | null;
+  spanId: string | null;
+  attributes: Record<string, string>;
+}
+export interface Operation {
+  name: string;
+  kind: string;
+  count: number;
+  requestsPerSecond: number;
+  errorRate: number;
+  p50Ms: number;
+  p95Ms: number;
+  p99Ms: number;
+  lastSeen: string;
+}
+export interface MetricInfo {
+  name: string;
+  type: string;
+  unit: string;
+  description: string;
+}
+export interface Point {
+  at: string;
+  value: number | null;
+}
+export interface Series {
+  name: string;
+  type: string;
+  unit: string;
+  aggregation: string;
+  stepSeconds: number;
+  points: Point[];
+}
+export interface ServiceStatsPoint {
+  at: string;
+  requestsPerSecond: number;
+  errorRate: number;
+  p95Ms: number | null;
+}
+export interface ServiceStats {
+  stepSeconds: number;
+  points: ServiceStatsPoint[];
+}
+export interface DependencyEvidence {
+  dependencyId: string;
+  relation: string;
+  confidence: string;
+  count: number;
+  errorRate: number;
+  p95Ms: number | null;
+  lastSeen: string | null;
+  slowestTraces: string[];
+  errorTraces: string[];
+}
+export interface SearchHit {
+  kind: 'trace' | 'span' | 'service';
+  id: string;
+  title: string;
+  traceId: string | null;
+}
+export type Query = Record<string, string | number | boolean | string[] | null | undefined>;
+/**
+ * The Console's only backend: the Juice API (Console requirements §3). One deployment serves one tenant, the one the
+ * signed-in user's token names.
+ */
+export declare class ApiService {
+  private readonly http;
+  private readonly base;
+  /** The caller's tenant, fetched once. */
+  readonly tenant$: Observable<Tenant>;
+  private get;
+  /** Every page of a cursor-paged list (bounded: at most `maxPages` requests). */
+  private all;
+  environments(): Observable<Page<DeploymentEnvironment>>;
+  applications(): Observable<Page<Application>>;
+  resources(type?: string): Observable<Page<ResourceSummary>>;
+  resource(id: string): Observable<ResourceDetail>;
+  health(query: Query): Observable<Page<Health>>;
+  topology(environment?: string | null): Observable<Topology>;
+  rules(): Observable<Page<Rule>>;
+  /** One page of alerts, newest first; pass the previous page's `nextCursor` as `cursor` for the next. */
+  alerts(query: Query): Observable<Page<Alert>>;
+  /** Every alert matching the query (bounded, like the other complete lists). */
+  allAlerts(query: Query): Observable<Page<Alert>>;
+  alert(id: string): Observable<AlertDetail>;
+  acknowledge(id: string, comment: string): Observable<Alert>;
+  traces(query: Query): Observable<TelemetryPage<TraceSummary>>;
+  trace(traceId: string): Observable<Trace>;
+  logs(query: Query): Observable<TelemetryPage<LogRecord>>;
+  operations(query: Query): Observable<TelemetryPage<Operation>>;
+  metrics(query: Query): Observable<TelemetryPage<MetricInfo>>;
+  series(query: Query): Observable<Series>;
+  serviceStats(query: Query): Observable<ServiceStats>;
+  dependency(id: string, query: Query): Observable<DependencyEvidence>;
+  search(q: string): Observable<TelemetryPage<SearchHit>>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ApiService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export declare const RANGES: Record<string, number>;
+/** Search ranges are at most 24 hours (the API's bound); series and operations take up to 7 days. */
+export declare const MAX_SEARCH_MS: number;
+/**
+ * The investigation context that follows the user between pages (Console requirements §17): environment and time
+ * range. It lives in the URL (`env`, and `range` or `from`/`to`), so every page is a deep link and the browser's back
+ * button restores it.
+ */
+export declare class ContextService {
+  private readonly router;
+  private readonly params;
+  readonly environment: import("@angular/core").Signal<string>;
+  readonly range: import("@angular/core").Signal<string>;
+  readonly absolute: import("@angular/core").Signal<{
+    from: string;
+    to: string;
+  } | null>;
+  /** The window as ISO strings, evaluated now for a relative range. */
+  window(maxMs?: number): {
+    from: string;
+    to: string;
+  };
+  /** Query parameters for a link: the context plus the target page's own. */
+  keep(extra?: Params): Params;
+  /** Changes the context on the current page, keeping its other parameters. */
+  set(change: {
+    env?: string | null;
+    range?: string | null;
+    from?: string | null;
+    to?: string | null;
+  }): void;
+  /** A time window centred on a moment, for "around this span" links. */
+  around(at: string, durationMs: number, paddingMs?: number): Params;
+  private leaf;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ContextService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * The pages, investigation first (Console requirements §4): services, traces, topology, logs and metrics; alerts and
+ * rules after. Detail pages are deep links (§17) and carry the environment and time range in their query parameters.
+ * The host mounts them at its `basePath` (see {@link provideJuiceObservability}) and adds its own guards.
+ */
+export declare const OBSERVABILITY_ROUTES: Routes;
+/** The side menu entries (juice-layout), investigation pages first, linking under `basePath`. */
+export declare function observabilityMenus(basePath?: string, order?: number): Menus;