@endge/core 5.0.0 → 6.0.0

package/dist/features/core/modules/diagnostics/EndgeTelemetry_Module.d.ts

@@ -0,0 +1,162 @@
+import { EndgeBootContext } from '../../kernel/types/bootstrap.types';
+import { DiagnosticsAdapterRegistry } from './adapters/DiagnosticsAdapterRegistry';
+import { DiagnosticsAdapter, DiagnosticsFlushResult } from './domain/types/diagnostics-adapter.type';
+import { DiagnosticsAttributes, DiagnosticsContextProvider, DiagnosticsCounters, DiagnosticsExceptionOptions, DiagnosticsFilter, DiagnosticsInstrumentationScope, DiagnosticsListener, DiagnosticsLogInput, DiagnosticsLogOptions, DiagnosticsLogRecord, DiagnosticsRecord, DiagnosticsResource, DiagnosticsSnapshot, DiagnosticsSpanEndOptions, DiagnosticsSpanHandle, DiagnosticsSpanOptions, DiagnosticsSpanOwner, DiagnosticsSpanRecord, DiagnosticsSubscribeOptions, DiagnosticsTelemetrySnapshot, EndgeDiagnosticsConfiguration } from './domain/types/diagnostics.types';
+import { EndgeModule } from '../../../federation/EndgeModule';
+/**
+ * Telemetry-подмодуль диагностики Endge.
+ * Собирает logs и завершённые spans, хранит bounded session history и маршрутизирует records в adapters.
+ */
+export declare class EndgeTelemetry_Module extends EndgeModule implements DiagnosticsSpanOwner {
+    private readonly _adapterRegistry;
+    private _configuration;
+    private _resource;
+    private _store;
+    private readonly _configuredAdapters;
+    private readonly _manualAdapters;
+    private readonly _contextProviders;
+    private readonly _subscriptions;
+    private readonly _activeSpans;
+    private _sessionId;
+    private _recordId;
+    private _droppedByPolicy;
+    private _droppedByCapacity;
+    private _adapterFailures;
+    private _listenerFailures;
+    private _contextProviderFailures;
+    private _notifyScheduled;
+    /** Создаёт telemetry module с внешним registry adapter factories. */
+    constructor(_adapterRegistry: DiagnosticsAdapterRegistry);
+    /** Возвращает идентификатор текущей diagnostics session. */
+    get sessionId(): string;
+    /** Возвращает независимую копию effective diagnostics configuration. */
+    get configuration(): EndgeDiagnosticsConfiguration;
+    /** Возвращает независимую копию resource текущего запуска. */
+    get resource(): DiagnosticsResource;
+    /** Применяет effective configuration после разрешения build context. */
+    build(_ctx: EndgeBootContext): void;
+    /**
+     * Завершает текущую session, доставляет buffered data и освобождает adapters.
+     * После reset модуль готов к следующему boot lifecycle.
+     */
+    reset(): Promise<void>;
+    /** Применяет telemetry, outputs и routes configuration без привязки к UI. */
+    configure(configuration: EndgeDiagnosticsConfiguration, resource?: DiagnosticsResource): void;
+    /** Записывает один нормализованный structured log. */
+    log(input: DiagnosticsLogInput): DiagnosticsLogRecord | null;
+    /** Записывает log уровня TRACE. */
+    trace(body: string, options?: DiagnosticsLogOptions): DiagnosticsLogRecord | null;
+    /** Записывает log уровня DEBUG. */
+    debug(body: string, options?: DiagnosticsLogOptions): DiagnosticsLogRecord | null;
+    /** Записывает log уровня INFO. */
+    info(body: string, options?: DiagnosticsLogOptions): DiagnosticsLogRecord | null;
+    /** Записывает log уровня WARN. */
+    warn(body: string, options?: DiagnosticsLogOptions): DiagnosticsLogRecord | null;
+    /** Записывает log уровня ERROR без обязательного объекта exception. */
+    error(body: string, options?: DiagnosticsLogOptions): DiagnosticsLogRecord | null;
+    /** Записывает log уровня FATAL; метод не останавливает runtime самостоятельно. */
+    fatal(body: string, options?: DiagnosticsLogOptions): DiagnosticsLogRecord | null;
+    /** Нормализует пойманное исключение в ERROR/FATAL log с exception.* attributes. */
+    recordException(error: unknown, options?: DiagnosticsExceptionOptions): DiagnosticsLogRecord | null;
+    /** Создаёт root или child span и возвращает correlation handle. */
+    startSpan(name: string, options?: DiagnosticsSpanOptions): DiagnosticsSpanHandle;
+    /** Завершает активный span и сохраняет один итоговый span record. */
+    finishSpan(input: {
+        traceId: string;
+        spanId: string;
+        parentSpanId?: string;
+        traceFlags?: number;
+        phase?: 'authoring' | 'build' | 'runtime';
+        name: string;
+        scope: DiagnosticsInstrumentationScope;
+        startTimestamp: number;
+        attributes: DiagnosticsAttributes;
+        options?: DiagnosticsSpanEndOptions;
+    }): DiagnosticsSpanRecord | null;
+    /** Подписывает listener на общие изменения Subscribable-модуля. */
+    subscribe(listener: () => void): () => void;
+    /** Подписывает listener на отфильтрованный diagnostics stream. */
+    subscribe(filter: DiagnosticsFilter, listener: DiagnosticsListener, options?: DiagnosticsSubscribeOptions): () => void;
+    /** Возвращает read-only snapshot records, соответствующих filter. */
+    query(filter?: DiagnosticsFilter): readonly DiagnosticsRecord[];
+    /** Возвращает telemetry-часть JSON-safe diagnostics snapshot. */
+    snapshot(filter?: DiagnosticsFilter): DiagnosticsTelemetrySnapshot;
+    /** Возвращает счётчики текущей diagnostics session. */
+    getCounters(): DiagnosticsCounters;
+    /** Очищает локальную history и session counters без изменения configuration и adapters. */
+    clear(): void;
+    /** Регистрирует синхронный provider общих record attributes и возвращает функцию отключения. */
+    registerContextProvider(id: string, provider: DiagnosticsContextProvider): () => void;
+    /** Регистрирует готовый adapter для программного output и возвращает функцию отключения. */
+    registerAdapter(adapter: DiagnosticsAdapter): () => void;
+    /** Доставляет buffered data, освобождает adapter и удаляет его из registry. */
+    unregisterAdapter(adapterId: string): Promise<void>;
+    /** Проверяет один configured output через optional adapter test method. */
+    testOutput(outputId: string): Promise<boolean>;
+    /** Доставляет snapshot в указанные outputs с поддержкой best-effort semantics. */
+    deliverSnapshot(snapshot: DiagnosticsSnapshot, outputIds: readonly string[]): void;
+    /** Выполняет best-effort flush всех adapters без reset модуля. */
+    flush(): Promise<DiagnosticsFlushResult>;
+    /** Проверяет collection policy для signal и optional severity. */
+    private _canCollect;
+    /** Добавляет record в store, subscribers и matching adapter routes. */
+    private _appendRecord;
+    /** Безопасно вызывает listener, не позволяя ему сломать producer. */
+    private _notifyListener;
+    /** Проверяет record по общему subscription/route filter. */
+    private _matchesFilter;
+    /** Сравнивает scalar/array attribute values без приведения типов. */
+    private _attributeEquals;
+    /** Нормализует и redacts attributes перед попаданием в core store. */
+    private _normalizeAttributes;
+    /** Добавляет к producer attributes значения всех context providers в порядке регистрации. */
+    private _resolveRecordAttributes;
+    /** Клонирует attributes, включая array values, без повторного изменения ключей. */
+    private _cloneAttributes;
+    /** Клонирует filter, чтобы внешние mutation не меняли subscription или route. */
+    private _cloneFilter;
+    /** Замораживает record и его вложенные структуры перед публикацией потребителям. */
+    private _freezeRecord;
+    /** Проверяет имя атрибута по обязательному списку sensitive fragments. */
+    private _isSensitiveKey;
+    /** Нормализует instrumentation scope и гарантирует непустое имя. */
+    private _normalizeScope;
+    /** Нормализует diagnostics phase из explicit field или legacy endge.phase attribute. */
+    private _normalizePhase;
+    /** Нормализует correlation и отбрасывает невалидные W3C ids. */
+    private _normalizeCorrelation;
+    /** Проверяет 16-byte trace id в lowercase hexadecimal representation. */
+    private _normalizeTraceId;
+    /** Проверяет 8-byte span id в lowercase hexadecimal representation. */
+    private _normalizeSpanId;
+    /** Нормализует W3C trace flags до одного unsigned byte. */
+    private _normalizeTraceFlags;
+    /** Нормализует timestamp и использует текущее время для отсутствующего значения. */
+    private _normalizeTimestamp;
+    /** Нормализует unknown exception в безопасные строковые поля. */
+    private _normalizeException;
+    /** Возвращает ближайшее поддерживаемое базовое severity value. */
+    private _normalizeSeverity;
+    /** Создаёт новый монотонный id внутри session. */
+    private _nextRecordId;
+    /** Создаёт session id без зависимости от browser-only API. */
+    private _createSessionId;
+    /** Создаёт hexadecimal id указанной длины. */
+    private _randomHex;
+    /** Клонирует configuration без передачи mutable ссылок наружу. */
+    private _cloneConfiguration;
+    /** Клонирует JSON-safe adapter options. */
+    private _cloneAdapterOptions;
+    /** Пересоздаёт adapters enabled outputs после configuration или registry changes. */
+    private _rebuildConfiguredAdapters;
+    /** Возвращает configured или manual adapter для одного output id. */
+    private _getAdapter;
+    /** Возвращает configured output или synthetic descriptor программного adapter. */
+    private _resolveOutput;
+    /** Объединяет adapters для counters и flush, отдавая приоритет manual registration. */
+    private _allAdapters;
+    /** Нормализует optional text. */
+    private _normalizeText;
+    /** Объединяет частые notify в один microtask. */
+    private _scheduleNotify;
+}

