@xeonr/telemetry 0.0.0-stage → 0.2.0

package/dist/fetch.js

@@ -0,0 +1,41 @@
+/**
+ * Outbound HTTP, the Node counterpart of go-platform's
+ * telemetry.HTTPTransport: the undici and http instrumentations already make
+ * the client span and send `traceparent`; this adds `peer.service` (and the
+ * span name `HTTP GET <peer>`) and, toward an in-cluster host only, origin
+ * baggage. Any `baggage` header aimed elsewhere is removed.
+ */
+import { context } from "@opentelemetry/api";
+import { HEADER_BAGGAGE, inCluster, originBaggage } from "./baggage.js";
+import { withPeer } from "./processor.js";
+/** A `fetch` for one peer. */
+export function fetchWith(opts = {}) {
+    const base = opts.fetch ?? ((...args) => globalThis.fetch(...args));
+    return (input, init) => {
+        const url = input instanceof Request ? input.url : String(input);
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        const b = opts.baggage === false ? "" : baggageFor(url, opts.inCluster);
+        if (b)
+            headers.set(HEADER_BAGGAGE, b);
+        else
+            headers.delete(HEADER_BAGGAGE);
+        const call = () => base(input, { ...init, headers });
+        return opts.peer ? withPeer(opts.peer, call) : call();
+    };
+}
+/**
+ * The `baggage` header for a request to `url`: the origin members when the
+ * host is in-cluster, else "". For HTTP clients other than fetch (axios,
+ * got): set it when non-empty, and run the call inside `withPeer`.
+ */
+export function baggageFor(url, isInCluster = inCluster) {
+    let host = "";
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        return "";
+    }
+    return isInCluster(host) ? originBaggage(context.active()) : "";
+}
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAa1C,8BAA8B;AAC9B,MAAM,UAAU,SAAS,CAAC,OAAqB,EAAE;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAA8B,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC9F,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,MAAM,GAAG,GAAG,KAAK,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,KAAK,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACrG,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACxE,IAAI,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;;YACjC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,CAAC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,cAAyC,SAAS;IACzF,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,CAAC;QACJ,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;IACD,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACjE,CAAC"}

