@nodii/telemetry 0.0.2 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +223 -1
  2. package/dist/active-span.d.ts +12 -0
  3. package/dist/active-span.d.ts.map +1 -0
  4. package/dist/active-span.js +20 -0
  5. package/dist/active-span.js.map +1 -0
  6. package/dist/agent-invocable.d.ts +24 -0
  7. package/dist/agent-invocable.d.ts.map +1 -0
  8. package/dist/agent-invocable.js +64 -0
  9. package/dist/agent-invocable.js.map +1 -0
  10. package/dist/audit.d.ts +47 -0
  11. package/dist/audit.d.ts.map +1 -0
  12. package/dist/audit.js +78 -0
  13. package/dist/audit.js.map +1 -0
  14. package/dist/context.d.ts +40 -0
  15. package/dist/context.d.ts.map +1 -0
  16. package/dist/context.js +70 -0
  17. package/dist/context.js.map +1 -0
  18. package/dist/index.d.ts +18 -2
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +29 -5
  21. package/dist/index.js.map +1 -1
  22. package/dist/init.d.ts +39 -0
  23. package/dist/init.d.ts.map +1 -0
  24. package/dist/init.js +114 -0
  25. package/dist/init.js.map +1 -0
  26. package/dist/intent.d.ts +21 -0
  27. package/dist/intent.d.ts.map +1 -0
  28. package/dist/intent.js +123 -0
  29. package/dist/intent.js.map +1 -0
  30. package/dist/logger.d.ts +19 -0
  31. package/dist/logger.d.ts.map +1 -0
  32. package/dist/logger.js +99 -0
  33. package/dist/logger.js.map +1 -0
  34. package/dist/metrics.d.ts +53 -0
  35. package/dist/metrics.d.ts.map +1 -0
  36. package/dist/metrics.js +152 -0
  37. package/dist/metrics.js.map +1 -0
  38. package/dist/otlp-adapter.d.ts +44 -0
  39. package/dist/otlp-adapter.d.ts.map +1 -0
  40. package/dist/otlp-adapter.js +351 -0
  41. package/dist/otlp-adapter.js.map +1 -0
  42. package/dist/outbox-emit.d.ts +34 -0
  43. package/dist/outbox-emit.d.ts.map +1 -0
  44. package/dist/outbox-emit.js +58 -0
  45. package/dist/outbox-emit.js.map +1 -0
  46. package/dist/redaction.d.ts +51 -0
  47. package/dist/redaction.d.ts.map +1 -0
  48. package/dist/redaction.js +173 -0
  49. package/dist/redaction.js.map +1 -0
  50. package/dist/sdk-counters.d.ts +14 -0
  51. package/dist/sdk-counters.d.ts.map +1 -0
  52. package/dist/sdk-counters.js +42 -0
  53. package/dist/sdk-counters.js.map +1 -0
  54. package/dist/tracer.d.ts +63 -0
  55. package/dist/tracer.d.ts.map +1 -0
  56. package/dist/tracer.js +214 -0
  57. package/dist/tracer.js.map +1 -0
  58. package/dist/types.d.ts +230 -0
  59. package/dist/types.d.ts.map +1 -0
  60. package/dist/types.js +66 -0
  61. package/dist/types.js.map +1 -0
  62. package/dist/uuid.d.ts +5 -0
  63. package/dist/uuid.d.ts.map +1 -0
  64. package/dist/uuid.js +34 -0
  65. package/dist/uuid.js.map +1 -0
  66. package/package.json +28 -6
package/dist/index.js CHANGED
@@ -1,7 +1,31 @@
1
- // @nodii/telemetry — placeholder at v0.0.1.
2
- // Implementation lands at v0.1.0 per the locked feature_doc.
1
+ // @nodii/telemetry — public barrel.
3
2
  //