package/dist/features/core/modules/diagnostics/adapters/ConsoleDiagnosticsAdapter.d.ts

@@ -0,0 +1,26 @@
+import { DiagnosticsAdapter, DiagnosticsAdapterFactory, DiagnosticsAdapterRecordContext, DiagnosticsAdapterSnapshotContext } from '../domain/types/diagnostics-adapter.type';
+import { DiagnosticsRecord, DiagnosticsSnapshot, EndgeDiagnosticsOutputConfiguration } from '../domain/types/diagnostics.types';
+/** Системный adapter вывода diagnostics records и snapshots в console API. */
+export declare class ConsoleDiagnosticsAdapter implements DiagnosticsAdapter {
+    readonly id: string;
+    private readonly _name;
+    private readonly _format;
+    private readonly _groupByTrace;
+    private readonly _includeTimestamp;
+    private readonly _includeScope;
+    private readonly _includeAttributes;
+    /** Создаёт console adapter из JSON-safe output options. */
+    constructor(output: EndgeDiagnosticsOutputConfiguration);
+    /** Выводит одну routed record в pretty или JSON формате. */
+    acceptRecord(record: DiagnosticsRecord, context: DiagnosticsAdapterRecordContext): void;
+    /** Выводит bounded summary снимка, не сериализуя telemetry history целиком. */
+    acceptSnapshot(snapshot: DiagnosticsSnapshot, context: DiagnosticsAdapterSnapshotContext): void;
+    /** Пишет безопасную тестовую строку без добавления record в diagnostics history. */
+    test(): void;
+    /** Формирует компактное сообщение и optional structured details. */
+    private _formatRecord;
+    /** Выбирает подходящий console method по severity или span status. */
+    private _writeRecord;
+}
+/** Factory системного console adapter. */
+export declare const CONSOLE_DIAGNOSTICS_ADAPTER_FACTORY: DiagnosticsAdapterFactory;