package/dist/identity.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The request's identity (observability plan §4.2), carried on the
+ * OpenTelemetry context as go-platform's telemetry package carries it on
+ * context.Context: one mutable record per request or job, so a handler's
+ * `setTeam` reaches every span and log line started after it.
+ */
+import { type Attributes, type Context, type Span } from "@opentelemetry/api";
+import { type AuthMethod, type SubjectKind } from "./keys.ts";
+/** What the telemetry layer knows about who a request or job acts for. Every value is a full URN or an opaque id, never a name or email. */
+export interface Identity {
+    subject?: string;
+    subjectKind?: SubjectKind;
+    orgId?: string;
+    clientId?: string;
+    applicationId?: string;
+    delegatorApp?: string;
+    apiKeyId?: string;
+    authMethod?: AuthMethod;
+    originSubject?: string;
+    originService?: string;
+    teamUrn?: string;
+    resourceType?: string;
+    resourceId?: string;
+    resourceUrn?: string;
+    /** On the RPC server span only; `attributes()` and `fields()` leave them out. */
+    scopes?: string[];
+    jobName?: string;
+    jobRunId?: string;
+    jobTrigger?: string;
+}
+/** The kind of a subject URN, as go-platform's telemetry.SubjectKind derives it. */
+export declare function subjectKind(subject: string | undefined): SubjectKind;
+/** The span attributes for an identity: the §4.2 table, minus scopes. */
+export declare function attributes(id: Identity): Attributes;
+/** The log fields for an identity: the same table, log spelling. */
+export declare function fields(id: Identity): Record<string, string>;
+/** @internal The per-request record. Exported for the package's own modules. */
+export declare class State {
+    id: Identity;
+    job: boolean;
+    originDecided: boolean;
+    entry: boolean;
+    baggageOrgId: string;
+    service: string;
+    procedure: string;
+    ip: string;
+    /** The request's or job's root span, so late team/resource reach it too. */
+    root: Span | undefined;
+    clone(): State;
+    /** The identity with its derived values filled in, as go-platform's state.identity. */
+    identity(): Identity;
+    merge(id: Identity): void;
+}
+/** @internal */
+export declare function stateFrom(ctx?: Context): State | undefined;
+/** @internal */
+export declare function withState(ctx: Context, s: State): Context;
+/** @internal The context's record, creating one when there is none. */
+export declare function ensureState(ctx?: Context): [Context, State];
+/** The identity of the request or job `ctx` belongs to, or undefined outside one. */
+export declare function identityFrom(ctx?: Context): Identity | undefined;
+/**
+ * Records who the caller is. Call it where the service verifies a Xeonr
+ * caller itself (its auth interceptor or middleware), the Node counterpart of
+ * go-platform's authn.WithPrincipal. It merges into the request's record when
+ * there is one (the server interceptor made it) and returns `ctx` unchanged;
+ * otherwise it returns a new context carrying a record, to run the rest of
+ * the work under with `context.with`.
+ */
+export declare function setIdentity(id: Identity, ctx?: Context): Context;
+/**
+ * Records the team the request acts on (resource ownership), never the
+ * caller's memberships. Spans started after the call carry it, and so do the
+ * current span and the request's root span.
+ */
+export declare function setTeam(urn: string, ctx?: Context): void;
+/** Records the request's target, as trail's SetTarget names it. */
+export declare function setResource(type: string, id: string, urn: string, ctx?: Context): void;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAoC,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAChH,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7E,4IAA4I;AAC5I,MAAM,WAAW,QAAQ;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AASD,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAQpE;AAID,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,UAAU,CAQnD;AAED,oEAAoE;AACpE,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ3D;AAED,gFAAgF;AAChF,qBAAa,KAAK;IACjB,EAAE,EAAE,QAAQ,CAAM;IAClB,GAAG,UAAS;IACZ,aAAa,UAAS;IACtB,KAAK,UAAS;IACd,YAAY,SAAM;IAClB,OAAO,SAAM;IACb,SAAS,SAAM;IACf,EAAE,SAAM;IACR,4EAA4E;IAC5E,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IAEvB,KAAK,IAAI,KAAK;IAcd,uFAAuF;IACvF,QAAQ,IAAI,QAAQ;IAapB,KAAK,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;CAMzB;AAID,gBAAgB;AAChB,wBAAgB,SAAS,CAAC,GAAG,GAAE,OAA0B,GAAG,KAAK,GAAG,SAAS,CAE5E;AAED,gBAAgB;AAChB,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAEzD;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,GAAG,GAAE,OAA0B,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAK7E;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,GAAG,GAAE,OAA0B,GAAG,QAAQ,GAAG,SAAS,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,GAAE,OAA0B,GAAG,OAAO,CAKlF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,OAA0B,GAAG,IAAI,CAK1E;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,OAA0B,GAAG,IAAI,CASxG"}

package/dist/identity.js

