@dipseth/opensearch-logs 0.1.0

package/dist/interfaces/alert.interfaces.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Alert system types — OSD monitors, Google Chat Card v2, YAML profiles,
+ * health report structures, and CLI arguments.
+ */
+import type { AggFilter, TermsAgg, DateHistBucket, ScriptedMetric, ParsedLatency, TopHitsAgg } from "./interfaces.js";
+export interface AlertProfile {
+    name: string;
+    description?: string;
+    destination: DestinationDef;
+    card_templates: Record<string, string>;
+    monitors: Record<string, MonitorDef>;
+    thresholds?: Record<string, number | string>;
+    defaults?: Record<string, string>;
+}
+export interface DestinationDef {
+    name: string;
+    type: "gchat" | "custom_webhook";
+}
+export interface MonitorDef {
+    description?: string;
+    schedule: ScheduleDef;
+    query: Record<string, unknown>;
+    index_pattern?: string;
+    trigger: TriggerDef;
+    card_template: string;
+    throttle?: ThrottleDef;
+}
+export interface ScheduleDef {
+    interval: number;
+    unit: "MINUTES" | "HOURS" | "DAYS";
+}
+export interface TriggerDef {
+    name: string;
+    severity: 1 | 2 | 3 | 4 | 5;
+    condition: string;
+}
+export interface ThrottleDef {
+    value: number;
+    unit: "MINUTES" | "HOURS" | "DAYS";
+}
+/** Flat context for pre-flight template resolution. */
+export interface TemplateContext {
+    thresholds: Record<string, number | string>;
+    defaults: Record<string, string>;
+}
+export interface OsdMonitorPayload {
+    type: "monitor";
+    name: string;
+    monitor_type: "query_level_monitor";
+    enabled: boolean;
+    schedule: {
+        period: {
+            interval: number;
+            unit: string;
+        };
+    };
+    inputs: OsdMonitorInput[];
+    triggers: OsdTriggerPayload[];
+}
+export interface OsdMonitorInput {
+    search: {
+        indices: string[];
+        query: Record<string, unknown>;
+    };
+}
+export interface OsdTriggerPayload {
+    name: string;
+    severity: string;
+    condition: {
+        script: {
+            source: string;
+            lang: "painless";
+        };
+    };
+    actions: OsdAction[];
+}
+export interface OsdAction {
+    name: string;
+    destination_id: string;
+    message_template: {
+        source: string;
+        lang: "mustache";
+    };
+    throttle_enabled: boolean;
+    throttle?: {
+        value: number;
+        unit: string;
+    };
+}
+export interface OsdDestinationPayload {
+    type: "custom_webhook";
+    name: string;
+    custom_webhook: {
+        scheme: string;
+        host: string;
+        port: number;
+        path: string;
+        query_params: Record<string, string>;
+        header_params: Record<string, string>;
+    };
+}
+/** Payload for POST _plugins/_notifications/configs (webhook channel). */
+export interface NotificationChannelPayload {
+    config_id?: string;
+    config: {
+        name: string;
+        description: string;
+        config_type: "webhook";
+        is_enabled: boolean;
+        webhook: {
+            url: string;
+            header_params: Record<string, string>;
+            method: "POST";
+        };
+    };
+}
+/** Response from POST _plugins/_notifications/configs. */
+export interface NotificationChannelResponse {
+    config_id: string;
+}
+/** Single channel entry from GET _plugins/_notifications/configs. */
+export interface NotificationChannelEntry {
+    config_id: string;
+    last_updated_time_ms: number;
+    created_time_ms: number;
+    config: {
+        name: string;
+        description: string;
+        config_type: string;
+        is_enabled: boolean;
+        webhook?: {
+            url: string;
+        };
+    };
+}
+/** Response from GET _plugins/_notifications/configs. */
+export interface NotificationChannelListResponse {
+    start_index: number;
+    total_hits: number;
+    total_hit_relation: string;
+    config_list: NotificationChannelEntry[];
+}
+export interface OsdMonitorResponse {
+    _id: string;
+    _version: number;
+    monitor: OsdMonitorPayload & {
+        name: string;
+    };
+}
+/** Response from POST /_plugins/_alerting/monitors/_search.
+ *  Note: _source contains the monitor fields directly (not nested under a "monitor" key). */
+export interface OsdSearchMonitorsResponse {
+    hits: {
+        total: {
+            value: number;
+        };
+        hits: Array<{
+            _id: string;
+            _source: {
+                type: string;
+                name: string;
+                monitor_type: string;
+                enabled: boolean;
+                schedule: {
+                    period: {
+                        interval: number;
+                        unit: string;
+                    };
+                };
+            };
+        }>;
+    };
+}
+export interface OsdExecuteResponse {
+    input_results: {
+        results: Array<{
+            query: Record<string, unknown>;
+        }>;
+    };
+    trigger_results: Record<string, {
+        triggered: boolean;
+    }>;
+}
+/** Structured result from listMonitors. */
+export interface MonitorListItem {
+    id: string;
+    name: string;
+    enabled: boolean;
+}
+/** Top-level Google Chat message payload containing Card v2 cards. */
+export interface GChatMessage {
+    cardsV2: GChatCardWrapper[];
+}
+export interface GChatCardWrapper {
+    cardId: string;
+    card: GChatCard;
+}
+export interface GChatCard {
+    header: GChatCardHeader;
+    sections: GChatSection[];
+}
+export interface GChatCardHeader {
+    title: string;
+    subtitle?: string;
+    imageUrl?: string;
+    imageType?: "CIRCLE" | "SQUARE";
+}
+export interface GChatSection {
+    header?: string;
+    widgets: GChatWidget[];
+}
+/** Union of all Google Chat Card v2 widget types we use. */
+export type GChatWidget = GChatDecoratedTextWidget | GChatButtonListWidget | GChatColumnsWidget;
+export interface GChatDecoratedTextWidget {
+    decoratedText: {
+        topLabel: string;
+        text: string;
+        wrapText?: boolean;
+        icon?: {
+            knownIcon: string;
+        };
+    };
+}
+export interface GChatButtonListWidget {
+    buttonList: {
+        buttons: GChatButton[];
+    };
+}
+export interface GChatButton {
+    text: string;
+    onClick: {
+        openLink: {
+            url: string;
+        };
+    };
+    color?: GChatColor;
+}
+export interface GChatColor {
+    red: number;
+    green: number;
+    blue: number;
+    alpha: number;
+}
+export interface GChatColumnsWidget {
+    columns: {
+        columnItems: GChatColumnItem[];
+    };
+}
+export interface GChatColumnItem {
+    horizontalSizeStyle: "FILL_AVAILABLE_SPACE" | "FILL_MINIMUM_SPACE";
+    horizontalAlignment: "START" | "CENTER" | "END";
+    verticalAlignment: "START" | "CENTER" | "END";
+    widgets: GChatWidget[];
+}
+export interface HealthReport {
+    env: string;
+    periodStart: string;
+    periodEnd: string;
+    totalLogs: number;
+    totalErrors: number;
+    status: HealthStatus;
+    patterns: HealthReportPattern[];
+    serviceErrors: HealthReportServiceError[];
+    latency: HealthReportLatency | null;
+    errorTrend: HealthReportTrendBucket[];
+    recentErrors: HealthReportError[];
+    dashboardUrl: string;
+    discoverUrl: string;
+}
+export type HealthStatus = "HEALTHY" | "WARNING" | "DEGRADED";
+export interface HealthReportPattern {
+    name: string;
+    count: number;
+}
+export interface HealthReportServiceError {
+    service: string;
+    count: number;
+    description: string;
+}
+export interface HealthReportLatency {
+    tracked: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+}
+export interface HealthReportTrendBucket {
+    time: string;
+    count: number;
+}
+export interface HealthReportError {
+    timestamp: string;
+    service: string;
+    message: string;
+}
+/** Aggregation shape returned by the health report query. */
+export interface HealthReportAggs {
+    total_requests: AggFilter;
+    latency_stats: AggFilter & {
+        parsed: ScriptedMetric<ParsedLatency>;
+    };
+    error_trend: AggFilter & {
+        over_time: TermsAgg<DateHistBucket>;
+    };
+    recent_errors: AggFilter & {
+        samples: TopHitsAgg;
+    };
+    /** Dynamic keys: pattern checks (e.g. HTTP_500s) and svc_5xx_{alias}. */
+    [key: string]: AggFilter | (AggFilter & Record<string, unknown>);
+}
+export type AlertMode = "create" | "list" | "test" | "delete" | "report";
+export interface AlertArgs {
+    mode: AlertMode;
+    profile?: string;
+    monitor?: string;
+    service?: string;
+    dashboardUrl?: string;
+    webhookUrl?: string;
+    env: string;
+    hours: number;
+    dryRun: boolean;
+    json: boolean;
+}