4
- // Spec: https://planning.dev.nucleus-cloud.in/api/v1/feature-docs?serviceId=nodii-libs&docKey=telemetry
5
- export const LIB_NAME = "telemetry";
6
- export const VERSION = "0.0.1";
3
+ // Spec: planning hub feature_doc serviceId=nodii-libs docKey=telemetry v3
4
+ //
5
+ // Use subpath imports for tree-shaking:
6
+ // - @nodii/telemetry/grpc — gRPC interceptor + client wrapper
7
+ // - @nodii/telemetry/bullmq — BullMQ producer + consumer wrappers
8
+ // - @nodii/telemetry/outbox — Outbox emit + drainer instrumentation
9
+ // - @nodii/telemetry/system-process — System-process adapter
10
+ // - @nodii/telemetry/lambda — Lambda lifecycle wrapper
11
+ //
12
+ // Top-level barrel re-exports the public surface so the common-case
13
+ // import works:
14
+ //
15
+ // import { initTelemetry, logger, tracer, metrics, audit, intent,
16
+ // agentInvocable, withSpanAttributes, getSagaTracer,
17
+ // type NodiiContext } from '@nodii/telemetry';
18
+ export { initTelemetry } from "./init";
19
+ export { forceFlush, getOtlpAdapterHandle, installOtlpAdapter, shutdownOtlpAdapter, } from "./otlp-adapter";
20
+ export { logger } from "./logger";
21
+ export { tracer, withSpanAttributes, getSagaTracer } from "./tracer";
22
+ export { metrics, MetricVocabularyError } from "./metrics";
23
+ export { audit } from "./audit";
24
+ export { intent, IntentTypeNotRegistered } from "./intent";
25
+ export { agentInvocable, readAgentRegistry, AGENT_INVOCABLE_METADATA, } from "./agent-invocable";
26
+ export { getContext, requireContext, withContext, } from "./context";
27
+ export { isPiiFieldName, redactString, redactFields, PII_FIELD_NAMES, } from "./redaction";
28
+ export { uuidv7, isUuidv7 } from "./uuid";
29
+ export { TelemetryNotInitialized } from "./types";
30
+ export { DEFAULT_SAMPLING_CONFIG, METRIC_FAMILIES, AGENT_INVOCABLE_SIDE_EFFECTS, } from "./types";
7
31
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,6DAA6D;AAC7D,EAAE;AACF,wGAAwG;AAExG,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;AACpC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,EAAE;AACF,wCAAwC;AACxC,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,gEAAgE;AAChE,kEAAkE;AAClE,EAAE;AACF,oEAAoE;AACpE,gBAAgB;AAChB,EAAE;AACF,oEAAoE;AACpE,gEAAgE;AAChE,0DAA0D;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAErE,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAM3D,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAwBlD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,GAC7B,MAAM,SAAS,CAAC"}
package/dist/init.d.ts ADDED
@@ -0,0 +1,39 @@
1
+ import { type AutoInstrumentationConfig, type ErrorHandlingConfig, type InitTelemetryConfig, type IntentTypeRegistry, type MetricVocabularyRegistry, type SamplingConfig } from "./types";
2
+ /** Snapshot of the resolved init config that runtime modules read from. */
3
+ export interface ResolvedTelemetryConfig {
4
+ serviceName: string;
5
+ env: string;
6
+ serviceVersion?: string;
7
+ deploymentRegion?: string;
8
+ otlpEndpoint?: string;
9
+ vocabularyRegistry: MetricVocabularyRegistry;
10
+ intentTypes: IntentTypeRegistry;
11
+ autoInstrumentation: Required<AutoInstrumentationConfig>;
12
+ samplingConfig: SamplingConfig;
13
+ errorHandling: ErrorHandlingConfig;
14
+ resourceAttributes: Record<string, string | number | boolean>;
15
+ }
16
+ /**
17
+ * Public bootstrap. Per D152 — call once at process start. Subsequent
18
+ * calls warn-log + no-op.
19
+ *
20
+ * When `otlpEndpoint` is supplied (or `NODII_TELEMETRY_OTLP_ENDPOINT`
21
+ * env var is set), real OTLP gRPC exporters are wired up by
22
+ * `installOtlpAdapter()` per D153 + D154. Spans, logs, and metrics
23
+ * flow into the configured collector immediately.
24
+ *
25
+ * If `disableOtlp: true` is passed, the no-op emitters/sinks/backends
26
+ * stay in place — for tests that want to assert SDK semantics without
27
+ * a live collector.
28
+ */
29
+ export declare function initTelemetry(config: InitTelemetryConfig): void;
30
+ /**
31
+ * SDK-internal accessor. Throws `TelemetryNotInitialized` if called
32
+ * before `initTelemetry()`. Every public API funnels through this.
33
+ */
34
+ export declare function requireTelemetry(): ResolvedTelemetryConfig;
35
+ /** Returns null when not initialized — for SDK internals that can no-op. */
36
+ export declare function getTelemetryOrNull(): ResolvedTelemetryConfig | null;
37
+ /** Test-only reset. NOT exported through the public barrel. */
38
+ export declare function _resetForTests(): void;
39
+ //# sourceMappingURL=init.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,yBAAyB,EAE9B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EAEpB,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,wBAAwB,CAAC;IAC7C,WAAW,EAAE,kBAAkB,CAAC;IAChC,mBAAmB,EAAE,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IACzD,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,mBAAmB,CAAC;IACnC,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC/D;AA8BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAqD/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,uBAAuB,CAK1D;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,uBAAuB,GAAG,IAAI,CAEnE;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,IAAI,IAAI,CAErC"}
package/dist/init.js ADDED
@@ -0,0 +1,114 @@
1
+ // Bootstrap — `initTelemetry()`. Per D152: single explicit init at
2
+ // process start, NOT side-effect import.
3
+ //
4
+ // Behavior:
5
+ // - First call: validates config, stores it in a process-local
6
+ // singleton, marks the SDK ready.
7
+ // - Subsequent calls: warn-log + no-op (per § 5.1).
8
+ // - Any public-API call before init: throws `TelemetryNotInitialized`.
9
+ import { installOtlpAdapter } from "./otlp-adapter";
10
+ import { DEFAULT_SAMPLING_CONFIG, TelemetryNotInitialized, } from "./types";
11
+ /** D154 defaults. */
12
+ const AUTO_INSTR_DEFAULTS = {
13
+ httpServer: true,
14
+ httpClient: true,
15
+ grpcServer: true,
16
+ grpcClient: true,
17
+ bullmqProducer: true,
18
+ bullmqConsumer: true,
19
+ pgQuerySpans: true,
20
+ hostMetrics: true,
21
+ logAutoStamping: true,
22
+ resourceAttributes: true,
23
+ piiRedaction: true,
24
+ redisSpans: false,
25
+ dnsLookups: false,
26
+ fileSystem: false,
27
+ pgDetailedStatement: false,
28
+ };
29
+ /** D153 defaults. */
30
+ const ERROR_HANDLING_DEFAULTS = {
31
+ otlpSendingQueueSize: 5000,
32
+ dropOnFull: true,
33
+ };
34
+ /** Process-local singleton; null until `initTelemetry()` runs. */
35
+ let resolved = null;
36
+ /**
37
+ * Public bootstrap. Per D152 — call once at process start. Subsequent
38
+ * calls warn-log + no-op.
39
+ *
40
+ * When `otlpEndpoint` is supplied (or `NODII_TELEMETRY_OTLP_ENDPOINT`
41
+ * env var is set), real OTLP gRPC exporters are wired up by
42
+ * `installOtlpAdapter()` per D153 + D154. Spans, logs, and metrics
43
+ * flow into the configured collector immediately.
44
+ *
45
+ * If `disableOtlp: true` is passed, the no-op emitters/sinks/backends
46
+ * stay in place — for tests that want to assert SDK semantics without
47
+ * a live collector.
48
+ */
49
+ export function initTelemetry(config) {
50
+ if (resolved) {
51
+ // eslint-disable-next-line no-console
52
+ console.warn("[@nodii/telemetry] initTelemetry() called more than once; ignoring subsequent call.");
53
+ return;
54
+ }
55
+ if (!config.serviceName) {
56
+ throw new Error("initTelemetry: `serviceName` is required.");
57
+ }
58
+ if (!config.env) {
59
+ throw new Error("initTelemetry: `env` is required.");
60
+ }
61
+ const otlpEndpoint = config.otlpEndpoint ?? process.env.NODII_TELEMETRY_OTLP_ENDPOINT;
62
+ resolved = {
63
+ serviceName: config.serviceName,
64
+ env: config.env,
65
+ serviceVersion: config.serviceVersion,
66
+ deploymentRegion: config.deploymentRegion,
67
+ otlpEndpoint,
68
+ vocabularyRegistry: config.vocabularyRegistry ?? {},
69
+ intentTypes: config.intentTypes ?? {},
70
+ autoInstrumentation: {
71
+ ...AUTO_INSTR_DEFAULTS,
72
+ ...config.autoInstrumentation,
73
+ },
74
+ samplingConfig: config.samplingConfig ?? DEFAULT_SAMPLING_CONFIG,
75
+ errorHandling: {
76
+ ...ERROR_HANDLING_DEFAULTS,
77
+ ...config.errorHandling,
78
+ },
79
+ resourceAttributes: config.resourceAttributes ?? {},
80
+ };
81
+ // D153/D154 — wire real OTLP exporters when an endpoint is present
82
+ // and OTLP isn't explicitly disabled. The adapter replaces the no-op
83
+ // SpanEmitter / LogSink / MetricsBackend with real OTel SDK pipelines.
84
+ if (otlpEndpoint && !config.disableOtlp) {
85
+ installOtlpAdapter({
86
+ serviceName: resolved.serviceName,
87
+ env: resolved.env,
88
+ serviceVersion: resolved.serviceVersion,
89
+ deploymentRegion: resolved.deploymentRegion,
90
+ otlpEndpoint,
91
+ errorHandling: resolved.errorHandling,
92
+ resourceAttributes: resolved.resourceAttributes,
93
+ });
94
+ }
95
+ }
96
+ /**
97
+ * SDK-internal accessor. Throws `TelemetryNotInitialized` if called
98
+ * before `initTelemetry()`. Every public API funnels through this.
99
+ */
100
+ export function requireTelemetry() {
101
+ if (!resolved) {
102
+ throw new TelemetryNotInitialized();
103
+ }
104
+ return resolved;
105
+ }
106
+ /** Returns null when not initialized — for SDK internals that can no-op. */
107
+ export function getTelemetryOrNull() {
108
+ return resolved;
109
+ }
110
+ /** Test-only reset. NOT exported through the public barrel. */
111
+ export function _resetForTests() {
112
+ resolved = null;
113
+ }
114
+ //# sourceMappingURL=init.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,21 @@
1
+ declare function begin(typeName: string, payload?: Record<string, unknown>): Promise<string>;
2
+ declare function complete(id: string, result?: Record<string, unknown>): Promise<void>;
3
+ declare function abandon(id: string, reason: string): Promise<void>;
4
+ declare function progress(_id: string, _payload?: Record<string, unknown>): void;
5
+ declare function current(): string | null;
6
+ /** Thrown by `intent.begin` when the type isn't in the registry (D155 HARD). */
7
+ export declare class IntentTypeNotRegistered extends Error {
8
+ readonly typeName: string;
9
+ constructor(typeName: string);
10
+ }
11
+ /** Test-only stack reset. */
12
+ export declare function _resetIntentStackForTests(): void;
13
+ export declare const intent: {
14
+ readonly begin: typeof begin;
15
+ readonly progress: typeof progress;
16
+ readonly complete: typeof complete;
17
+ readonly abandon: typeof abandon;
18
+ readonly current: typeof current;
19
+ };
20
+ export {};
21
+ //# sourceMappingURL=intent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAoCA,iBAAe,KAAK,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,CAyBjB;AAED,iBAAe,QAAQ,CACrB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,iBAAe,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhE;AAED,iBAAS,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAGvE;AAED,iBAAS,OAAO,IAAI,MAAM,GAAG,IAAI,CAEhC;AAsBD,gFAAgF;AAChF,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAM7C;AAED,6BAA6B;AAC7B,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC"}
package/dist/intent.js ADDED
@@ -0,0 +1,123 @@
1
+ // Intent lifecycle per D46 + D155.
2
+ //
3
+ // API: `intent.begin/progress/complete/abandon/current`.
4
+ // begin sync UUIDv7 mint + async outbox `core.intent.begun.v1`;
5
+ // HARD validates against intent_types registry (D155).
6
+ // Activates ALS context: sets `intent_id` on the current
7
+ // NodiiContext via `_setIntentIdInCurrentScope`.
8
+ // progress no-op stub at v0.1.0 per M02 carry-forward (D155). Kept
9
+ // on the surface so callers don't break when the real
10
+ // behavior lands.
11
+ // complete emits outbox `core.intent.completed.v1`; deactivates
12
+ // context (intent_id back to null OR to the parent in the
13
+ // nested-begin stack, see below).
14
+ // abandon emits outbox `core.intent.abandoned.v1`; deactivates
15
+ // context same as complete.
16
+ // current sync ALS read; returns the active intent_id or null.
17
+ //
18
+ // Nested begins stack by ID match (D155). The library tracks an
19
+ // in-process stack keyed by trailing intent_id; complete/abandon pop
20
+ // the matching entry. If a complete/abandon arrives for an id not at
21
+ // the top of the stack, we still emit the event but log a warning —
22
+ // nested-begin discipline is a caller-side rule.
23
+ import { _setIntentIdInCurrentScope, getContext } from "./context";
24
+ import { requireTelemetry } from "./init";
25
+ import { emitOutbox } from "./outbox-emit";
26
+ import { uuidv7 } from "./uuid";
27
+ /** Per-typeName runtime registry; populated by `initTelemetry`. */
28
+ function intentTypeDef(typeName) {
29
+ const cfg = requireTelemetry();
30
+ return cfg.intentTypes[typeName] ?? null;
31
+ }
32
+ const stack = [];
33
+ async function begin(typeName, payload) {
34
+ const def = intentTypeDef(typeName);
35
+ if (!def) {
36
+ throw new IntentTypeNotRegistered(typeName);
37
+ }
38
+ // D45/D46 (E5 reframe): per-flow server/client mintable enforcement
39
+ // is a runtime concern that the gateway / SDK middleware should set
40
+ // via context; for v0.1.0 we accept all begins from server-side code
41
+ // and rely on the gateway to mint for HTTP-initiated. The flag is
42
+ // surfaced on the def so consumers can branch if they need to.
43
+ const id = uuidv7();
44
+ stack.push(id);
45
+ _setIntentIdInCurrentScope(id);
46
+ await emitOutbox({
47
+ topic: "core.intent.begun.v1",
48
+ event_id: id,
49
+ schema_version: 1,
50
+ payload: {
51
+ intent_type: typeName,
52
+ timeout_seconds: def.timeout_seconds,
53
+ payload: payload ?? null,
54
+ },
55
+ });
56
+ return id;
57
+ }
58
+ async function complete(id, result) {
59
+ requireTelemetry();
60
+ popStack(id, "complete");
61
+ _setIntentIdInCurrentScope(currentStackTop());
62
+ await emitOutbox({
63
+ topic: "core.intent.completed.v1",
64
+ event_id: id,
65
+ schema_version: 1,
66
+ payload: { intent_id: id, result: result ?? null },
67
+ });
68
+ }
69
+ async function abandon(id, reason) {
70
+ requireTelemetry();
71
+ popStack(id, "abandon");
72
+ _setIntentIdInCurrentScope(currentStackTop());
73
+ await emitOutbox({
74
+ topic: "core.intent.abandoned.v1",
75
+ event_id: id,
76
+ schema_version: 1,
77
+ payload: { intent_id: id, reason },
78
+ });
79
+ }
80
+ function progress(_id, _payload) {
81
+ // No-op at v0.1.0 per D155 § M02 carry-forward. Surface kept stable
82
+ // so callers don't break when behavior lands at a later version.
83
+ }
84
+ function current() {
85
+ return getContext()?.intent_id ?? null;
86
+ }
87
+ function popStack(id, op) {
88
+ const idx = stack.lastIndexOf(id);
89
+ if (idx === -1) {
90
+ // Not in stack — likely a misuse, but per D155 we still emit the
91
+ // event so the outbox stays a faithful chronology. Log a warning.
92
+ // eslint-disable-next-line no-console
93
+ console.warn(`[@nodii/telemetry] intent.${op}(${id}) called but id is not on the active stack; emitting event anyway.`);
94
+ return;
95
+ }
96
+ // Pop entries above this one too (treats out-of-order as orphaned
97
+ // begins — they get implicitly abandoned for the in-process stack).
98
+ stack.length = idx;
99
+ }
100
+ function currentStackTop() {
101
+ return stack.length > 0 ? (stack[stack.length - 1] ?? null) : null;
102
+ }
103
+ /** Thrown by `intent.begin` when the type isn't in the registry (D155 HARD). */
104
+ export class IntentTypeNotRegistered extends Error {
105
+ typeName;
106
+ constructor(typeName) {
107
+ super(`intent type "${typeName}" is not registered. Add it to the intent_types registry passed to initTelemetry().`);
108
+ this.typeName = typeName;
109
+ this.name = "IntentTypeNotRegistered";
110
+ }
111
+ }
112
+ /** Test-only stack reset. */
113
+ export function _resetIntentStackForTests() {
114
+ stack.length = 0;
115
+ }
116
+ export const intent = {
117
+ begin,
118
+ progress,
119
+ complete,
120
+ abandon,
121
+ current,
122
+ };
123
+ //# sourceMappingURL=intent.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"intent.js","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,19 @@
1
+ import type { LogEnvelope } from "./types";
2
+ /** A sink that consumes formed log envelopes. Default = JSON to stdio. */
3
+ export type LogSink = (envelope: LogEnvelope, fields: Record<string, unknown>) => void;
4
+ /**
5
+ * SDK-internal: the OTel adapter installs an OTLP-log sink in TS-12.
6
+ * Public callers MUST NOT call this; the override is for internal
7
+ * substitution only (and tests).
8
+ */
9
+ export declare function _setLogSink(s: LogSink): void;
10
+ /** Test-only restore. */
11
+ export declare function _resetLogSinkForTests(): void;
12
+ /** D13/D14 logger. Envelope fields are SDK-injected; do not supply them. */
13
+ export declare const logger: {
14
+ readonly debug: (msg: string, fields?: Record<string, unknown>) => void;
15
+ readonly info: (msg: string, fields?: Record<string, unknown>) => void;
16
+ readonly warn: (msg: string, fields?: Record<string, unknown>) => void;
17
+ readonly error: (msg: string, fields?: Record<string, unknown>) => void;
18
+ };
19
+ //# sourceMappingURL=logger.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,SAAS,CAAC;AAErD,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG,CACpB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,IAAI,CAAC;AAIV;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAE5C;AAED,yBAAyB;AACzB,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AA+DD,4EAA4E;AAC5E,eAAO,MAAM,MAAM;0BACN,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;yBAGhD,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;yBAG/C,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;0BAG9C,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;CAGlD,CAAC"}
package/dist/logger.js ADDED
@@ -0,0 +1,99 @@
1
+ // Logger per D13/D14/D15.
2
+ //
3
+ // API:
4
+ // logger.debug | info | warn | error (msg, fields?)
5
+ //
6
+ // The 11-field envelope is auto-attached from initTelemetry config +
7
+ // active NodiiContext + active OTel span. Caller passes only `msg` +
8
+ // optional `fields`. Fields go through the D15 redaction passes
9
+ // (structured key + regex on string values) before emission. Failure
10
+ // in either pass = drop the line + bump
11
+ // `telemetry.sdk.redaction_failure_total{reason}` (D15 fail-closed).
12
+ //
13
+ // Sink: the default sink writes JSON to stdout/stderr. Real OTel-LP
14
+ // export wiring is deferred to TS-12; the sink is a single injection
15
+ // point that the OTel adapter replaces.
16
+ import { getActiveSpan } from "./active-span";
17
+ import { getContext } from "./context";
18
+ import { requireTelemetry } from "./init";
19
+ import { attemptRedactFields, attemptRedactString } from "./redaction";
20
+ import { incSdkCounter } from "./sdk-counters";
21
+ let sink = defaultJsonSink;
22
+ /**
23
+ * SDK-internal: the OTel adapter installs an OTLP-log sink in TS-12.
24
+ * Public callers MUST NOT call this; the override is for internal
25
+ * substitution only (and tests).
26
+ */
27
+ export function _setLogSink(s) {
28
+ sink = s;
29
+ }
30
+ /** Test-only restore. */
31
+ export function _resetLogSinkForTests() {
32
+ sink = defaultJsonSink;
33
+ }
34
+ function defaultJsonSink(envelope, fields) {
35
+ const line = JSON.stringify({ ...envelope, ...fields });
36
+ if (envelope.level === "error" || envelope.level === "warn") {
37
+ // eslint-disable-next-line no-console
38
+ process.stderr.write(`${line}\n`);
39
+ }
40
+ else {
41
+ // eslint-disable-next-line no-console
42
+ process.stdout.write(`${line}\n`);
43
+ }
44
+ }
45
+ function emit(level, msg, fields) {
46
+ const cfg = requireTelemetry();
47
+ const ctx = getContext();
48
+ // D15 redaction (fail-closed). Run BOTH passes before forming the
49
+ // envelope; if either throws, drop the line + bump the counter.
50
+ const msgResult = attemptRedactString(msg);
51
+ if (!msgResult.ok) {
52
+ incSdkCounter("telemetry.sdk.redaction_failure_total", {
53
+ reason: msgResult.reason,
54
+ });
55
+ return;
56
+ }
57
+ const fieldsResult = fields
58
+ ? attemptRedactFields(fields)
59
+ : { ok: true, redacted: {} };
60
+ if (!fieldsResult.ok) {
61
+ incSdkCounter("telemetry.sdk.redaction_failure_total", {
62
+ reason: fieldsResult.reason,
63
+ });
64
+ return;
65
+ }
66
+ const span = getActiveSpan();
67
+ const envelope = {
68
+ level,
69
+ ts: new Date().toISOString(),
70
+ msg: msgResult.redacted,
71
+ service: cfg.serviceName,
72
+ env: cfg.env,
73
+ tenant_id: ctx?.tenant_id ?? "",
74
+ user_id: ctx?.user_id ?? null,
75
+ on_behalf_of: ctx?.on_behalf_of ?? null,
76
+ actor_type: ctx?.actor_type,
77
+ request_id: ctx?.request_id ?? "",
78
+ trace_id: span?.trace_id ?? null,
79
+ span_id: span?.span_id ?? null,
80
+ intent_id: ctx?.intent_id ?? null,
81
+ };
82
+ sink(envelope, fieldsResult.redacted);
83
+ }
84
+ /** D13/D14 logger. Envelope fields are SDK-injected; do not supply them. */
85
+ export const logger = {
86
+ debug(msg, fields) {
87
+ emit("debug", msg, fields);
88
+ },
89
+ info(msg, fields) {
90
+ emit("info", msg, fields);
91
+ },
92
+ warn(msg, fields) {
93
+ emit("warn", msg, fields);
94
+ },
95
+ error(msg, fields) {
96
+ emit("error", msg, fields);
97
+ },
98
+ };
99
+ //# sourceMappingURL=logger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,53 @@
1
+ import { type MetricFamily } from "./types";
2
+ /** Thrown by `metrics.counter/histogram` when registration is rejected. */
3
+ export declare class MetricVocabularyError extends Error {
4
+ readonly metric: string;
5
+ readonly reason: string;
6
+ constructor(metric: string, reason: string);
7
+ }
8
+ export interface CounterHandle {
9
+ readonly name: string;
10
+ readonly family: MetricFamily;
11
+ readonly description: string;
12
+ inc(labels?: Record<string, string | number>): void;
13
+ inc(by: number, labels?: Record<string, string | number>): void;
14
+ }
15
+ export interface HistogramHandle {
16
+ readonly name: string;
17
+ readonly family: MetricFamily;
18
+ readonly description: string;
19
+ readonly maxBuckets: number;
20
+ record(value: number, labels?: Record<string, string | number>): void;
21
+ }
22
+ /**
23
+ * Backend that records the actual data points. The default backend
24
+ * stores points in-process for tests + the SDK counters; the real OTel
25
+ * meter wires in via TS-12 by replacing this through `_setBackend`.
26
+ */
27
+ export interface MetricsBackend {
28
+ recordCounter(name: string, by: number, labels: Record<string, string | number>): void;
29
+ recordHistogram(name: string, value: number, labels: Record<string, string | number>): void;
30
+ }
31
+ export declare function _setMetricsBackend(b: MetricsBackend): void;
32
+ export declare function _resetMetricsBackendForTests(): void;
33
+ export interface MetricRegistration {
34
+ family: MetricFamily;
35
+ description: string;
36
+ labelKeys?: readonly string[];
37
+ }
38
+ declare function counter(name: string, reg: MetricRegistration): CounterHandle;
39
+ declare function histogram(name: string, reg: MetricRegistration & {
40
+ maxBuckets?: number;
41
+ }): HistogramHandle;
42
+ /**
43
+ * The `metrics.*` namespace (D149 verbatim name). Use:
44
+ *
45
+ * const c = metrics.counter('billing_payments_total', { family: 'async_worker', description: '...' });
46
+ * c.inc({ tenant_id, pgw, status });
47
+ */
48
+ export declare const metrics: {
49
+ readonly counter: typeof counter;
50
+ readonly histogram: typeof histogram;
51
+ };
52
+ export {};
53
+ //# sourceMappingURL=metrics.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAsBA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,MAAM;gBADd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;CAKjC;AAsED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;IACpD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CACvE;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACtC,IAAI,CAAC;IACR,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACtC,IAAI,CAAC;CACT;AAaD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI,CAE1D;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,iBAAS,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,aAAa,CAwBrE;AAED,iBAAS,SAAS,CAChB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,kBAAkB,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,eAAe,CAoBjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;CAGV,CAAC"}