package/dist/features/core/modules/diagnostics/adapters/DiagnosticsAdapterRegistry.d.ts

@@ -0,0 +1,19 @@
+import { DiagnosticsAdapter, DiagnosticsAdapterCreateContext, DiagnosticsAdapterFactory } from '../domain/types/diagnostics-adapter.type';
+import { EndgeDiagnosticsOutputConfiguration } from '../domain/types/diagnostics.types';
+/** Реестр расширяемых типов diagnostics adapters. */
+export declare class DiagnosticsAdapterRegistry {
+    private readonly _factories;
+    private readonly _listeners;
+    /** Регистрирует factory по стабильному adapter type и возвращает функцию удаления. */
+    register(factory: DiagnosticsAdapterFactory): () => void;
+    /** Возвращает factory зарегистрированного adapter type. */
+    get(type: string): DiagnosticsAdapterFactory | undefined;
+    /** Возвращает список зарегистрированных adapter types. */
+    list(): readonly DiagnosticsAdapterFactory[];
+    /** Создаёт runtime adapter для одного output или возвращает null для неизвестного type. */
+    create(output: EndgeDiagnosticsOutputConfiguration, context: DiagnosticsAdapterCreateContext): DiagnosticsAdapter | null;
+    /** Подписывает listener на изменения состава factories. */
+    subscribe(listener: () => void): () => void;
+    /** Уведомляет владельца runtime adapters о необходимости пересборки. */
+    private _notify;
+}