package/dist/interfaces/alert.interfaces.js

@@ -0,0 +1,6 @@
+/**
+ * Alert system types — OSD monitors, Google Chat Card v2, YAML profiles,
+ * health report structures, and CLI arguments.
+ */
+export {};
+//# sourceMappingURL=alert.interfaces.js.map

package/dist/interfaces/alert.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.interfaces.js","sourceRoot":"","sources":["../../src/interfaces/alert.interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/interfaces/dashboard-gen.interfaces.d.ts

@@ -0,0 +1,33 @@
+/** YAML-driven dashboard generator types. */
+export interface DashboardConfig {
+    name: string;
+    title: string;
+    description?: string;
+    time_from?: string;
+    time_to?: string;
+    refresh_interval?: number;
+    header?: string;
+    metrics?: DashboardMetricDef[];
+    charts?: DashboardChartDef[];
+    markdown?: DashboardMarkdownDef[];
+}
+export interface DashboardMetricDef {
+    title: string;
+    query: string;
+    label?: string;
+}
+export interface DashboardChartDef {
+    title: string;
+    width?: "half" | "full";
+    interval?: string;
+    series: Record<string, string>;
+}
+export interface DashboardMarkdownDef {
+    title: string;
+    text: string;
+}
+export interface DashboardGenArgs {
+    mode: "create" | "validate" | "delete";
+    config: string;
+    dryRun: boolean;
+}

