@capxul/observability 4.2.0 → 4.20.0-beta.10

package/README.md

@@ -94,3 +94,17 @@ vp run --filter @capxul/observability build
 
 Read [`CONTEXT.md`](./CONTEXT.md) before changing event names, schemas,
 redaction, journeys, or adapter behavior.
+
+## Engineering composition
+
+Import `makeEngineeringTelemetryLayer` and `flushEngineeringTelemetry` from
+`@capxul/observability/engineering`. The layer shares OTLP logs, traces, and delta
+metrics. The flush Effect attempts delivery without claiming ingestion. Optional
+`enabled` stops collection for the acquired layer when false or when its callback
+throws. `shutdownTimeout` applies per exporter; a host can set it to zero after
+it runs an explicit flush under its own total deadline.
+
+Set `privacy: "minimal"` for hosts that must export only closed operation/error
+codes, timings, environment, and validated correlation. This opt-in removes
+free-form logs, provider messages, URLs, bodies, and source paths, including
+span exception events. Default consumers retain the existing redaction policy.

package/dist/engineering.d.mts

@@ -1,5 +1,43 @@
-import { Layer, Tracer } from "effect";
-import { OtlpExporter } from "effect/unstable/observability";
+import { Context, Duration, Effect, Layer, Logger, Metric, References, Tracer } from "effect";
+import { HttpClient, HttpClientError } from "effect/unstable/http";
+import { OtlpExporter, OtlpSerialization } from "effect/unstable/observability";
+//#region src/engineering-delivery.d.ts
+/** Fixed admission limits for one CLI invocation and its SDK client. */
+declare const CLI_ENGINEERING_LIMITS: Readonly<{
+  records: 80;
+  ordinaryRecords: 64;
+  recordBytes: 16384;
+  requests: 5;
+  ordinaryRequests: 2;
+  requestBytes: 1572864;
+  metricSeries: 16;
+  requestTimeoutMs: 1000;
+}>;
+type MetricEntry = Metric.Metric.Metadata<unknown, unknown>;
+interface CliEngineeringStats {
+  readonly records: number;
+  readonly reservedRecordBytes: number;
+  readonly peakRecords: number;
+  readonly peakReservedRecordBytes: number;
+  readonly activeRequests: number;
+  readonly requestBytes: number;
+  readonly peakRequests: number;
+  readonly peakRequestBytes: number;
+  /** Rejected records, fields, metric registrations and export attempts; not delivered-event count. */
+  readonly dropped: number;
+  readonly metricSeries: number;
+}
+/** Shared, closure-owned admission state; no queue or mutable counters are exposed. */
+declare function makeCliEngineeringBudget(): Readonly<{
+  metricRegistry: Map<string, MetricEntry>;
+  emptyMetricRegistry: () => Map<string, MetricEntry>;
+  drop: () => void;
+  admitRecord(terminal: boolean): (() => void) | undefined;
+  admitRequest(bytes: number, terminal: boolean): (() => void) | undefined;
+  snapshot(): CliEngineeringStats;
+}>;
+type CliEngineeringBudget = ReturnType<typeof makeCliEngineeringBudget>;
+//#endregion
 //#region src/engineering.d.ts
 type EngineeringProducer = "browser" | "server";
 declare const ENGINEERING_CAPXUL_ENVS: readonly ["development", "staging", "production", "local"];
@@ -11,15 +49,30 @@ interface EngineeringTelemetryConfig {
   readonly producer: EngineeringProducer;
   readonly sdkVersion: string;
   readonly serviceName?: string;
+  /** False or a thrown callback disables this acquired layer for its remaining lifetime. */
+  readonly enabled?: boolean | (() => boolean);
+  /** Codes, timings, and correlation only; no free text or private source paths. */
+  readonly privacy?: "minimal";
+  readonly shutdownTimeout?: Duration.Input;
+  readonly exportInterval?: Duration.Input;
+  /** CLI-only shared admission and transport lifetime. Omission preserves host defaults. */
+  readonly deliveryBudget?: CliEngineeringBudget;
 }
 declare const traceHeaderFilter: (_name: string) => boolean;
 declare const postHogOtlpEndpoints: (host: string) => {
   readonly logs: `${string}/i/v1/logs`;
   readonly traces: `${string}/i/v1/traces`;
+  readonly metrics: `${string}/i/v1/metrics`;
 };
 /** Preserve domain exits while preventing the OTLP serializer from seeing raw causes. */
-declare const makeLeakSafeEngineeringTracer: (delegate: Tracer.Tracer) => Tracer.Tracer;
+declare const makeLeakSafeEngineeringTracer: (delegate: Tracer.Tracer, enabled?: () => boolean) => Tracer.Tracer;
+/** Attempt to drain all engineering signals; completion does not prove ingestion. */
+declare const flushEngineeringTelemetry: Effect.Effect<void, never, OtlpExporter.Flusher>;
+declare const EngineeringLog_base: Context.ServiceClass<EngineeringLog, "capxul/EngineeringLog", Logger.Logger<unknown, void>>;
+declare class EngineeringLog extends EngineeringLog_base {}
+/** Deliver an owned engineering record without changing the caller's console verbosity. */
+declare const logEngineeringInfo: (message: string, attributes: Readonly<Record<string, unknown>>) => Effect.Effect<void, never, never>;
 /** Shared browser/server OTLP layer. OtlpLogger merges with incumbent loggers once. */
-declare const makeEngineeringTelemetryLayer: (config: EngineeringTelemetryConfig) => Layer.Layer<OtlpExporter.Flusher, never, never>;
+declare const makeEngineeringTelemetryLayer: (config: EngineeringTelemetryConfig) => Layer.Layer<EngineeringLog | OtlpExporter.Flusher, never, never>;
 //#endregion
-export { ENGINEERING_CAPXUL_ENVS, EngineeringCapxulEnv, EngineeringProducer, EngineeringTelemetryConfig, makeEngineeringTelemetryLayer, makeLeakSafeEngineeringTracer, postHogOtlpEndpoints, traceHeaderFilter };
+export { CLI_ENGINEERING_LIMITS, type CliEngineeringBudget, type CliEngineeringStats, ENGINEERING_CAPXUL_ENVS, EngineeringCapxulEnv, EngineeringProducer, EngineeringTelemetryConfig, flushEngineeringTelemetry, logEngineeringInfo, makeCliEngineeringBudget, makeEngineeringTelemetryLayer, makeLeakSafeEngineeringTracer, postHogOtlpEndpoints, traceHeaderFilter };