package/dist/features/core/modules/diagnostics/adapters/SentryDiagnosticsAdapter.d.ts

@@ -0,0 +1,66 @@
+import { DiagnosticsAdapter, DiagnosticsAdapterCreateContext, DiagnosticsAdapterFactory, DiagnosticsAdapterRecordContext, DiagnosticsAdapterSnapshotContext } from '../domain/types/diagnostics-adapter.type';
+import { DiagnosticsRecord, DiagnosticsSnapshot, EndgeDiagnosticsOutputConfiguration } from '../domain/types/diagnostics.types';
+/** Системный adapter доставки Endge telemetry и snapshots в Sentry ingestion API. */
+export declare class SentryDiagnosticsAdapter implements DiagnosticsAdapter {
+    readonly id: string;
+    private readonly _name;
+    private readonly _dsn;
+    private readonly _envelopeUrl;
+    private readonly _environment?;
+    private readonly _release?;
+    private readonly _serverName?;
+    private readonly _sendSnapshots;
+    private readonly _requestTimeoutMs;
+    private readonly _tags;
+    private readonly _pending;
+    /** Создаёт Sentry adapter и разрешает variable tokens только в runtime copy options. */
+    constructor(output: EndgeDiagnosticsOutputConfiguration, context: DiagnosticsAdapterCreateContext);
+    /** Преобразует routed log в Sentry event, а завершённый span — в transaction. */
+    acceptRecord(record: DiagnosticsRecord, context: DiagnosticsAdapterRecordContext): Promise<void>;
+    /** Отправляет snapshot как отдельное событие с полным JSON attachment. */
+    acceptSnapshot(snapshot: DiagnosticsSnapshot, context: DiagnosticsAdapterSnapshotContext): Promise<void> | void;
+    /** Отправляет безопасное тестовое событие, не добавляя запись в локальную diagnostics history. */
+    test(): Promise<void>;
+    /** Ожидает завершения всех ingestion requests, начатых adapter-ом. */
+    flush(): Promise<void>;
+    /** Завершает pending delivery перед освобождением adapter. */
+    dispose(): Promise<void>;
+    /** Нормализует persisted options и разрешает только строковые runtime credentials. */
+    private _normalizeOptions;
+    /** Разбирает standard Sentry DSN и строит browser-safe envelope endpoint. */
+    private _parseDsn;
+    /** Преобразует Endge log record в Sentry event payload. */
+    private _mapLogRecord;
+    /** Преобразует завершённый Endge span в Sentry transaction payload. */
+    private _mapSpanRecord;
+    /** Добавляет общие Sentry environment, release, resource и static tags. */
+    private _baseEvent;
+    /** Формирует Sentry trace context из OpenTelemetry-compatible ids. */
+    private _traceContext;
+    /** Выделяет Sentry user context из стандартных diagnostics attributes. */
+    private _mapUser;
+    /** Собирает envelope и выполняет один ingestion request. */
+    private _sendEnvelope;
+    /** Учитывает pending request для flush и удаляет его после завершения. */
+    private _track;
+    /** Преобразует Endge severity в Sentry event level. */
+    private _mapLogLevel;
+    /** Преобразует Endge span status в Sentry trace status. */
+    private _mapSpanStatus;
+    /** Проецирует resource attributes в ограниченный набор Sentry tags. */
+    private _resourceTags;
+    /** Читает adapter tags из JSON-safe options. */
+    private _readTags;
+    /** Нормализует произвольный tags object в строковые Sentry tags. */
+    private _normalizeTags;
+    /** Возвращает непустой scalar attribute как строку. */
+    private _attributeText;
+    /** Возвращает положительное целое число или fallback. */
+    private _normalizePositiveInteger;
+    /** Создаёт 128-bit Sentry event id в lowercase hexadecimal representation. */
+    private _createEventId;
+    /** Проверяет, что unknown value является plain record. */
+    private _isRecord;
+}
+/** Factory встроенного Sentry adapter. */
+export declare const SENTRY_DIAGNOSTICS_ADAPTER_FACTORY: DiagnosticsAdapterFactory;