package/dist/interfaces/dashboard-gen.interfaces.js

@@ -0,0 +1,3 @@
+/** YAML-driven dashboard generator types. */
+export {};
+//# sourceMappingURL=dashboard-gen.interfaces.js.map

package/dist/interfaces/dashboard-gen.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-gen.interfaces.js","sourceRoot":"","sources":["../../src/interfaces/dashboard-gen.interfaces.ts"],"names":[],"mappings":"AAAA,6CAA6C"}

package/dist/interfaces/interfaces.d.ts

@@ -0,0 +1,312 @@
+/** Shared TypeScript interfaces for OpenSearch log tools. */
+export interface OpenSearchConfig {
+    host: string;
+    port: string;
+    username: string;
+    password: string;
+    /** Port for the data API (search, alerting). Defaults to 25060 (DO-managed). AWS uses 443. */
+    dataPort?: number;
+    /** Port for the Dashboards API (saved objects, Kibana UI). Defaults to 443. */
+    dashboardsPort?: number;
+    /** Index name prefix. Defaults to "python-services". Override for non-Python services. */
+    indexPrefix?: string;
+    /** Security tenant for dashboards API. Defaults to "global". */
+    tenant?: string;
+}
+export interface ServiceInfo {
+    logName: string;
+    nginxPrefix: string;
+    port: number;
+    description: string;
+}
+/** Any OpenSearch query DSL clause (bool, term, range, query_string, etc.). */
+export type QueryClause = Record<string, unknown>;
+/** Fields available on log documents in the _source. All optional because
+ *  unstructured nginx logs only have @timestamp, log, environment, droplet_id. */
+export interface LogSource {
+    "@timestamp"?: string;
+    log?: string;
+    service?: string;
+    level?: string;
+    name?: string;
+    message?: string;
+    timestamp?: string;
+    host?: string;
+    droplet_id?: string;
+    environment?: string;
+    status_code?: number;
+    duration_ms?: number;
+    endpoint?: string;
+    correlation_id?: string;
+    error_type?: string;
+    method?: string;
+    user_agent?: string;
+    client_ip?: string;
+    exc_info?: string;
+}
+export interface SearchHit {
+    _id: string;
+    _source: LogSource;
+}
+export interface SearchResult<TAggs = Record<string, unknown>> {
+    hits: {
+        total: {
+            value: number;
+            relation: string;
+        };
+        hits: SearchHit[];
+    };
+    aggregations?: TAggs;
+}
+export interface CountResult {
+    count: number;
+}
+export interface ApiResponse {
+    _conflict?: boolean;
+    _not_found?: boolean;
+    _error?: boolean;
+    _code?: number;
+    _body?: string;
+    _reason?: string;
+    [key: string]: unknown;
+}
+/** Base result from any filter aggregation. */
+export interface AggFilter {
+    doc_count: number;
+}
+/** Bucket from a terms aggregation. */
+export interface TermsBucket<K extends string | number = string> {
+    key: K;
+    doc_count: number;
+}
+/** Bucket from a date_histogram aggregation. */
+export interface DateHistBucket {
+    key: number;
+    key_as_string: string;
+    doc_count: number;
+}
+/** Result shape for a terms aggregation. */
+export interface TermsAgg<B = TermsBucket> {
+    buckets: B[];
+}
+/** Result shape for a scripted_metric aggregation. */
+export interface ScriptedMetric<V> {
+    value: V;
+}
+/** Result shape for a top_hits aggregation. */
+export interface TopHitsAgg {
+    hits: SearchResult["hits"];
+}
+export interface ParsedLatency {
+    count: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+}
+/** Per-service bucket used by modeServices. */
+export interface ServiceBucket extends TermsBucket {
+    errors: AggFilter;
+    client_errors: AggFilter;
+    latency: AggFilter & {
+        parsed: ScriptedMetric<ParsedLatency>;
+    };
+}
+/** Per-service bucket used by modeReport (uses errors_5xx/errors_4xx names). */
+export interface ReportServiceBucket extends TermsBucket {
+    errors_5xx: AggFilter;
+    errors_4xx: AggFilter;
+    latency: AggFilter & {
+        parsed: ScriptedMetric<ParsedLatency>;
+    };
+}
+/** Per-service bucket in modeErrors with status sub-aggregation. */
+export interface ErrorServiceBucket extends TermsBucket {
+    by_status: TermsAgg<TermsBucket<number>>;
+}
+/** Per-service bucket in modeLatency with parsed latency. */
+export interface LatencyServiceBucket extends TermsBucket {
+    parsed: ScriptedMetric<ParsedLatency>;
+}
+/** Date histogram bucket with parsed latency. */
+export interface LatencyTimeBucket extends DateHistBucket {
+    parsed: ScriptedMetric<ParsedLatency>;
+}
+/** Date histogram bucket with p95_parsed latency (Phase 2 naming). */
+export interface P95TimeBucket extends DateHistBucket {
+    p95_parsed: ScriptedMetric<ParsedLatency>;
+}
+/** modeDashboard aggregation results. */
+export interface DashboardAggs {
+    total_requests: AggFilter;
+    latency_stats: AggFilter & {
+        parsed: ScriptedMetric<ParsedLatency>;
+    };
+    [key: string]: AggFilter;
+}
+/** modeLatency aggregation results. */
+export interface LatencyAggs {
+    overall: ScriptedMetric<ParsedLatency>;
+    by_service: TermsAgg<LatencyServiceBucket>;
+    over_time: TermsAgg<LatencyTimeBucket>;
+}
+/** modeErrors aggregation results. */
+export interface ErrorsAggs {
+    by_service: TermsAgg<ErrorServiceBucket>;
+    by_status_code: TermsAgg<TermsBucket<number>>;
+    by_endpoint: TermsAgg<TermsBucket>;
+    by_error_type: TermsAgg<TermsBucket>;
+    over_time: TermsAgg<DateHistBucket>;
+    recent_errors: TopHitsAgg;
+}
+/** modeReport Phase 1 aggregation results. */
+export interface ReportP1Aggs {
+    total: AggFilter;
+    by_service: AggFilter & {
+        services: TermsAgg<ReportServiceBucket>;
+    };
+    error_total: AggFilter & {
+        over_time: TermsAgg<DateHistBucket>;
+    };
+    latency_overview: AggFilter & {
+        parsed: ScriptedMetric<ParsedLatency>;
+    };
+    [key: string]: unknown;
+}
+/** modeReport Phase 2 error detail. */
+export interface ReportErrorDetail extends AggFilter {
+    by_status_code: TermsAgg<TermsBucket<number>>;
+    by_error_type: TermsAgg<TermsBucket>;
+    by_endpoint: TermsAgg<TermsBucket>;
+    recent: TopHitsAgg;
+}
+/** modeReport Phase 2 latency detail. */
+export interface ReportLatencyDetail extends AggFilter {
+    p95_over_time: TermsAgg<P95TimeBucket>;
+}
+/** modeReport Phase 2 aggregation results. */
+export interface ReportP2Aggs {
+    error_detail?: ReportErrorDetail;
+    latency_detail?: ReportLatencyDetail;
+}
+/** modeReport Phase 3 pattern sample aggregation. */
+export interface PatternSampleAgg extends AggFilter {
+    samples: TopHitsAgg;
+}
+export interface SavedObjectAttributes {
+    title?: string;
+    description?: string;
+    visState?: string;
+    uiStateJSON?: string;
+    panelsJSON?: string;
+    optionsJSON?: string;
+    fields?: string;
+    kibanaSavedObjectMeta?: {
+        searchSourceJSON: string;
+    };
+    [key: string]: unknown;
+}
+export interface SavedObjectResponse {
+    attributes?: SavedObjectAttributes;
+    references?: SavedObjectRef[];
+}
+export interface SavedObjectRef {
+    name: string;
+    type: string;
+    id: string;
+}
+export type VisDef = [
+    string,
+    {
+        attributes: Record<string, unknown>;
+        references: SavedObjectRef[];
+    }
+];
+export interface FieldDefinition {
+    name: string;
+    type: string;
+    esTypes: string[];
+    searchable: boolean;
+    aggregatable: boolean;
+    readFromDocValues: boolean;
+}
+export interface FieldMapping {
+    type?: string;
+    fields?: Record<string, {
+        type: string;
+        ignore_above?: number;
+    }>;
+}
+export interface DashboardPanel {
+    version: string;
+    gridData: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        i: string;
+    };
+    panelIndex: string;
+    embeddableConfig: Record<string, unknown>;
+    panelRefName: string;
+}
+/** Response from GET /api/status. */
+export interface OsdStatusResponse {
+    version?: {
+        number?: string;
+        build_hash?: string;
+    };
+    status?: {
+        overall?: {
+            state?: string;
+        };
+    };
+}
+/** Response from GET /{index}/_mapping. */
+export interface IndexMappingResponse {
+    [indexName: string]: {
+        mappings?: {
+            properties?: Record<string, FieldMapping>;
+        };
+    };
+}
+/** Aggregation shape for pattern-counting queries (monitor.service + playbook). */
+export interface PatternCountAggs {
+    _total?: AggFilter;
+    [key: string]: AggFilter | undefined;
+}
+export interface SearchArgs {
+    env: string;
+    query?: string;
+    service?: string;
+    level?: string;
+    status?: string;
+    correlationId?: string;
+    hours?: number;
+    timeFrom?: string;
+    timeTo?: string;
+    mode: string;
+    limit: number;
+    interval?: string;
+    asc: boolean;
+    ids: boolean;
+    full: boolean;
+    json: boolean;
+    link: boolean;
+}
+export interface MonitorArgs {
+    mode: string;
+    service?: string;
+    hours?: number;
+    minutes?: number;
+    watch?: number;
+    from1?: string;
+    to1?: string;
+    from2?: string;
+    to2?: string;
+}
+export interface DashboardArgs {
+    validate: boolean;
+    delete: boolean;
+    name?: string;
+}

package/dist/interfaces/interfaces.js

@@ -0,0 +1,3 @@
+/** Shared TypeScript interfaces for OpenSearch log tools. */
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces/interfaces.ts"],"names":[],"mappings":"AAAA,6DAA6D"}