@3ngram/config 0.2.0
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.
- package/LICENSE +202 -0
- package/dist/context.d.ts +29 -0
- package/dist/context.js +23 -0
- package/dist/context.js.map +1 -0
- package/dist/env.d.ts +165 -0
- package/dist/env.js +544 -0
- package/dist/env.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +9 -0
- package/dist/index.js.map +1 -0
- package/dist/logger.d.ts +24 -0
- package/dist/logger.js +68 -0
- package/dist/logger.js.map +1 -0
- package/dist/metrics.d.ts +51 -0
- package/dist/metrics.js +118 -0
- package/dist/metrics.js.map +1 -0
- package/dist/otel.d.ts +58 -0
- package/dist/otel.js +169 -0
- package/dist/otel.js.map +1 -0
- package/dist/redaction.d.ts +27 -0
- package/dist/redaction.js +88 -0
- package/dist/redaction.js.map +1 -0
- package/package.json +66 -0
- package/tsconfig.package.json +10 -0
package/dist/logger.js
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { pino } from 'pino';
|
|
3
|
+
import { getContext } from './context.js';
|
|
4
|
+
import { loadEnv } from './env.js';
|
|
5
|
+
import { redactDeep } from './redaction.js';
|
|
6
|
+
const CONTEXT_LOG_KEYS = {
|
|
7
|
+
requestId: 'request_id',
|
|
8
|
+
surface: 'surface',
|
|
9
|
+
userIdHash: 'user_id',
|
|
10
|
+
operation: 'operation',
|
|
11
|
+
toolName: 'tool_name',
|
|
12
|
+
sessionId: 'session_id',
|
|
13
|
+
jobId: 'job_id',
|
|
14
|
+
queue: 'queue',
|
|
15
|
+
attempt: 'attempt',
|
|
16
|
+
};
|
|
17
|
+
/** camelCase context → snake_case log keys, mapped once here (observability.md §1). */
|
|
18
|
+
export function contextBindings(ctx) {
|
|
19
|
+
const bindings = {};
|
|
20
|
+
for (const [key, logKey] of Object.entries(CONTEXT_LOG_KEYS)) {
|
|
21
|
+
const value = ctx[key];
|
|
22
|
+
if (value !== undefined)
|
|
23
|
+
bindings[logKey] = value;
|
|
24
|
+
}
|
|
25
|
+
return bindings;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Production logger config in one place; tests inject a sink to assert on the
|
|
29
|
+
* exact JSON the real config emits.
|
|
30
|
+
*/
|
|
31
|
+
export function createLogger(destination) {
|
|
32
|
+
return pino({
|
|
33
|
+
level: loadEnv().LOG_LEVEL,
|
|
34
|
+
// Recursive redaction of the entire log object — any key, any depth,
|
|
35
|
+
// arrays included. Serializers/redact-path allowlists were rejected:
|
|
36
|
+
// they miss memory rows under unanticipated keys ({ results: rows }).
|
|
37
|
+
formatters: {
|
|
38
|
+
log: (object) => redactDeep(object),
|
|
39
|
+
},
|
|
40
|
+
}, destination);
|
|
41
|
+
}
|
|
42
|
+
/** Root logger. Prefer log() at call sites so request context rides along. */
|
|
43
|
+
export const logger = createLogger();
|
|
44
|
+
// The destination log() resolves against. Defaults to the root logger; a test
|
|
45
|
+
// may rebind it to a capturable sink so a line emitted by code reaching the
|
|
46
|
+
// module-global log() (e.g. a route handler over real HTTP) is observable —
|
|
47
|
+
// the same createLogger(stream) precedent redaction.test.ts uses, lifted to the
|
|
48
|
+
// process-global call site that production transports actually use.
|
|
49
|
+
let rootLogger = logger;
|
|
50
|
+
/**
|
|
51
|
+
* Test-only seam: route every subsequent log() through `destination`. Pass
|
|
52
|
+
* undefined to restore the production root logger. Never call this in
|
|
53
|
+
* production code — it exists so a transport test can assert the structured
|
|
54
|
+
* line a handler emits via log() without a DB-backed integration harness.
|
|
55
|
+
*/
|
|
56
|
+
export function setLogDestination(destination) {
|
|
57
|
+
rootLogger = destination === undefined ? logger : createLogger(destination);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The call-site API: a child logger carrying the current AsyncLocalStorage
|
|
61
|
+
* request context (request_id, surface, user_id hash, tool_name, ...).
|
|
62
|
+
* Outside a request scope it falls back to the bare root logger.
|
|
63
|
+
*/
|
|
64
|
+
export function log() {
|
|
65
|
+
const ctx = getContext();
|
|
66
|
+
return ctx === undefined ? rootLogger : rootLogger.child(contextBindings(ctx));
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=logger.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,EAAuC,IAAI,EAAE,MAAM,MAAM,CAAA;AAChE,OAAO,EAAE,UAAU,EAAuB,MAAM,cAAc,CAAA;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C,MAAM,gBAAgB,GAAG;IACvB,SAAS,EAAE,YAAY;IACvB,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,SAAS;IACrB,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,WAAW;IACrB,SAAS,EAAE,YAAY;IACvB,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;CACqC,CAAA;AAEzD,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,GAAmB;IACjD,MAAM,QAAQ,GAA4B,EAAE,CAAA;IAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,GAA2B,CAAC,CAAA;QAC9C,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAAA;IACnD,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,WAA+B;IAC1D,OAAO,IAAI,CACT;QACE,KAAK,EAAE,OAAO,EAAE,CAAC,SAAS;QAC1B,qEAAqE;QACrE,qEAAqE;QACrE,sEAAsE;QACtE,UAAU,EAAE;YACV,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAA4B;SAC/D;KACF,EACD,WAAW,CACZ,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;AAEpC,8EAA8E;AAC9E,4EAA4E;AAC5E,4EAA4E;AAC5E,gFAAgF;AAChF,oEAAoE;AACpE,IAAI,UAAU,GAAW,MAAM,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAA+B;IAC/D,UAAU,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG;IACjB,MAAM,GAAG,GAAG,UAAU,EAAE,CAAA;IACxB,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAA;AAChF,CAAC"}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { type Attributes, type Counter, type Histogram } from '@opentelemetry/api';
|
|
2
|
+
/**
|
|
3
|
+
* Single namespace root for every domain metric name. All metric names derive
|
|
4
|
+
* from this prefix via metricName() so the namespace can never drift one metric
|
|
5
|
+
* at a time. Renaming the
|
|
6
|
+
* namespace is dashboard-breaking — any external dashboard/alert must move in
|
|
7
|
+
* lockstep.
|
|
8
|
+
*
|
|
9
|
+
* MUST start with an alphabetic character: the OpenTelemetry instrument-naming
|
|
10
|
+
* spec requires names to begin with a letter, so a digit-leading prefix (e.g.
|
|
11
|
+
* "3ngram") would make every instrument invalid/no-op once a real meter
|
|
12
|
+
* provider is registered. Hence the spelled-out "threengram", not "3ngram".
|
|
13
|
+
*/
|
|
14
|
+
export declare const METRIC_PREFIX = "threengram";
|
|
15
|
+
export declare const metricName: (suffix: string) => string;
|
|
16
|
+
export declare const memoryWritten: Counter<Attributes>;
|
|
17
|
+
export declare const memorySuperseded: Counter<Attributes>;
|
|
18
|
+
export declare const searchLatencyMs: Histogram<Attributes>;
|
|
19
|
+
/** Consolidation accept-rate is the ADR-0005 advisory-model early-warning signal. */
|
|
20
|
+
export declare const consolidationProposed: Counter<Attributes>;
|
|
21
|
+
export declare const consolidationAccepted: Counter<Attributes>;
|
|
22
|
+
export declare const consolidationRejected: Counter<Attributes>;
|
|
23
|
+
/** Per-tool labels (tool_name × client_ua) catch client version skew (§6). */
|
|
24
|
+
export declare const mcpToolCalls: Counter<Attributes>;
|
|
25
|
+
export declare const mcpToolErrors: Counter<Attributes>;
|
|
26
|
+
/**
|
|
27
|
+
* Rate-limit STORE failures (Redis unreachable), labelled by key_prefix (the
|
|
28
|
+
* limiter/route class — no secrets, no principal ids). This is the alert signal
|
|
29
|
+
* for a fail-open outage: when the store is down a fail-open limiter passes every
|
|
30
|
+
* request, so brute-force protection (ADR-0009 §6) silently vanishes with no
|
|
31
|
+
* over-limit 429s to alert on — this counter is the ONLY metric that fires.
|
|
32
|
+
*/
|
|
33
|
+
export declare const rateLimitStoreFailure: Counter<Attributes>;
|
|
34
|
+
/**
|
|
35
|
+
* Budget-gate consumption-lookup failures. When the
|
|
36
|
+
* usage-store lookup errors, the budget gate FAILS OPEN — it allows the metered
|
|
37
|
+
* op rather than block all writes on a transient error — so there is no over-cap
|
|
38
|
+
* rejection to alert on. This counter is the ONLY signal that cost protection
|
|
39
|
+
* silently degraded; alert on it. Labelled by operation (no user id, no content).
|
|
40
|
+
*/
|
|
41
|
+
export declare const budgetGateLookupFailure: Counter<Attributes>;
|
|
42
|
+
/**
|
|
43
|
+
* Watch signal for the free→paid line.
|
|
44
|
+
* Increments when a GENERATION-class LLM operation (the gateway.complete() surface
|
|
45
|
+
* — entity extraction, digests, agents) is recorded — the moment real paid cost
|
|
46
|
+
* begins. Today it never fires: no generation operation is registered and the
|
|
47
|
+
* completion-accounting path is deferred, so all live traffic is embed-class.
|
|
48
|
+
* When it first fires, the paid surface has become real and caps/enforcement must
|
|
49
|
+
* be revisited. Content-free — labelled by operation only.
|
|
50
|
+
*/
|
|
51
|
+
export declare const generationCostObserved: Counter<Attributes>;
|
package/dist/metrics.js
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { metrics, } from '@opentelemetry/api';
|
|
3
|
+
/**
|
|
4
|
+
* Domain metrics counters (observability.md §4). Vendor-neutral by
|
|
5
|
+
* construction: call sites talk to @opentelemetry/api only. With no
|
|
6
|
+
* MeterProvider registered (SENTRY_DSN unset — the self-host default) these
|
|
7
|
+
* resolve to the API's built-in no-op meter, so every .add()/.record() is a
|
|
8
|
+
* free no-op with zero call-site branching.
|
|
9
|
+
*
|
|
10
|
+
* Instruments are resolved lazily per global-provider identity, NOT at module
|
|
11
|
+
* evaluation: @opentelemetry/api has no ProxyMeterProvider, so an instrument
|
|
12
|
+
* created at import time would stay bound to the no-op meter even after
|
|
13
|
+
* initObservability() installs a real provider (ESM evaluates all imports
|
|
14
|
+
* before the entrypoint's first statement runs).
|
|
15
|
+
*/
|
|
16
|
+
const METER_NAME = '@3ngram/observability';
|
|
17
|
+
/**
|
|
18
|
+
* Single namespace root for every domain metric name. All metric names derive
|
|
19
|
+
* from this prefix via metricName() so the namespace can never drift one metric
|
|
20
|
+
* at a time. Renaming the
|
|
21
|
+
* namespace is dashboard-breaking — any external dashboard/alert must move in
|
|
22
|
+
* lockstep.
|
|
23
|
+
*
|
|
24
|
+
* MUST start with an alphabetic character: the OpenTelemetry instrument-naming
|
|
25
|
+
* spec requires names to begin with a letter, so a digit-leading prefix (e.g.
|
|
26
|
+
* "3ngram") would make every instrument invalid/no-op once a real meter
|
|
27
|
+
* provider is registered. Hence the spelled-out "threengram", not "3ngram".
|
|
28
|
+
*/
|
|
29
|
+
export const METRIC_PREFIX = 'threengram';
|
|
30
|
+
export const metricName = (suffix) => `${METRIC_PREFIX}.${suffix}`;
|
|
31
|
+
function perProvider(create) {
|
|
32
|
+
let boundTo;
|
|
33
|
+
let instrument;
|
|
34
|
+
return () => {
|
|
35
|
+
const provider = metrics.getMeterProvider();
|
|
36
|
+
if (instrument === undefined || provider !== boundTo) {
|
|
37
|
+
boundTo = provider;
|
|
38
|
+
instrument = create();
|
|
39
|
+
}
|
|
40
|
+
return instrument;
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
function lazyCounter(name, options) {
|
|
44
|
+
const resolve = perProvider(() => metrics.getMeter(METER_NAME).createCounter(name, options));
|
|
45
|
+
return {
|
|
46
|
+
add(value, attributes, context) {
|
|
47
|
+
resolve().add(value, attributes, context);
|
|
48
|
+
},
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
function lazyHistogram(name, options) {
|
|
52
|
+
const resolve = perProvider(() => metrics.getMeter(METER_NAME).createHistogram(name, options));
|
|
53
|
+
return {
|
|
54
|
+
record(value, attributes, context) {
|
|
55
|
+
resolve().record(value, attributes, context);
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
export const memoryWritten = lazyCounter(metricName('memory.written'), {
|
|
60
|
+
description: 'Memories written, by memory type',
|
|
61
|
+
});
|
|
62
|
+
export const memorySuperseded = lazyCounter(metricName('memory.superseded'), {
|
|
63
|
+
description: 'Memories superseded (ADR-0005 append-and-supersede)',
|
|
64
|
+
});
|
|
65
|
+
export const searchLatencyMs = lazyHistogram(metricName('search.latency_ms'), {
|
|
66
|
+
description: 'Unified search latency; p50/p95 derived from the distribution',
|
|
67
|
+
unit: 'ms',
|
|
68
|
+
});
|
|
69
|
+
/** Consolidation accept-rate is the ADR-0005 advisory-model early-warning signal. */
|
|
70
|
+
export const consolidationProposed = lazyCounter(metricName('consolidation.proposed'), {
|
|
71
|
+
description: 'Consolidation proposals created',
|
|
72
|
+
});
|
|
73
|
+
export const consolidationAccepted = lazyCounter(metricName('consolidation.accepted'), {
|
|
74
|
+
description: 'Consolidation proposals accepted',
|
|
75
|
+
});
|
|
76
|
+
export const consolidationRejected = lazyCounter(metricName('consolidation.rejected'), {
|
|
77
|
+
description: 'Consolidation proposals rejected',
|
|
78
|
+
});
|
|
79
|
+
/** Per-tool labels (tool_name × client_ua) catch client version skew (§6). */
|
|
80
|
+
export const mcpToolCalls = lazyCounter(metricName('mcp.tool_calls'), {
|
|
81
|
+
description: 'MCP tool invocations, by tool_name and client_ua',
|
|
82
|
+
});
|
|
83
|
+
export const mcpToolErrors = lazyCounter(metricName('mcp.tool_errors'), {
|
|
84
|
+
description: 'MCP tool failures, by tool_name and reason_code',
|
|
85
|
+
});
|
|
86
|
+
/**
|
|
87
|
+
* Rate-limit STORE failures (Redis unreachable), labelled by key_prefix (the
|
|
88
|
+
* limiter/route class — no secrets, no principal ids). This is the alert signal
|
|
89
|
+
* for a fail-open outage: when the store is down a fail-open limiter passes every
|
|
90
|
+
* request, so brute-force protection (ADR-0009 §6) silently vanishes with no
|
|
91
|
+
* over-limit 429s to alert on — this counter is the ONLY metric that fires.
|
|
92
|
+
*/
|
|
93
|
+
export const rateLimitStoreFailure = lazyCounter(metricName('rate_limit.store_failure'), {
|
|
94
|
+
description: 'Rate-limit store (Redis) failures, by key_prefix and fail_open posture',
|
|
95
|
+
});
|
|
96
|
+
/**
|
|
97
|
+
* Budget-gate consumption-lookup failures. When the
|
|
98
|
+
* usage-store lookup errors, the budget gate FAILS OPEN — it allows the metered
|
|
99
|
+
* op rather than block all writes on a transient error — so there is no over-cap
|
|
100
|
+
* rejection to alert on. This counter is the ONLY signal that cost protection
|
|
101
|
+
* silently degraded; alert on it. Labelled by operation (no user id, no content).
|
|
102
|
+
*/
|
|
103
|
+
export const budgetGateLookupFailure = lazyCounter(metricName('budget.gate_lookup_failure'), {
|
|
104
|
+
description: 'Budget-gate consumption-lookup failures (fail-open), by operation',
|
|
105
|
+
});
|
|
106
|
+
/**
|
|
107
|
+
* Watch signal for the free→paid line.
|
|
108
|
+
* Increments when a GENERATION-class LLM operation (the gateway.complete() surface
|
|
109
|
+
* — entity extraction, digests, agents) is recorded — the moment real paid cost
|
|
110
|
+
* begins. Today it never fires: no generation operation is registered and the
|
|
111
|
+
* completion-accounting path is deferred, so all live traffic is embed-class.
|
|
112
|
+
* When it first fires, the paid surface has become real and caps/enforcement must
|
|
113
|
+
* be revisited. Content-free — labelled by operation only.
|
|
114
|
+
*/
|
|
115
|
+
export const generationCostObserved = lazyCounter(metricName('budget.generation_cost_observed'), {
|
|
116
|
+
description: 'Generation-class (paid) LLM usage recorded, by operation — the free→paid watch signal',
|
|
117
|
+
});
|
|
118
|
+
//# sourceMappingURL=metrics.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}
|
package/dist/otel.d.ts
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type Env } from './env.js';
|
|
2
|
+
/**
|
|
3
|
+
* Deep-scrub for Sentry payloads: same field list as the log redaction, so
|
|
4
|
+
* the §1 red line (no memory content in error events or traces) holds in one
|
|
5
|
+
* place. Returns plain data — Sentry events are JSON-shaped.
|
|
6
|
+
*/
|
|
7
|
+
export declare function scrubEvent<T>(event: T): T;
|
|
8
|
+
/**
|
|
9
|
+
* Error-event scrub for the beforeSend gate. Field-name scrubbing alone is
|
|
10
|
+
* not enough for error events: `exception.values[].value` carries the raw
|
|
11
|
+
* Error message (and `message`/breadcrumb messages are free text), so memory
|
|
12
|
+
* content embedded in an exception would reach Sentry past the field scrub.
|
|
13
|
+
* Free text becomes a len+digest token; structured stacktrace frames survive,
|
|
14
|
+
* so grouping (stack-based) and correlation both keep working. Raw text only
|
|
15
|
+
* in local dev.
|
|
16
|
+
*/
|
|
17
|
+
export declare function scrubSentryEvent<T>(event: T): T;
|
|
18
|
+
/**
|
|
19
|
+
* The Sentry `environment` tag. Hosted staging and production both run with
|
|
20
|
+
* NODE_ENV=production, so deriving the tag from NODE_ENV alone makes the two
|
|
21
|
+
* indistinguishable. Precedence: an explicit SENTRY_ENVIRONMENT, then
|
|
22
|
+
* the Railway-injected environment name, then NODE_ENV. Each candidate is
|
|
23
|
+
* trimmed and a blank/whitespace-only value is treated as unset — a plain `??`
|
|
24
|
+
* is insufficient because '' is not null/undefined and would otherwise be taken
|
|
25
|
+
* as an authoritative empty environment.
|
|
26
|
+
*/
|
|
27
|
+
export declare function resolveSentryEnvironment(env: Pick<Env, 'SENTRY_ENVIRONMENT' | 'RAILWAY_ENVIRONMENT_NAME' | 'NODE_ENV'>): string;
|
|
28
|
+
/**
|
|
29
|
+
* Error tracking + tracing, DSN-gated: an empty SENTRY_DSN means fully
|
|
30
|
+
* disabled — no phone-home, the self-host default (§2). With a DSN, Sentry's
|
|
31
|
+
* Node SDK boots its bundled OpenTelemetry SDK (auto-instrumentation for
|
|
32
|
+
* http/pg/fetch) and exports spans to Sentry; release is tagged with the git
|
|
33
|
+
* SHA. Explicit crash handlers either way: a worker crash is an event, not a
|
|
34
|
+
* silent restart.
|
|
35
|
+
*
|
|
36
|
+
* METRIC EXPORT IS DELIBERATELY NOT WIRED YET (§3: instrumentation now, the
|
|
37
|
+
* backend can wait — Sentry's metrics product was sunset, so counters need an
|
|
38
|
+
* OTLP target chosen with the first deployable). metrics.ts instruments are
|
|
39
|
+
* recorded against whatever global MeterProvider exists; until one is
|
|
40
|
+
* registered they are API no-ops. Wiring it later is contained here: register
|
|
41
|
+
* an @opentelemetry/sdk-metrics MeterProvider (PeriodicExportingMetricReader
|
|
42
|
+
* + OTLP exporter) behind this same DSN/env gate — call sites never change,
|
|
43
|
+
* and the provider-rebind test in metrics.test.ts proves instruments pick up
|
|
44
|
+
* a provider installed after first use.
|
|
45
|
+
*/
|
|
46
|
+
export declare function initObservability(options?: {
|
|
47
|
+
release?: string;
|
|
48
|
+
}): void;
|
|
49
|
+
/**
|
|
50
|
+
* Crash reasons are logged in a safe projection: an Error message built from
|
|
51
|
+
* memory content (and the stack's first line, which repeats it verbatim)
|
|
52
|
+
* would otherwise hit stdout on exactly the path where invariants break.
|
|
53
|
+
* Frames locate the crash; message length+digest correlate it. The raw
|
|
54
|
+
* exception still goes to captureException, but the beforeSend gate
|
|
55
|
+
* (scrubSentryEvent) sanitizes its message before anything leaves the
|
|
56
|
+
* process. Raw passthrough only in local dev.
|
|
57
|
+
*/
|
|
58
|
+
export declare function crashSafeError(cause: unknown): Record<string, unknown>;
|
package/dist/otel.js
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
// Observability bootstrap (observability.md §2–§3). Import this module FIRST
|
|
3
|
+
// in every app entrypoint — Sentry's OTel auto-instrumentation must load
|
|
4
|
+
// before http/pg/etc. Never import it from library code; apps only.
|
|
5
|
+
import * as Sentry from '@sentry/node';
|
|
6
|
+
import { loadEnv } from './env.js';
|
|
7
|
+
import { logger } from './logger.js';
|
|
8
|
+
import { contentDigest, REDACTED, REDACTED_FIELDS } from './redaction.js';
|
|
9
|
+
const REDACTED_FIELD_SET = new Set(REDACTED_FIELDS);
|
|
10
|
+
/**
|
|
11
|
+
* Deep-scrub for Sentry payloads: same field list as the log redaction, so
|
|
12
|
+
* the §1 red line (no memory content in error events or traces) holds in one
|
|
13
|
+
* place. Returns plain data — Sentry events are JSON-shaped.
|
|
14
|
+
*/
|
|
15
|
+
export function scrubEvent(event) {
|
|
16
|
+
return scrubValue(event);
|
|
17
|
+
}
|
|
18
|
+
function scrubValue(value) {
|
|
19
|
+
if (Array.isArray(value))
|
|
20
|
+
return value.map(scrubValue);
|
|
21
|
+
if (value !== null && typeof value === 'object') {
|
|
22
|
+
const out = {};
|
|
23
|
+
for (const [key, entry] of Object.entries(value)) {
|
|
24
|
+
out[key] = REDACTED_FIELD_SET.has(key) ? REDACTED : scrubValue(entry);
|
|
25
|
+
}
|
|
26
|
+
return out;
|
|
27
|
+
}
|
|
28
|
+
return value;
|
|
29
|
+
}
|
|
30
|
+
function redactFreeText(text) {
|
|
31
|
+
return `[redacted len=${text.length} sha256_8=${contentDigest(text)}]`;
|
|
32
|
+
}
|
|
33
|
+
function safeStackFrames(stack) {
|
|
34
|
+
const frames = stack
|
|
35
|
+
?.split('\n')
|
|
36
|
+
.slice(1)
|
|
37
|
+
.map((line) => line.trim())
|
|
38
|
+
.filter((line) => line.startsWith('at '))
|
|
39
|
+
.slice(0, 20);
|
|
40
|
+
return frames && frames.length > 0 ? frames : undefined;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Error-event scrub for the beforeSend gate. Field-name scrubbing alone is
|
|
44
|
+
* not enough for error events: `exception.values[].value` carries the raw
|
|
45
|
+
* Error message (and `message`/breadcrumb messages are free text), so memory
|
|
46
|
+
* content embedded in an exception would reach Sentry past the field scrub.
|
|
47
|
+
* Free text becomes a len+digest token; structured stacktrace frames survive,
|
|
48
|
+
* so grouping (stack-based) and correlation both keep working. Raw text only
|
|
49
|
+
* in local dev.
|
|
50
|
+
*/
|
|
51
|
+
export function scrubSentryEvent(event) {
|
|
52
|
+
const scrubbed = scrubValue(event);
|
|
53
|
+
if (loadEnv().NODE_ENV === 'development')
|
|
54
|
+
return scrubbed;
|
|
55
|
+
if (typeof scrubbed.message === 'string') {
|
|
56
|
+
scrubbed.message = redactFreeText(scrubbed.message);
|
|
57
|
+
}
|
|
58
|
+
const exception = scrubbed.exception;
|
|
59
|
+
for (const entry of exception?.values ?? []) {
|
|
60
|
+
if (typeof entry.value === 'string')
|
|
61
|
+
entry.value = redactFreeText(entry.value);
|
|
62
|
+
}
|
|
63
|
+
const breadcrumbs = scrubbed.breadcrumbs;
|
|
64
|
+
const crumbs = Array.isArray(breadcrumbs) ? breadcrumbs : (breadcrumbs?.values ?? []);
|
|
65
|
+
for (const crumb of crumbs) {
|
|
66
|
+
if (typeof crumb.message === 'string')
|
|
67
|
+
crumb.message = redactFreeText(crumb.message);
|
|
68
|
+
}
|
|
69
|
+
return scrubbed;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* The Sentry `environment` tag. Hosted staging and production both run with
|
|
73
|
+
* NODE_ENV=production, so deriving the tag from NODE_ENV alone makes the two
|
|
74
|
+
* indistinguishable. Precedence: an explicit SENTRY_ENVIRONMENT, then
|
|
75
|
+
* the Railway-injected environment name, then NODE_ENV. Each candidate is
|
|
76
|
+
* trimmed and a blank/whitespace-only value is treated as unset — a plain `??`
|
|
77
|
+
* is insufficient because '' is not null/undefined and would otherwise be taken
|
|
78
|
+
* as an authoritative empty environment.
|
|
79
|
+
*/
|
|
80
|
+
export function resolveSentryEnvironment(env) {
|
|
81
|
+
const norm = (value) => {
|
|
82
|
+
const trimmed = value.trim();
|
|
83
|
+
return trimmed === '' ? undefined : trimmed;
|
|
84
|
+
};
|
|
85
|
+
return norm(env.SENTRY_ENVIRONMENT) ?? norm(env.RAILWAY_ENVIRONMENT_NAME) ?? env.NODE_ENV;
|
|
86
|
+
}
|
|
87
|
+
let initialized = false;
|
|
88
|
+
/**
|
|
89
|
+
* Error tracking + tracing, DSN-gated: an empty SENTRY_DSN means fully
|
|
90
|
+
* disabled — no phone-home, the self-host default (§2). With a DSN, Sentry's
|
|
91
|
+
* Node SDK boots its bundled OpenTelemetry SDK (auto-instrumentation for
|
|
92
|
+
* http/pg/fetch) and exports spans to Sentry; release is tagged with the git
|
|
93
|
+
* SHA. Explicit crash handlers either way: a worker crash is an event, not a
|
|
94
|
+
* silent restart.
|
|
95
|
+
*
|
|
96
|
+
* METRIC EXPORT IS DELIBERATELY NOT WIRED YET (§3: instrumentation now, the
|
|
97
|
+
* backend can wait — Sentry's metrics product was sunset, so counters need an
|
|
98
|
+
* OTLP target chosen with the first deployable). metrics.ts instruments are
|
|
99
|
+
* recorded against whatever global MeterProvider exists; until one is
|
|
100
|
+
* registered they are API no-ops. Wiring it later is contained here: register
|
|
101
|
+
* an @opentelemetry/sdk-metrics MeterProvider (PeriodicExportingMetricReader
|
|
102
|
+
* + OTLP exporter) behind this same DSN/env gate — call sites never change,
|
|
103
|
+
* and the provider-rebind test in metrics.test.ts proves instruments pick up
|
|
104
|
+
* a provider installed after first use.
|
|
105
|
+
*/
|
|
106
|
+
export function initObservability(options = {}) {
|
|
107
|
+
if (initialized)
|
|
108
|
+
return;
|
|
109
|
+
initialized = true;
|
|
110
|
+
const env = loadEnv();
|
|
111
|
+
if (env.SENTRY_DSN === '') {
|
|
112
|
+
logger.info('observability: telemetry disabled (no SENTRY_DSN)');
|
|
113
|
+
registerCrashHandlers(false);
|
|
114
|
+
return;
|
|
115
|
+
}
|
|
116
|
+
const release = options.release ?? (env.GIT_SHA || env.RAILWAY_GIT_COMMIT_SHA);
|
|
117
|
+
const environment = resolveSentryEnvironment(env);
|
|
118
|
+
Sentry.init({
|
|
119
|
+
dsn: env.SENTRY_DSN,
|
|
120
|
+
environment,
|
|
121
|
+
...(release === '' ? {} : { release }),
|
|
122
|
+
// Solo-scale: sample everything; revisit before real traffic.
|
|
123
|
+
tracesSampleRate: 1.0,
|
|
124
|
+
beforeSend: (event) => scrubSentryEvent(event),
|
|
125
|
+
beforeSendTransaction: (event) => scrubEvent(event),
|
|
126
|
+
});
|
|
127
|
+
registerCrashHandlers(true);
|
|
128
|
+
logger.info({ release, environment }, 'observability: Sentry + OTel enabled');
|
|
129
|
+
}
|
|
130
|
+
function registerCrashHandlers(sentryEnabled) {
|
|
131
|
+
process.on('unhandledRejection', (reason) => die('unhandledRejection', reason, sentryEnabled));
|
|
132
|
+
process.on('uncaughtException', (error) => die('uncaughtException', error, sentryEnabled));
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Crash reasons are logged in a safe projection: an Error message built from
|
|
136
|
+
* memory content (and the stack's first line, which repeats it verbatim)
|
|
137
|
+
* would otherwise hit stdout on exactly the path where invariants break.
|
|
138
|
+
* Frames locate the crash; message length+digest correlate it. The raw
|
|
139
|
+
* exception still goes to captureException, but the beforeSend gate
|
|
140
|
+
* (scrubSentryEvent) sanitizes its message before anything leaves the
|
|
141
|
+
* process. Raw passthrough only in local dev.
|
|
142
|
+
*/
|
|
143
|
+
export function crashSafeError(cause) {
|
|
144
|
+
if (loadEnv().NODE_ENV === 'development')
|
|
145
|
+
return { err: cause };
|
|
146
|
+
if (cause instanceof Error) {
|
|
147
|
+
return {
|
|
148
|
+
err_type: cause.name,
|
|
149
|
+
message_len: cause.message.length,
|
|
150
|
+
message_sha256_8: contentDigest(cause.message),
|
|
151
|
+
// V8 callsites only. Some drivers append SQL/params as non-frame stack
|
|
152
|
+
// lines; those are free text and must not reach logs.
|
|
153
|
+
stack_frames: safeStackFrames(cause.stack),
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
if (typeof cause === 'string') {
|
|
157
|
+
return { err_type: 'string', message_len: cause.length, message_sha256_8: contentDigest(cause) };
|
|
158
|
+
}
|
|
159
|
+
return { err_type: typeof cause };
|
|
160
|
+
}
|
|
161
|
+
function die(kind, cause, sentryEnabled) {
|
|
162
|
+
logger.fatal({ ...crashSafeError(cause), kind }, `fatal: ${kind}`);
|
|
163
|
+
if (!sentryEnabled) {
|
|
164
|
+
process.exit(1);
|
|
165
|
+
}
|
|
166
|
+
Sentry.captureException(cause);
|
|
167
|
+
void Sentry.flush(2000).finally(() => process.exit(1));
|
|
168
|
+
}
|
|
169
|
+
//# sourceMappingURL=otel.js.map
|
package/dist/otel.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Memory-content field names that must never reach logs, traces, or metrics
|
|
3
|
+
* (observability.md §1 red line; AGENTS.md hard rule 6). Both snake_case
|
|
4
|
+
* (Drizzle rows) and camelCase (DTOs) spellings.
|
|
5
|
+
*/
|
|
6
|
+
export declare const REDACTED_FIELDS: readonly ["answer", "body", "chunkContent", "chunk_content", "content", "embedding", "query", "queryText", "query_text", "summary", "text", "topic"];
|
|
7
|
+
export declare const REDACTED = "[redacted]";
|
|
8
|
+
/**
|
|
9
|
+
* Raw memory content in logs is allowed only in local dev with the explicit
|
|
10
|
+
* opt-in flag. The env schema already refuses the flag outside development at
|
|
11
|
+
* boot; this re-check makes the redaction layer safe even if env parsing is
|
|
12
|
+
* bypassed.
|
|
13
|
+
*/
|
|
14
|
+
export declare function debugContentEnabled(): boolean;
|
|
15
|
+
/** sha256(salt + id) → `u_` + 16 hex chars: correlation without identification (§1). */
|
|
16
|
+
export declare function hashUserId(userId: string): string;
|
|
17
|
+
/** 8-hex content fingerprint: correlation/dedup without disclosure. */
|
|
18
|
+
export declare function contentDigest(value: string): string;
|
|
19
|
+
/**
|
|
20
|
+
* Redaction-by-construction for the whole log object: recursively strip every
|
|
21
|
+
* known content field at any depth — including inside arrays under arbitrary
|
|
22
|
+
* keys (`{ results: rows }`) — synthesizing `<key>_len` (and `<key>_sha256_8`
|
|
23
|
+
* for strings) so dedup debugging stays possible without disclosure.
|
|
24
|
+
* Non-plain objects (Error, Date, Buffer) pass through untouched; pino's own
|
|
25
|
+
* serializers have already flattened errors by the time this runs.
|
|
26
|
+
*/
|
|
27
|
+
export declare function redactDeep(input: unknown): unknown;
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import { loadEnv } from './env.js';
|
|
4
|
+
/**
|
|
5
|
+
* Memory-content field names that must never reach logs, traces, or metrics
|
|
6
|
+
* (observability.md §1 red line; AGENTS.md hard rule 6). Both snake_case
|
|
7
|
+
* (Drizzle rows) and camelCase (DTOs) spellings.
|
|
8
|
+
*/
|
|
9
|
+
export const REDACTED_FIELDS = [
|
|
10
|
+
'answer',
|
|
11
|
+
'body',
|
|
12
|
+
'chunkContent',
|
|
13
|
+
'chunk_content',
|
|
14
|
+
'content',
|
|
15
|
+
'embedding',
|
|
16
|
+
'query',
|
|
17
|
+
'queryText',
|
|
18
|
+
'query_text',
|
|
19
|
+
'summary',
|
|
20
|
+
'text',
|
|
21
|
+
'topic',
|
|
22
|
+
];
|
|
23
|
+
const REDACTED_FIELD_SET = new Set(REDACTED_FIELDS);
|
|
24
|
+
export const REDACTED = '[redacted]';
|
|
25
|
+
/**
|
|
26
|
+
* Raw memory content in logs is allowed only in local dev with the explicit
|
|
27
|
+
* opt-in flag. The env schema already refuses the flag outside development at
|
|
28
|
+
* boot; this re-check makes the redaction layer safe even if env parsing is
|
|
29
|
+
* bypassed.
|
|
30
|
+
*/
|
|
31
|
+
export function debugContentEnabled() {
|
|
32
|
+
const env = loadEnv();
|
|
33
|
+
return env.LOG_DEBUG_CONTENT && env.NODE_ENV === 'development';
|
|
34
|
+
}
|
|
35
|
+
/** sha256(salt + id) → `u_` + 16 hex chars: correlation without identification (§1). */
|
|
36
|
+
export function hashUserId(userId) {
|
|
37
|
+
const env = loadEnv();
|
|
38
|
+
const digest = createHash('sha256')
|
|
39
|
+
.update(env.LOG_HASH_SALT + userId)
|
|
40
|
+
.digest('hex');
|
|
41
|
+
return `u_${digest.slice(0, 16)}`;
|
|
42
|
+
}
|
|
43
|
+
/** 8-hex content fingerprint: correlation/dedup without disclosure. */
|
|
44
|
+
export function contentDigest(value) {
|
|
45
|
+
return createHash('sha256').update(value).digest('hex').slice(0, 8);
|
|
46
|
+
}
|
|
47
|
+
function isPlainObject(value) {
|
|
48
|
+
if (value === null || typeof value !== 'object')
|
|
49
|
+
return false;
|
|
50
|
+
const proto = Object.getPrototypeOf(value);
|
|
51
|
+
return proto === Object.prototype || proto === null;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Redaction-by-construction for the whole log object: recursively strip every
|
|
55
|
+
* known content field at any depth — including inside arrays under arbitrary
|
|
56
|
+
* keys (`{ results: rows }`) — synthesizing `<key>_len` (and `<key>_sha256_8`
|
|
57
|
+
* for strings) so dedup debugging stays possible without disclosure.
|
|
58
|
+
* Non-plain objects (Error, Date, Buffer) pass through untouched; pino's own
|
|
59
|
+
* serializers have already flattened errors by the time this runs.
|
|
60
|
+
*/
|
|
61
|
+
export function redactDeep(input) {
|
|
62
|
+
if (debugContentEnabled())
|
|
63
|
+
return input;
|
|
64
|
+
return walk(input);
|
|
65
|
+
}
|
|
66
|
+
function walk(value) {
|
|
67
|
+
if (Array.isArray(value))
|
|
68
|
+
return value.map(walk);
|
|
69
|
+
if (!isPlainObject(value))
|
|
70
|
+
return value;
|
|
71
|
+
const out = {};
|
|
72
|
+
for (const [key, entry] of Object.entries(value)) {
|
|
73
|
+
if (!REDACTED_FIELD_SET.has(key)) {
|
|
74
|
+
out[key] = walk(entry);
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
if (typeof entry === 'string') {
|
|
78
|
+
out[`${key}_len`] = entry.length;
|
|
79
|
+
out[`${key}_sha256_8`] = contentDigest(entry);
|
|
80
|
+
}
|
|
81
|
+
else if (Array.isArray(entry)) {
|
|
82
|
+
out[`${key}_len`] = entry.length;
|
|
83
|
+
}
|
|
84
|
+
// other shapes: dropped entirely
|
|
85
|
+
}
|
|
86
|
+
return out;
|
|
87
|
+
}
|
|
88
|
+
//# sourceMappingURL=redaction.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}
|