package/dist/features/core/modules/diagnostics/adapters/SentryDiagnosticsAdapter.types.d.ts

@@ -0,0 +1,20 @@
+import { DiagnosticsAttributeScalar } from '../domain/types/diagnostics.types';
+/** JSON-safe настройки одного Sentry diagnostics output. */
+export interface SentryDiagnosticsAdapterOptions {
+    /** DSN проекта Sentry; поддерживает `{{ VARIABLE }}` через WorkspaceVariables. */
+    dsn: string;
+    /** Имя окружения Sentry, например development или production. */
+    environment?: string;
+    /** Версия приложения, используемая Sentry Releases. */
+    release?: string;
+    /** Логическое имя runtime instance. */
+    serverName?: string;
+    /** Optional tunnel endpoint для proxying Sentry envelopes. */
+    tunnel?: string;
+    /** Отправлять diagnostics snapshots как JSON attachment. */
+    sendSnapshots?: boolean;
+    /** Timeout одного ingestion request в миллисекундах. */
+    requestTimeoutMs?: number;
+    /** Статические tags, добавляемые ко всем событиям output. */
+    tags?: Record<string, DiagnosticsAttributeScalar>;
+}

package/dist/features/core/modules/diagnostics/config/diagnostics.config.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticsSeverityNumber, EndgeDiagnosticsConfiguration } from '../domain/types/diagnostics.types';
+/** Системная diagnostics configuration для workspace без явных настроек. */
+export declare const DEFAULT_ENDGE_DIAGNOSTICS_CONFIGURATION: Readonly<EndgeDiagnosticsConfiguration>;
+/** Текстовое представление базовых значений OpenTelemetry SeverityNumber. */
+export declare const DIAGNOSTICS_SEVERITY_TEXT: Record<DiagnosticsSeverityNumber, 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL'>;

package/dist/features/core/modules/diagnostics/domain/entities/DiagnosticsRecordStore.d.ts