@@ -0,0 +1,173 @@
+/**
+ * The request's identity (observability plan §4.2), carried on the
+ * OpenTelemetry context as go-platform's telemetry package carries it on
+ * context.Context: one mutable record per request or job, so a handler's
+ * `setTeam` reaches every span and log line started after it.
+ */
+import { context, createContextKey, trace } from "@opentelemetry/api";
+import { IDENTITY_KEYS } from "./keys.js";
+const URN_USER = "urn:xeonr:auth:uid:user:";
+const URN_SERVICE_ACCOUNT = "urn:xeonr:auth:uid:service_account:";
+const URN_CLIENT = "urn:xeonr:auth:client:";
+const URN_TEAM = "urn:xeonr:auth:team:";
+const URN_API_KEY = "urn:xeonr:auth:api-key:";
+const URN_AUTOMATION_KEY = "urn:xeonr:auth:automation-key:";
+/** The kind of a subject URN, as go-platform's telemetry.SubjectKind derives it. */
+export function subjectKind(subject) {
+    if (!subject)
+        return "anonymous";
+    if (subject.startsWith(URN_USER))
+        return "user";
+    if (subject.startsWith(URN_SERVICE_ACCOUNT))
+        return "service_account";
+    if (subject.startsWith(URN_CLIENT))
+        return "client";
+    if (subject.startsWith(URN_TEAM))
+        return "team";
+    if (subject.startsWith(URN_API_KEY) || subject.startsWith(URN_AUTOMATION_KEY))
+        return "api_key";
+    return "unknown";
+}
+/** The span attributes for an identity: the §4.2 table, minus scopes. */
+export function attributes(id) {
+    const out = {};
+    for (const k of IDENTITY_KEYS) {
+        if (k.rpcServerSpanOnly)
+            continue;
+        const v = id[k.prop];
+        if (v)
+            out[k.span] = v;
+    }
+    return out;
+}
+/** The log fields for an identity: the same table, log spelling. */
+export function fields(id) {
+    const out = {};
+    for (const k of IDENTITY_KEYS) {
+        if (!k.log)
+            continue;
+        const v = id[k.prop];
+        if (v)
+            out[k.log] = v;
+    }
+    return out;
+}
+/** @internal The per-request record. Exported for the package's own modules. */
+export class State {
+    id = {};
+    job = false;
+    originDecided = false;
+    entry = false;
+    baggageOrgId = "";
+    service = "";
+    procedure = "";
+    ip = "";
+    /** The request's or job's root span, so late team/resource reach it too. */
+    root;
+    clone() {
+        const c = new State();
+        c.id = { ...this.id, ...(this.id.scopes ? { scopes: [...this.id.scopes] } : {}) };
+        c.job = this.job;
+        c.originDecided = this.originDecided;
+        c.entry = this.entry;
+        c.baggageOrgId = this.baggageOrgId;
+        c.service = this.service;
+        c.procedure = this.procedure;
+        c.ip = this.ip;
+        c.root = this.root;
+        return c;
+    }
+    /** The identity with its derived values filled in, as go-platform's state.identity. */
+    identity() {
+        const id = { ...this.id };
+        if (this.id.scopes)
+            id.scopes = [...this.id.scopes];
+        if (!id.subjectKind)
+            id.subjectKind = id.subject ? subjectKind(id.subject) : this.job ? "system" : "anonymous";
+        if (!id.authMethod && !id.subject && !this.job)
+            id.authMethod = "none";
+        if (!id.orgId && this.baggageOrgId)
+            id.orgId = this.baggageOrgId;
+        if (this.entry && !id.originSubject && !id.originService) {
+            if (id.subject)
+                id.originSubject = id.subject;
+            if (this.service)
+                id.originService = this.service;
+        }
+        return id;
+    }
+    merge(id) {
+        for (const [k, v] of Object.entries(id)) {
+            if (v === undefined || v === "")
+                continue;
+            this.id[k] = Array.isArray(v) ? [...v] : v;
+        }
+    }
+}
+const STATE = createContextKey("xeonr.telemetry.state");
+/** @internal */
+export function stateFrom(ctx = context.active()) {
+    return ctx.getValue(STATE);
+}
+/** @internal */
+export function withState(ctx, s) {
+    return ctx.setValue(STATE, s);
+}
+/** @internal The context's record, creating one when there is none. */
+export function ensureState(ctx = context.active()) {
+    const s = stateFrom(ctx);
+    if (s)
+        return [ctx, s];
+    const n = new State();
+    return [withState(ctx, n), n];
+}
+/** The identity of the request or job `ctx` belongs to, or undefined outside one. */
+export function identityFrom(ctx = context.active()) {
+    return stateFrom(ctx)?.identity();
+}
+/**
+ * Records who the caller is. Call it where the service verifies a Xeonr
+ * caller itself (its auth interceptor or middleware), the Node counterpart of
+ * go-platform's authn.WithPrincipal. It merges into the request's record when
+ * there is one (the server interceptor made it) and returns `ctx` unchanged;
+ * otherwise it returns a new context carrying a record, to run the rest of
+ * the work under with `context.with`.
+ */
+export function setIdentity(id, ctx = context.active()) {
+    const [next, s] = ensureState(ctx);
+    s.merge(id);
+    stamp(s, ctx, attributes(s.identity()));
+    return next;
+}
+/**
+ * Records the team the request acts on (resource ownership), never the
+ * caller's memberships. Spans started after the call carry it, and so do the
+ * current span and the request's root span.
+ */
+export function setTeam(urn, ctx = context.active()) {
+    const s = stateFrom(ctx);
+    if (!s || !urn)
+        return;
+    s.merge({ teamUrn: urn });
+    stamp(s, ctx, { "xeonr.team.urn": urn });
+}
+/** Records the request's target, as trail's SetTarget names it. */
+export function setResource(type, id, urn, ctx = context.active()) {
+    const s = stateFrom(ctx);
+    if (!s)
+        return;
+    const add = {};
+    if (type)
+        add.resourceType = type;
+    if (id)
+        add.resourceId = id;
+    if (urn)
+        add.resourceUrn = urn;
+    s.merge(add);
+    stamp(s, ctx, attributes(add));
+}
+function stamp(s, ctx, attrs) {
+    trace.getSpan(ctx)?.setAttributes(attrs);
+    s.root?.setAttributes(attrs);
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@xeonr/telemetry`: the Node mirror of go-platform's telemetry package.
+ *
+ * Start the process with `node --import @xeonr/telemetry/register app.js`
+ * (or `--require` for CommonJS). The app then uses:
+ * - `setIdentity` where it verifies a caller, `setTeam` / `setResource` in
+ *   handlers acting on owned resources;
+ * - `startJob` / `runJob` / `detach` for background work;
+ * - `fetchWith` / `withPeer` / `baggageFor` for outbound HTTP, and
+ *   `@xeonr/telemetry/connect` for Connect;
+ * - `@xeonr/telemetry/log` for logging;
+ * - `shutdown()` last, after its servers and workers have drained.
+ */
+export * from "./keys.ts";
+export { attributes, fields, identityFrom, setIdentity, setResource, setTeam, subjectKind, type Identity } from "./identity.ts";
+export { DEFAULT_TRUSTED_PROXY_CIDR, HEADER_BAGGAGE, inCluster, originBaggage, parseOriginBaggage, PeerTrust } from "./baggage.ts";
+export { detach, METRIC_JOB_DURATION, METRIC_JOB_RUNS, runJob, SCOPE, startJob, type Job, type JobOptions } from "./job.ts";
+export { baggageFor, fetchWith, type FetchOptions } from "./fetch.ts";
+export { DynamicSpanProcessor, IdentitySpanProcessor, KEY_LOCAL_EVENT, KEY_PEER_SERVICE, localEvent, METRIC_ROOTLESS_CLIENT_SPANS, ExportGuard, SanitizeSpanProcessor, withPeer, } from "./processor.ts";
+export { sanitize, stripUrl } from "./sanitize.ts";
+export { addSpanProcessor, environment, forceFlush, init, initialised, instrumentations, resolveEndpoint, shutdown, type Endpoint, type InitOptions } from "./sdk.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAChI,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACnI,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC5H,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACN,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,4BAA4B,EAC5B,WAAW,EACX,qBAAqB,EACrB,QAAQ,GACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * `@xeonr/telemetry`: the Node mirror of go-platform's telemetry package.
+ *
+ * Start the process with `node --import @xeonr/telemetry/register app.js`
+ * (or `--require` for CommonJS). The app then uses:
+ * - `setIdentity` where it verifies a caller, `setTeam` / `setResource` in
+ *   handlers acting on owned resources;
+ * - `startJob` / `runJob` / `detach` for background work;
+ * - `fetchWith` / `withPeer` / `baggageFor` for outbound HTTP, and
+ *   `@xeonr/telemetry/connect` for Connect;
+ * - `@xeonr/telemetry/log` for logging;
+ * - `shutdown()` last, after its servers and workers have drained.
+ */
+export * from "./keys.js";
+export { attributes, fields, identityFrom, setIdentity, setResource, setTeam, subjectKind } from "./identity.js";
+export { DEFAULT_TRUSTED_PROXY_CIDR, HEADER_BAGGAGE, inCluster, originBaggage, parseOriginBaggage, PeerTrust } from "./baggage.js";
+export { detach, METRIC_JOB_DURATION, METRIC_JOB_RUNS, runJob, SCOPE, startJob } from "./job.js";
+export { baggageFor, fetchWith } from "./fetch.js";
+export { DynamicSpanProcessor, IdentitySpanProcessor, KEY_LOCAL_EVENT, KEY_PEER_SERVICE, localEvent, METRIC_ROOTLESS_CLIENT_SPANS, ExportGuard, SanitizeSpanProcessor, withPeer, } from "./processor.js";
+export { sanitize, stripUrl } from "./sanitize.js";
+export { addSpanProcessor, environment, forceFlush, init, initialised, instrumentations, resolveEndpoint, shutdown } from "./sdk.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAChI,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACnI,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAA6B,MAAM,UAAU,CAAC;AAC5H,OAAO,EAAE,UAAU,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AACtE,OAAO,EACN,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,4BAA4B,EAC5B,WAAW,EACX,qBAAqB,EACrB,QAAQ,GACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAmC,MAAM,UAAU,CAAC"}

package/dist/job.d.ts

@@ -0,0 +1,38 @@
+import { type Context, type Link, type Span } from "@opentelemetry/api";
+/** The tracer and meter scope, the package as go-platform's is its module path. */
+export declare const SCOPE = "@xeonr/telemetry";
+export declare const METRIC_JOB_RUNS = "xeonr_job_runs_total";
+export declare const METRIC_JOB_DURATION = "xeonr_job_duration_seconds";
+export interface JobOptions {
+    /** What started the job: `cron`, `queue`, `request`, `boot`, … (`xeonr.job.trigger`). */
+    trigger?: string;
+    /** The context to start from. Default: the active one. Its span, if any, becomes a link, never the parent. */
+    ctx?: Context;
+    /** Extra links, e.g. a queue message's producer span. */
+    links?: Link[];
+    /** Attributes for the job's root span. Never ids of people or teams: those come from the identity. */
+    attributes?: Record<string, string | number | boolean>;
+}
+export interface Job {
+    /** The job's context: run the work under it (`context.with(job.ctx, …)`). */
+    ctx: Context;
+    span: Span;
+    /** Ends the job. An error marks it failed (status and a sanitised exception event). Safe to call twice. */
+    end(err?: unknown): void;
+}
+/**
+ * A context for work that outlives the request that spawned it: the request
+ * trace is not held open. It keeps the identity (minus the root span) and
+ * remembers the request's span, so the job started from it links to it.
+ */
+export declare function detach(ctx?: Context): Context;
+/** Starts a job: a new root span, linked to whatever span `opts.ctx` carried. End it with `job.end(err)`. */
+export declare function startJob(name: string, opts?: JobOptions): Job;
+/**
+ * Runs `fn` as a job and returns its result. A thrown error or rejection ends
+ * the job failed and is rethrown.
+ */
+export declare function runJob<T>(name: string, fn: (ctx: Context) => Promise<T> | T, opts?: JobOptions): Promise<T>;
+/** @internal Marks a span failed with a sanitised exception event, as go-platform does. */
+export declare function recordError(span: Span, err: unknown): void;
+//# sourceMappingURL=job.d.ts.map

package/dist/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../src/job.ts"],"names":[],"mappings":"AAQA,OAAO,EAON,KAAK,OAAO,EACZ,KAAK,IAAI,EACT,KAAK,IAAI,EAET,MAAM,oBAAoB,CAAC;AAI5B,mFAAmF;AACnF,eAAO,MAAM,KAAK,qBAAqB,CAAC;AAExC,eAAO,MAAM,eAAe,yBAAyB,CAAC;AACtD,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAIhE,MAAM,WAAW,UAAU;IAC1B,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8GAA8G;IAC9G,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,sGAAsG;IACtG,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,GAAG;IACnB,6EAA6E;IAC7E,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,2GAA2G;IAC3G,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,GAAE,OAA0B,GAAG,OAAO,CAW/D;AAED,6GAA6G;AAC7G,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,GAAG,CA+CjE;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAUrH;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAI1D"}

package/dist/job.js

@@ -0,0 +1,107 @@
+/**
+ * Background work (observability plan §5.9), as go-platform's telemetry
+ * StartJob, RunJob and Detach do it: every cron run, queue job, poller pass
+ * or handler-spawned task is a root span named after the job, with
+ * `xeonr.job.*` and system identity, so none of its database, cache or client
+ * spans is ever a trace root (obs.rooted-spans).
+ */
+import { randomBytes } from "node:crypto";
+import { context, createContextKey, metrics, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { attributes, State, stateFrom, withState } from "./identity.js";
+import { sanitizeError } from "./sanitize.js";
+/** The tracer and meter scope, the package as go-platform's is its module path. */
+export const SCOPE = "@xeonr/telemetry";
+export const METRIC_JOB_RUNS = "xeonr_job_runs_total";
+export const METRIC_JOB_DURATION = "xeonr_job_duration_seconds";
+const DETACHED = createContextKey("xeonr.telemetry.detached");
+/**
+ * A context for work that outlives the request that spawned it: the request
+ * trace is not held open. It keeps the identity (minus the root span) and
+ * remembers the request's span, so the job started from it links to it.
+ */
+export function detach(ctx = context.active()) {
+    const link = trace.getSpanContext(ctx);
+    let d = trace.deleteSpan(ctx);
+    if (link && trace.isSpanContextValid(link))
+        d = d.setValue(DETACHED, link);
+    const s = stateFrom(ctx);
+    if (s) {
+        const c = s.clone();
+        c.root = undefined;
+        d = withState(d, c);
+    }
+    return d;
+}
+/** Starts a job: a new root span, linked to whatever span `opts.ctx` carried. End it with `job.end(err)`. */
+export function startJob(name, opts = {}) {
+    const parent = opts.ctx ?? context.active();
+    const start = performance.now();
+    const links = [...(opts.links ?? [])];
+    const linked = parent.getValue(DETACHED) ?? trace.getSpanContext(parent);
+    if (linked && trace.isSpanContextValid(linked))
+        links.push({ context: linked });
+    const s = new State();
+    s.job = true;
+    const prev = stateFrom(parent);
+    if (prev) {
+        const p = prev.clone();
+        s.id = p.id;
+        s.service = p.service;
+        s.entry = p.entry;
+        s.originDecided = p.originDecided;
+        s.baggageOrgId = p.baggageOrgId;
+    }
+    s.id.jobName = name;
+    s.id.jobRunId = randomBytes(8).toString("hex");
+    if (opts.trigger)
+        s.id.jobTrigger = opts.trigger;
+    const base = withState(trace.deleteSpan(parent).deleteValue(DETACHED), s);
+    const span = trace.getTracer(SCOPE).startSpan(name, { root: true, kind: SpanKind.INTERNAL, links, attributes: { ...opts.attributes, ...attributes(s.identity()) } }, base);
+    s.root = span;
+    const ctx = trace.setSpan(base, span);
+    let ended = false;
+    return {
+        ctx,
+        span,
+        end(err) {
+            if (ended)
+                return;
+            ended = true;
+            let outcome = "ok";
+            if (err !== undefined && err !== null) {
+                outcome = "error";
+                recordError(span, err);
+            }
+            span.end();
+            recordJob(name, outcome, start);
+        },
+    };
+}
+/**
+ * Runs `fn` as a job and returns its result. A thrown error or rejection ends
+ * the job failed and is rethrown.
+ */
+export async function runJob(name, fn, opts = {}) {
+    const job = startJob(name, opts);
+    try {
+        const out = await context.with(job.ctx, () => fn(job.ctx));
+        job.end();
+        return out;
+    }
+    catch (err) {
+        job.end(err);
+        throw err;
+    }
+}
+/** @internal Marks a span failed with a sanitised exception event, as go-platform does. */
+export function recordError(span, err) {
+    const { type, message } = sanitizeError(err);
+    span.addEvent("exception", { "exception.type": type, "exception.message": message });
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+}
+function recordJob(name, outcome, start) {
+    const m = metrics.getMeter(SCOPE);
+    m.createCounter(METRIC_JOB_RUNS, { description: "Background job runs by outcome (ok, error)." }).add(1, { job: name, outcome });
+    m.createHistogram(METRIC_JOB_DURATION, { unit: "s", description: "Background job run duration." }).record((performance.now() - start) / 1000, { job: name });
+}
+//# sourceMappingURL=job.js.map

package/dist/job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.js","sourceRoot":"","sources":["../src/job.ts"],"names":[],"mappings":"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"}

package/dist/keys.d.ts

@@ -0,0 +1,80 @@
+/** One identity key: the span attribute, the log field and the Identity property. */
+export interface IdentityKey {
+    readonly field: string;
+    readonly prop: string;
+    readonly span: string;
+    readonly log?: string;
+    readonly baggage?: boolean;
+    readonly rpcServerSpanOnly?: boolean;
+}
+export declare const VOCABULARY_VERSION = 1;
+/** Subject is the verified principal's full URN (urn:xeonr:auth:uid:user:88, a service account, a client, an API key's owner or the key itself). Never a bare id. */
+export declare const KeySubject = "xeonr.subject";
+export declare const FieldSubject = "subject";
+/** SubjectKind is derived from Subject's URN prefix (SubjectKind func): user, service_account, client, api_key, team; anonymous for an unauthenticated request, system for a job with no caller, unknown for a URN with no recognised prefix. */
+export declare const KeySubjectKind = "xeonr.subject.kind";
+export declare const FieldSubjectKind = "subject_kind";
+/** OrgID is the auth organisation id (Principal.OrganisationID). Not Lantern's org.id resource attribute. */
+export declare const KeyOrgID = "xeonr.org.id";
+export declare const FieldOrgID = "org_id";
+/** ClientID is the OAuth client the token was issued to. */
+export declare const KeyClientID = "xeonr.client.id";
+export declare const FieldClientID = "client_id";
+/** ApplicationID is the auth application the token was minted for. */
+export declare const KeyApplicationID = "xeonr.application.id";
+export declare const FieldApplicationID = "application_id";
+/** DelegatorApp is the product acting for the user on an RFC 8693 exchanged token; empty unless delegated. */
+export declare const KeyDelegatorApp = "xeonr.delegator.app";
+export declare const FieldDelegatorApp = "delegator_app";
+/** APIKeyID is the API key's URN when a key authenticated the request. */
+export declare const KeyAPIKeyID = "xeonr.api_key.id";
+export declare const FieldAPIKeyID = "api_key_id";
+/** AuthMethod is how the caller authenticated: bearer, cookie, api_key, or none. */
+export declare const KeyAuthMethod = "xeonr.auth.method";
+export declare const FieldAuthMethod = "auth_method";
+/** OriginSubject is the subject at the entry of the trace. It survives a service-account hop through baggage from trusted in-cluster peers. */
+export declare const KeyOriginSubject = "xeonr.origin.subject";
+export declare const FieldOriginSubject = "origin_subject";
+/** OriginService is the service.name of the trace's entry service. */
+export declare const KeyOriginService = "xeonr.origin.service";
+export declare const FieldOriginService = "origin_service";
+/** TeamURN is the team the request acts on (resource ownership), set by the handler with SetTeam. Never the caller's membership list. */
+export declare const KeyTeamURN = "xeonr.team.urn";
+export declare const FieldTeamURN = "team_urn";
+/** ResourceType is the kind of the request's target, set with SetResource. */
+export declare const KeyResourceType = "xeonr.resource.type";
+export declare const FieldResourceType = "resource_type";
+/** ResourceID is the target's id, set with SetResource. */
+export declare const KeyResourceID = "xeonr.resource.id";
+export declare const FieldResourceID = "resource_id";
+/** ResourceURN is the target's URN, set with SetResource. */
+export declare const KeyResourceURN = "xeonr.resource.urn";
+export declare const FieldResourceURN = "resource_urn";
+/** Scopes are the token's scopes. They go on the RPC server span only: Attributes and Fields leave them out. */
+export declare const KeyScopes = "xeonr.scopes";
+/** JobName is the background job's name (trail.outbox.flush), set by StartJob. */
+export declare const KeyJobName = "xeonr.job.name";
+export declare const FieldJobName = "job";
+/** JobRunID identifies one run of the job, set by StartJob. */
+export declare const KeyJobRunID = "xeonr.job.run_id";
+export declare const FieldJobRunID = "job_run_id";
+/** JobTrigger is what started the job (cron, queue, request), set by StartJob's Trigger option. */
+export declare const KeyJobTrigger = "xeonr.job.trigger";
+export declare const FieldJobTrigger = "job_trigger";
+/** the Connect procedure of the request a log line belongs to */
+export declare const FieldProcedure = "procedure";
+/** the Connect code of a finished RPC */
+export declare const FieldStatus = "status";
+/** how long the RPC or job took, in milliseconds */
+export declare const FieldDurationMS = "duration_ms";
+/** the resolved client address (connectmw.ClientIPResolver) */
+export declare const FieldIP = "ip";
+/** true on a span whose request or job panicked */
+export declare const KeyPanic = "xeonr.panic";
+/** The §4.2 table in order. */
+export declare const IDENTITY_KEYS: readonly IdentityKey[];
+/** The baggage members, in table order: nothing else ever travels as baggage. */
+export declare const BAGGAGE_KEYS: readonly string[];
+export type SubjectKind = "user" | "service_account" | "client" | "api_key" | "team" | "anonymous" | "system" | "unknown";
+export type AuthMethod = "bearer" | "cookie" | "api_key" | "none";
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}