@@ -0,0 +1,52 @@
+import { DiagnosticsRecord, DiagnosticsSignal } from '../types/diagnostics.types';
+/** Ограниченное кольцевое хранилище diagnostic records с основными индексами. */
+export declare class DiagnosticsRecordStore {
+    private _capacity;
+    private _slots;
+    private _head;
+    private _length;
+    private readonly _byId;
+    private readonly _traceIndex;
+    private readonly _spanIndex;
+    private readonly _scopeIndex;
+    private readonly _recordsBySignal;
+    private readonly _recordsByScope;
+    /** Создаёт store с указанной максимальной ёмкостью. */
+    constructor(capacity: number);
+    /** Возвращает количество сохранённых records. */
+    get size(): number;
+    /** Изменяет ёмкость, сохраняя самые новые records. */
+    setCapacity(nextCapacity: number): void;
+    /** Добавляет record и возвращает вытесненную запись. */
+    append(record: DiagnosticsRecord): DiagnosticsRecord | null;
+    /** Полностью очищает records и индексы. */
+    clear(): void;
+    /** Возвращает records от старых к новым с необязательным ограничением хвоста. */
+    toArray(limit?: number): DiagnosticsRecord[];
+    /** Возвращает records одного trace. */
+    getByTraceId(traceId: string, limit?: number): DiagnosticsRecord[];
+    /** Возвращает records, связанные с одним span. */
+    getBySpanId(spanId: string, limit?: number): DiagnosticsRecord[];
+    /** Возвращает records одного instrumentation scope. */
+    getByScope(scopeName: string, limit?: number): DiagnosticsRecord[];
+    /** Возвращает количества records по signal. */
+    getRecordsBySignal(): Partial<Record<DiagnosticsSignal, number>>;
+    /** Возвращает количества records по instrumentation scope. */
+    getRecordsByScope(): Record<string, number>;
+    /** Очищает внутреннее состояние без пересоздания массива slots. */
+    private _clearState;
+    /** Возвращает records по готовому индексу. */
+    private _fromIndex;
+    /** Добавляет record во все индексы store. */
+    private _addIndexes;
+    /** Удаляет вытесненный record из всех индексов store. */
+    private _removeIndexes;
+    /** Добавляет id в индекс по строковому ключу. */
+    private _addToIndex;
+    /** Удаляет id из индекса и очищает пустую корзину. */
+    private _removeFromIndex;
+    /** Изменяет счётчик и удаляет нулевое значение. */
+    private _bump;
+    /** Нормализует ёмкость store до положительного целого числа. */
+    private _normalizeCapacity;
+}

package/dist/features/core/modules/diagnostics/domain/entities/DiagnosticsSpan.d.ts

@@ -0,0 +1,29 @@
+import { DiagnosticsAttributes, DiagnosticsExceptionOptions, DiagnosticsInstrumentationScope, DiagnosticsLogInput, DiagnosticsLogRecord, DiagnosticsSpanEndOptions, DiagnosticsSpanHandle, DiagnosticsSpanOptions, DiagnosticsSpanOwner, DiagnosticsSpanRecord } from '../types/diagnostics.types';
+/** Управляет одним активным span и завершает его через owner-модуль. */
+export declare class DiagnosticsSpan implements DiagnosticsSpanHandle {
+    private readonly _owner;
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | undefined;
+    private readonly _traceFlags;
+    private readonly _name;
+    private readonly _scope;
+    private readonly _startTimestamp;
+    private readonly _phase;
+    private _ended;
+    private _attributes;
+    /** Создаёт handle с уже нормализованной correlation и scope. */
+    constructor(_owner: DiagnosticsSpanOwner, traceId: string, spanId: string, parentSpanId: string | undefined, _traceFlags: number | undefined, _name: string, _scope: DiagnosticsInstrumentationScope, _startTimestamp: number, attributes: DiagnosticsAttributes, _phase: DiagnosticsSpanOptions['phase']);
+    /** Показывает, был ли span уже завершён. */
+    get isEnded(): boolean;
+    /** Добавляет или заменяет структурированные атрибуты активного span. */
+    setAttributes(attributes: DiagnosticsAttributes): void;
+    /** Создаёт дочерний span с correlation текущего handle. */
+    startChild(name: string, options?: Omit<DiagnosticsSpanOptions, 'traceId' | 'parentSpanId'>): DiagnosticsSpanHandle;
+    /** Записывает log с автоматической correlation текущего span. */
+    log(input: Omit<DiagnosticsLogInput, 'traceId' | 'spanId'>): DiagnosticsLogRecord | null;
+    /** Записывает exception как связанный ERROR/FATAL log. */
+    recordException(error: unknown, options?: DiagnosticsExceptionOptions): DiagnosticsLogRecord | null;
+    /** Идемпотентно завершает span и возвращает сохранённый record. */
+    end(options?: DiagnosticsSpanEndOptions): DiagnosticsSpanRecord | null;
+}