@equipe-tech/observability 0.2.1 → 0.3.5

package/dist/contract/EventProducer.js

@@ -0,0 +1,209 @@
+import { Clock, Context, DateTime, Effect, Predicate, Random, Schema } from "effect";
+import { AuditContext, AuditOutcome } from "../audit/AuditRecord.js";
+import { CorrelationContext, CurrentCorrelation } from "../Correlation.js";
+import { telemetryContractProvenance, validateContractEvent, } from "./TelemetryContract.js";
+import { ErrorContext, EventDuration, EventOutcome, EventSeverity, EventTimestamp, HttpContext, } from "./TelemetryEvent.js";
+import { CurrentDataPolicy } from "../policy/DataPolicy.js";
+import { transformSignalFields } from "../policy/PolicyTransform.js";
+import { sensitiveFieldReplacement } from "../policy/PolicyVocabulary.js";
+import { InvalidTelemetryEvent } from "./TelemetryContractError.js";
+export class TelemetryEventSink extends Context.Service()("@equipe-tech/observability/TelemetryEventSink") {
+}
+const eventError = (code, message, context) => new InvalidTelemetryEvent({ code, message, ...context });
+const parseEventPayload = (definition, payload) => {
+    if (!Predicate.isObject(payload)) {
+        return eventError("OBS_EVENT_INVALID_FIELD", `Event "${definition.name}" has an invalid payload. Use an event payload object with declared fields.`, { eventName: definition.name, attributeName: "payload" });
+    }
+    return payload;
+};
+const parseAttributes = (policy, contract, definition, attributes) => {
+    if (!Predicate.isObject(attributes)) {
+        return eventError("OBS_EVENT_INVALID_FIELD", `Event "${definition.name}" has invalid attributes. Use a declared scalar attribute object.`, { eventName: definition.name, attributeName: "attributes" });
+    }
+    const parsed = {};
+    const contractRedactions = [];
+    for (const [attributeName, value] of Object.entries(attributes)) {
+        const attribute = definition.attributes.get(attributeName);
+        if (value === undefined ||
+            (!Predicate.isString(value) &&
+                !Predicate.isBoolean(value) &&
+                (!Predicate.isNumber(value) || !Number.isFinite(value)))) {
+            return eventError("OBS_EVENT_INVALID_FIELD", `Event "${definition.name}" has a non-scalar or non-finite value for "${attributeName}". Use a string, finite number, or boolean.`, { eventName: definition.name, attributeName });
+        }
+        if (attribute === undefined) {
+            parsed[attributeName] = value;
+            continue;
+        }
+        if (attribute.classification === "forbidden") {
+            return eventError("OBS_EVENT_RESTRICTED_ATTRIBUTE", `Event "${definition.name}" cannot emit forbidden attribute "${attributeName}". Remove the attribute before emitting.`, { eventName: definition.name, attributeName });
+        }
+        if (attribute.classification === "sensitive" && attribute.metricLabel) {
+            return eventError("OBS_EVENT_SENSITIVE_METRIC_LABEL", `Event "${definition.name}" cannot use sensitive attribute "${attributeName}" as a metric label. Remove the metric label declaration.`, { eventName: definition.name, attributeName });
+        }
+        parsed[attributeName] =
+            attribute.classification === "sensitive" ? sensitiveFieldReplacement : value;
+        if (attribute.classification === "sensitive" &&
+            policy.classify(attributeName) !== "sensitive") {
+            contractRedactions.push({ rule: "classification", action: "masked", surface: "event" });
+        }
+    }
+    const validation = validateContractEvent(contract, definition.name, parsed);
+    if (validation instanceof InvalidTelemetryEvent) {
+        return validation;
+    }
+    const decision = transformSignalFields(policy, "event", parsed);
+    return {
+        attributes: decision.value,
+        redactions: [...contractRedactions, ...decision.redactions],
+        admission: { policyDroppedAttributes: decision.dropped },
+    };
+};
+const decodeSeverity = Schema.decodeUnknownEffect(EventSeverity);
+const decodeOutcome = Schema.decodeUnknownEffect(EventOutcome);
+const decodeAuditOutcome = Schema.decodeUnknownEffect(AuditOutcome);
+const decodeTimestamp = Schema.decodeUnknownEffect(EventTimestamp);
+const decodeDuration = Schema.decodeUnknownEffect(EventDuration);
+const decodeHttp = Schema.decodeUnknownEffect(HttpContext);
+const decodeError = Schema.decodeUnknownEffect(ErrorContext);
+const decodeAudit = Schema.decodeUnknownEffect(AuditContext);
+const decodeCorrelation = Schema.decodeUnknownEffect(CorrelationContext);
+const parseTimestamp = (eventName, timestamp) => decodeTimestamp(timestamp).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has an invalid timestamp. Use a real RFC 3339 UTC timestamp ending in Z.`, { eventName, attributeName: "event.timestamp" })));
+const parseDuration = (eventName, durationMs) => decodeDuration(durationMs).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has an invalid durationMs. Use a finite non-negative number.`, { eventName, attributeName: "event.duration_ms" })));
+const parseHttp = (eventName, http) => decodeHttp(http).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has invalid HTTP context. Use a non-empty method and route with an integer status code from 100 to 599.`, { eventName, attributeName: "http" })));
+const parseError = (eventName, error) => decodeError(error).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has invalid error context. Use a non-empty type, a message, and a boolean retryable value.`, { eventName, attributeName: "error" })));
+const parseAudit = (eventName, audit) => decodeAudit(audit).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has invalid audit context. Use a declared action, actor, resource type, and resource id.`, { eventName, attributeName: "audit" })));
+const parseCorrelation = (eventName, correlation) => {
+    if (correlation === undefined) {
+        return CurrentCorrelation;
+    }
+    return decodeCorrelation(correlation).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has invalid correlation context. Use traced or untraced linkage with bounded request and run identifiers.`, { eventName, attributeName: "correlation" })));
+};
+const parseOutcome = (definition, outcome) => decodeOutcome(outcome).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_OUTCOME", `Event "${definition.name}" has an invalid outcome. Use success, failure, or cancelled.`, { eventName: definition.name, attributeName: "event.outcome" })));
+const parseSeverity = (eventName, severity) => decodeSeverity(severity).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_FIELD", `Event "${eventName}" has an invalid severity. Use debug, info, warn, error, or fatal.`, { eventName, attributeName: "event.severity" })));
+const shouldRecord = Effect.fn("shouldRecord")(function* (definition, outcome) {
+    if (definition.mandatory ||
+        definition.kind === "audit" ||
+        definition.kind === "defect" ||
+        outcome === "failure" ||
+        definition.sampling.kind === "always") {
+        return true;
+    }
+    const draw = yield* Random.next;
+    return draw < definition.sampling.rate;
+});
+const buildEvent = Effect.fn("buildEvent")(function* (definition, contract, attributes, payload) {
+    const rawTimestamp = payload.timestamp ?? DateTime.formatIso(DateTime.makeUnsafe(yield* Clock.currentTimeMillis));
+    const timestamp = yield* parseTimestamp(definition.name, rawTimestamp);
+    const severity = yield* parseSeverity(definition.name, payload.severity ?? definition.defaultSeverity);
+    const correlation = yield* parseCorrelation(definition.name, payload.correlation);
+    const base = {
+        timestamp,
+        name: definition.name,
+        severity,
+        correlation,
+        attributes,
+    };
+    switch (definition.kind) {
+        case "request": {
+            if (payload.durationMs === undefined ||
+                payload.http === undefined ||
+                payload.outcome === undefined) {
+                return yield* eventError("OBS_EVENT_INVALID_FIELD", `Request event "${definition.name}" requires outcome, durationMs, and http fields. Add every required field.`, { eventName: definition.name });
+            }
+            const outcome = yield* parseOutcome(definition, payload.outcome);
+            const durationMs = yield* parseDuration(definition.name, payload.durationMs);
+            const http = yield* parseHttp(definition.name, payload.http);
+            return { ...base, kind: "request", outcome, durationMs, http };
+        }
+        case "operation": {
+            if (payload.durationMs === undefined || payload.outcome === undefined) {
+                return yield* eventError("OBS_EVENT_INVALID_FIELD", `Operation event "${definition.name}" requires outcome and durationMs. Add both fields.`, { eventName: definition.name });
+            }
+            const outcome = yield* parseOutcome(definition, payload.outcome);
+            const durationMs = yield* parseDuration(definition.name, payload.durationMs);
+            return { ...base, kind: "operation", outcome, durationMs };
+        }
+        case "domain": {
+            if (payload.outcome === undefined) {
+                return yield* eventError("OBS_EVENT_INVALID_FIELD", `Domain event "${definition.name}" requires an outcome. Add the required field.`, { eventName: definition.name });
+            }
+            const outcome = yield* parseOutcome(definition, payload.outcome);
+            return { ...base, kind: "domain", outcome };
+        }
+        case "defect": {
+            if (payload.error === undefined) {
+                return yield* eventError("OBS_EVENT_INVALID_FIELD", `Defect event "${definition.name}" requires error context. Add error type, message, and retryable fields.`, { eventName: definition.name });
+            }
+            if (payload.outcome !== undefined) {
+                return yield* eventError("OBS_EVENT_INVALID_OUTCOME", `Defect event "${definition.name}" has an invalid outcome. Defect outcomes are always failure.`, { eventName: definition.name, attributeName: "event.outcome" });
+            }
+            const error = yield* parseError(definition.name, payload.error);
+            return { ...base, kind: "defect", outcome: "failure", error };
+        }
+        case "audit": {
+            if (payload.audit === undefined || payload.outcome === undefined) {
+                return yield* eventError("OBS_EVENT_INVALID_FIELD", `Audit event "${definition.name}" requires outcome and audit context. Add both fields.`, { eventName: definition.name });
+            }
+            const outcome = yield* decodeAuditOutcome(payload.outcome).pipe(Effect.mapError(() => eventError("OBS_EVENT_INVALID_AUDIT_OUTCOME", `Audit event "${definition.name}" has an invalid outcome. Use success, failure, cancelled, or denied.`, { eventName: definition.name, attributeName: "event.outcome" })));
+            const audit = yield* parseAudit(definition.name, payload.audit);
+            const action = contract.auditActionByName.get(audit.action);
+            if (action === undefined) {
+                return yield* eventError("OBS_EVENT_UNKNOWN_AUDIT_ACTION", `Audit event "${definition.name}" uses undeclared action "${audit.action}". Use a contract audit action.`, { eventName: definition.name, attributeName: "audit.action" });
+            }
+            if (action.resourceType !== audit.resourceType) {
+                return yield* eventError("OBS_EVENT_INVALID_AUDIT_RESOURCE", `Audit action "${audit.action}" requires resource type "${action.resourceType}". Use the declared resource type.`, { eventName: definition.name, attributeName: "audit.resource.type" });
+            }
+            if (!action.allowedOutcomes.includes(outcome)) {
+                return yield* eventError("OBS_EVENT_INVALID_AUDIT_OUTCOME", `Audit action "${audit.action}" does not allow outcome "${outcome}". Use one of its declared outcomes.`, { eventName: definition.name, attributeName: "event.outcome" });
+            }
+            if (audit.reasonCode !== undefined && !action.reasonCodes.includes(audit.reasonCode)) {
+                return yield* eventError("OBS_EVENT_INVALID_AUDIT_REASON", `Audit action "${audit.action}" does not declare reason code "${audit.reasonCode}". Use a declared reason code or omit it.`, { eventName: definition.name, attributeName: "audit.reason_code" });
+            }
+            return { ...base, kind: "audit", outcome, audit };
+        }
+    }
+});
+export const admitEvent = Effect.fn("admitEvent")(function* (contract, definition, payload) {
+    const policy = yield* CurrentDataPolicy;
+    const parsedAttributes = parseAttributes(policy, contract, definition, payload.attributes);
+    if (parsedAttributes instanceof InvalidTelemetryEvent)
+        return yield* parsedAttributes;
+    const event = yield* buildEvent(definition, contract, parsedAttributes.attributes, payload);
+    if (!(yield* shouldRecord(definition, event.outcome))) {
+        return { decision: "sampled_out", name: definition.name };
+    }
+    return {
+        decision: "recorded",
+        event,
+        redactions: parsedAttributes.redactions,
+        admission: parsedAttributes.admission,
+    };
+});
+export const makeEventProducer = (contract) => {
+    const contractProvenance = telemetryContractProvenance(contract);
+    return {
+        emit: Effect.fn("EventProducer.emit")(function* (alias, payload) {
+            const definition = contract.eventByAlias.get(alias);
+            if (definition === undefined) {
+                return yield* eventError("OBS_EVENT_UNKNOWN_NAME", `Event alias "${alias}" is not declared by this telemetry contract. Use one of the contract aliases.`, { eventAlias: alias });
+            }
+            const parsedPayload = parseEventPayload(definition, payload);
+            if (parsedPayload instanceof InvalidTelemetryEvent) {
+                return yield* parsedPayload;
+            }
+            const admitted = yield* admitEvent(contract, definition, parsedPayload);
+            if (admitted.decision === "sampled_out") {
+                return { ...admitted, contractProvenance };
+            }
+            const sink = yield* TelemetryEventSink;
+            yield* sink.record(admitted.event, admitted.admission);
+            return {
+                decision: "recorded",
+                event: admitted.event,
+                redactions: admitted.redactions,
+                admission: admitted.admission,
+                contractProvenance,
+            };
+        }),
+    };
+};

package/dist/contract/MetricContractError.d.ts

@@ -0,0 +1,19 @@
+export type MetricMeasurementErrorCode = "OBS_METRIC_UNKNOWN_ALIAS" | "OBS_METRIC_KIND_MISMATCH" | "OBS_METRIC_UNDECLARED_ATTRIBUTE" | "OBS_METRIC_MISSING_ATTRIBUTE" | "OBS_METRIC_VALUE_NOT_ALLOWED" | "OBS_METRIC_CARDINALITY_EXCEEDED" | "OBS_METRIC_INVALID_VALUE";
+type InvalidMetricMeasurementOptions = {
+    readonly code: MetricMeasurementErrorCode;
+    readonly operation: string;
+    readonly message: string;
+    readonly metricAlias: string;
+    readonly metricName?: string;
+    readonly attributeName?: string;
+};
+export declare class InvalidMetricMeasurement extends Error {
+    readonly code: MetricMeasurementErrorCode;
+    readonly operation: string;
+    readonly metricAlias: string;
+    readonly metricName?: string;
+    readonly attributeName?: string;
+    readonly retryable = false;
+    constructor(options: InvalidMetricMeasurementOptions);
+}
+export {};

package/dist/contract/MetricContractError.js

@@ -0,0 +1,19 @@
+export class InvalidMetricMeasurement extends Error {
+    code;
+    operation;
+    metricAlias;
+    metricName;
+    attributeName;
+    retryable = false;
+    constructor(options) {
+        super(options.message);
+        this.name = "InvalidMetricMeasurement";
+        this.code = options.code;
+        this.operation = options.operation;
+        this.metricAlias = options.metricAlias;
+        if (options.metricName !== undefined)
+            this.metricName = options.metricName;
+        if (options.attributeName !== undefined)
+            this.attributeName = options.attributeName;
+    }
+}

package/dist/contract/MetricDefinition.d.ts

@@ -0,0 +1,61 @@
+export type MetricKind = "counter" | "histogram" | "observable_gauge";
+export type MetricAttributeScalar = string | number | boolean;
+export type MetricAttributeDefinitionInput = {
+    readonly classification: "public" | "internal";
+    readonly maximumCardinality: number;
+    readonly allowedValues?: readonly [
+        MetricAttributeScalar,
+        ...ReadonlyArray<MetricAttributeScalar>
+    ];
+};
+export type MetricAttributeDefinitionsInput = {
+    readonly [attributeName: string]: MetricAttributeDefinitionInput;
+};
+type MetricDefinitionBase = {
+    readonly name: string;
+    readonly description: string;
+    readonly unit: string;
+    readonly attributes: MetricAttributeDefinitionsInput;
+};
+export type CounterMetricDefinitionInput = MetricDefinitionBase & {
+    readonly kind: "counter";
+    readonly boundaries?: never;
+};
+export type HistogramMetricDefinitionInput = MetricDefinitionBase & {
+    readonly kind: "histogram";
+    readonly boundaries: ReadonlyArray<number>;
+};
+export type ObservableGaugeMetricDefinitionInput = MetricDefinitionBase & {
+    readonly kind: "observable_gauge";
+    readonly boundaries?: never;
+};
+export type MetricDefinitionInput = CounterMetricDefinitionInput | HistogramMetricDefinitionInput | ObservableGaugeMetricDefinitionInput;
+export type MetricDefinitionsInput = {
+    readonly [alias: string]: MetricDefinitionInput;
+};
+type CompiledMetricDefinitionBase = {
+    readonly alias: string;
+    readonly name: string;
+    readonly description: string;
+    readonly unit: string;
+    readonly attributes: ReadonlyMap<string, MetricAttributeDefinitionInput>;
+};
+export type CompiledMetricDefinition = (CompiledMetricDefinitionBase & {
+    readonly kind: "counter";
+    readonly boundaries?: never;
+}) | (CompiledMetricDefinitionBase & {
+    readonly kind: "histogram";
+    readonly boundaries: ReadonlyArray<number>;
+}) | (CompiledMetricDefinitionBase & {
+    readonly kind: "observable_gauge";
+    readonly boundaries?: never;
+});
+export declare const isValidMetricName: (name: string) => boolean;
+export declare const isValidMetricDescription: (description: string) => boolean;
+export declare const isValidMetricUnit: (unit: string) => boolean;
+export declare const isValidHistogramBoundaries: (boundaries: ReadonlyArray<number>) => boolean;
+export declare const isValidMetricAttributeName: (name: string) => boolean;
+export declare const isValidMetricAttributeCount: (count: number) => boolean;
+export declare const isValidMetricCardinality: (value: number) => boolean;
+export declare const validAllowedValues: (values: ReadonlyArray<MetricAttributeScalar> | undefined, maximumCardinality: number) => boolean;
+export {};

package/dist/contract/MetricDefinition.js

@@ -0,0 +1,91 @@
+import { isReservedEventNamePart, isValidAttributeName } from "./EventName.js";
+import { isForbiddenMetricAttributeName } from "../policy/MetricLabelPolicy.js";
+import { isFiniteMetricScalar, metricScalarIdentity } from "../metrics/MetricScalar.js";
+import { containsControlCharacter, instrumentNamePattern, maximumMetricAttributeCardinality, maximumMetricAttributes, unitPattern, } from "../metrics/InstrumentGrammar.js";
+const metricNamePattern = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+const reservedMetricParts = new Set([
+    "production",
+    "prod",
+    "staging",
+    "stage",
+    "development",
+    "dev",
+    "test",
+    "local",
+    "sandbox",
+    "qa",
+    "preview",
+    "debug",
+    "info",
+    "warn",
+    "warning",
+    "fatal",
+    "critical",
+    "trace",
+    "verbose",
+    "severity",
+    "success",
+    "succeeded",
+    "failure",
+    "failed",
+    "cancelled",
+    "canceled",
+    "ok",
+    "outcome",
+    "errored",
+    "error",
+    "service",
+    "environment",
+    "instance",
+    "host",
+    "pod",
+    "node",
+    "region",
+    "zone",
+    "cluster",
+    "namespace",
+    "ms",
+    "seconds",
+    "bytes",
+    "count",
+    "percent",
+    "ratio",
+    "unit",
+]);
+export const isValidMetricName = (name) => name.length <= 128 &&
+    metricNamePattern.test(name) &&
+    instrumentNamePattern.test(name) &&
+    name.split(".").every((part) => !isReservedEventNamePart(part) && !reservedMetricParts.has(part));
+export const isValidMetricDescription = (description) => description.length > 0 && description.length <= 1_024 && !containsControlCharacter(description);
+export const isValidMetricUnit = (unit) => unit.length <= 63 && unitPattern.test(unit);
+export const isValidHistogramBoundaries = (boundaries) => {
+    if (boundaries.length === 0 || boundaries.length > 50)
+        return false;
+    let previous = Number.NEGATIVE_INFINITY;
+    for (const boundary of boundaries) {
+        if (!Number.isFinite(boundary) || boundary <= previous)
+            return false;
+        previous = boundary;
+    }
+    return true;
+};
+export const isValidMetricAttributeName = (name) => isValidAttributeName(name) && !isForbiddenMetricAttributeName(name);
+export const isValidMetricAttributeCount = (count) => count <= maximumMetricAttributes;
+export const isValidMetricCardinality = (value) => Number.isInteger(value) && value >= 1 && value <= maximumMetricAttributeCardinality;
+export const validAllowedValues = (values, maximumCardinality) => {
+    if (values === undefined)
+        return true;
+    if (values.length === 0 || values.length > maximumCardinality)
+        return false;
+    const identities = new Set();
+    for (const value of values) {
+        if (!isFiniteMetricScalar(value)) {
+            return false;
+        }
+        const identity = metricScalarIdentity(value);
+        if (identities.has(identity))
+            return false;
+        identities.add(identity);
+    }
+    return true;
+};

package/dist/contract/MetricProducer.d.ts

@@ -0,0 +1,42 @@
+import type { MetricAttributeValue, Metrics, ObservableGaugeRegistration } from "../Metrics.js";
+import type { TelemetryContract, TelemetryContractInput } from "./TelemetryContract.js";
+import type { CompiledMetricDefinition, MetricAttributeDefinitionInput, MetricDefinitionInput } from "./MetricDefinition.js";
+export type MetricAttributeValueOf<Definition extends MetricAttributeDefinitionInput> = Definition["allowedValues"] extends ReadonlyArray<infer Value extends MetricAttributeValue> ? Value : MetricAttributeValue;
+export type MetricAttributesOf<Definition extends MetricDefinitionInput> = {
+    readonly [Name in keyof Definition["attributes"]]: MetricAttributeValueOf<Definition["attributes"][Name]>;
+};
+type AliasesOfKind<Definition extends TelemetryContractInput, Kind extends string> = {
+    readonly [Alias in keyof Definition["metrics"]]: Definition["metrics"][Alias]["kind"] extends Kind ? Alias : never;
+}[keyof Definition["metrics"]] & string;
+export type ContractCounter<Definition extends TelemetryContractInput, Alias extends AliasesOfKind<Definition, "counter">> = {
+    readonly add: (value: number, attributes: MetricAttributesOf<Definition["metrics"][Alias]>) => void;
+};
+export type ContractHistogram<Definition extends TelemetryContractInput, Alias extends AliasesOfKind<Definition, "histogram">> = {
+    readonly record: (value: number, attributes: MetricAttributesOf<Definition["metrics"][Alias]>) => void;
+};
+export type ContractGaugeObservation<Definition extends MetricDefinitionInput> = {
+    readonly value: number;
+    readonly attributes: MetricAttributesOf<Definition>;
+};
+export type MetricProducer<Definition extends TelemetryContractInput> = {
+    readonly counter: <Alias extends AliasesOfKind<Definition, "counter">>(alias: Alias) => ContractCounter<Definition, Alias>;
+    readonly histogram: <Alias extends AliasesOfKind<Definition, "histogram">>(alias: Alias) => ContractHistogram<Definition, Alias>;
+    readonly observableGauge: <Alias extends AliasesOfKind<Definition, "observable_gauge">>(alias: Alias, callback: () => ReadonlyArray<ContractGaugeObservation<Definition["metrics"][Alias]>>) => ObservableGaugeRegistration;
+};
+type NamedContractCounterMeasurement = {
+    readonly name: string;
+    readonly value: number;
+    readonly attributes: {
+        readonly [name: string]: MetricAttributeValue;
+    };
+};
+export declare const prepareContractCounterBatchByName: (contract: {
+    readonly metricByName: ReadonlyMap<string, CompiledMetricDefinition>;
+}, metrics: Metrics, measurements: ReadonlyArray<NamedContractCounterMeasurement>) => (() => void);
+export declare const recordContractCounterByName: (contract: {
+    readonly metricByName: ReadonlyMap<string, CompiledMetricDefinition>;
+}, metrics: Metrics, name: string, value: number, attributes: {
+    readonly [name: string]: MetricAttributeValue;
+}) => void;
+export declare const makeMetricProducer: <const Definition extends TelemetryContractInput>(contract: TelemetryContract<Definition>, metrics: Metrics) => MetricProducer<Definition>;
+export {};

package/dist/contract/MetricProducer.js

@@ -0,0 +1,123 @@
+import { prepareContractMetricAttributes, registerContractGaugeObservation, reserveMetricCounterBatch, } from "../MetricsRuntime.js";
+import { InvalidMetricMeasurement } from "./MetricContractError.js";
+import { isFiniteMetricScalar, metricScalarIdentity } from "../metrics/MetricScalar.js";
+const measurementError = (code, operation, alias, metricName, message, attributeName) => {
+    const options = { code, operation, message, metricAlias: alias };
+    if (metricName !== undefined)
+        options.metricName = metricName;
+    if (attributeName !== undefined)
+        options.attributeName = attributeName;
+    return new InvalidMetricMeasurement(options);
+};
+function resolveDefinition(contract, alias, kind) {
+    const definition = contract.metricByAlias.get(alias);
+    if (definition === undefined) {
+        throw measurementError("OBS_METRIC_UNKNOWN_ALIAS", kind, alias, undefined, `Metric alias "${alias}" is not declared by the telemetry contract. Use a declared alias.`);
+    }
+    if (definition.kind !== kind) {
+        throw measurementError("OBS_METRIC_KIND_MISMATCH", kind, alias, definition.name, `Metric alias "${alias}" has kind "${definition.kind}", not "${kind}". Use the matching producer method.`);
+    }
+    return definition;
+}
+const parseContractAttributes = (alias, definition, input) => {
+    const attributes = [];
+    for (const attributeName of definition.attributes.keys()) {
+        if (!Object.hasOwn(input, attributeName)) {
+            throw measurementError("OBS_METRIC_MISSING_ATTRIBUTE", "record", alias, definition.name, `Metric "${definition.name}" is missing declared attribute "${attributeName}". Provide every declared attribute.`, attributeName);
+        }
+    }
+    for (const [attributeName, value] of Object.entries(input)) {
+        const attributeDefinition = definition.attributes.get(attributeName);
+        if (attributeDefinition === undefined) {
+            throw measurementError("OBS_METRIC_UNDECLARED_ATTRIBUTE", "record", alias, definition.name, `Metric "${definition.name}" does not declare attribute "${attributeName}". Remove it or add it to the contract.`, attributeName);
+        }
+        if (!isFiniteMetricScalar(value)) {
+            throw measurementError("OBS_METRIC_INVALID_VALUE", "record", alias, definition.name, `Metric "${definition.name}" attribute "${attributeName}" must be a finite scalar value.`, attributeName);
+        }
+        const allowedValues = attributeDefinition.allowedValues;
+        if (allowedValues !== undefined &&
+            !allowedValues.some((allowed) => metricScalarIdentity(allowed) === metricScalarIdentity(value))) {
+            throw measurementError("OBS_METRIC_VALUE_NOT_ALLOWED", "record", alias, definition.name, `Metric "${definition.name}" attribute "${attributeName}" is outside its declared allowed values. Use a declared value.`, attributeName);
+        }
+        attributes.push({ key: attributeName, value });
+    }
+    return attributes;
+};
+const cardinalityLimits = (definition) => Array.from(definition.attributes, ([attributeName, attribute]) => ({
+    attributeName,
+    maximumCardinality: attribute.maximumCardinality,
+}));
+const counterHandle = (metrics, alias, definition) => {
+    const counter = metrics.counter(definition);
+    return {
+        add: (value, input) => {
+            const attributes = parseContractAttributes(alias, definition, input);
+            const commit = prepareContractMetricAttributes(metrics, alias, definition.name, definition, attributes, cardinalityLimits(definition));
+            counter.add(value, attributes);
+            commit();
+        },
+    };
+};
+const histogramHandle = (metrics, alias, definition) => {
+    const histogram = metrics.histogram(definition);
+    return {
+        record: (value, input) => {
+            const attributes = parseContractAttributes(alias, definition, input);
+            const commit = prepareContractMetricAttributes(metrics, alias, definition.name, definition, attributes, cardinalityLimits(definition));
+            histogram.record(value, attributes);
+            commit();
+        },
+    };
+};
+const resolveContractCounterByName = (contract, name) => {
+    const definition = contract.metricByName.get(name);
+    if (definition === undefined) {
+        throw measurementError("OBS_METRIC_UNKNOWN_ALIAS", "counter", name, name, `Metric "${name}" is not declared by the telemetry contract. Use a declared canonical metric name.`);
+    }
+    if (definition.kind !== "counter") {
+        throw measurementError("OBS_METRIC_KIND_MISMATCH", "counter", definition.alias, definition.name, `Metric "${name}" has kind "${definition.kind}", not "counter". Use a declared counter.`);
+    }
+    return definition;
+};
+export const prepareContractCounterBatchByName = (contract, metrics, measurements) => {
+    const batch = [];
+    for (const measurement of measurements) {
+        const definition = resolveContractCounterByName(contract, measurement.name);
+        const attributes = parseContractAttributes(definition.alias, definition, measurement.attributes);
+        const admission = {
+            metrics,
+            metricAlias: definition.alias,
+            metricName: definition.name,
+            definitionIdentity: definition,
+            attributes,
+            limits: cardinalityLimits(definition),
+        };
+        batch.push({ definition, value: measurement.value, attributes, admission });
+    }
+    return reserveMetricCounterBatch(metrics, batch);
+};
+export const recordContractCounterByName = (contract, metrics, name, value, attributes) => prepareContractCounterBatchByName(contract, metrics, [{ name, value, attributes }])();
+export const makeMetricProducer = (contract, metrics) => ({
+    counter: (alias) => {
+        const definition = resolveDefinition(contract, alias, "counter");
+        return counterHandle(metrics, alias, definition);
+    },
+    histogram: (alias) => {
+        const definition = resolveDefinition(contract, alias, "histogram");
+        return histogramHandle(metrics, alias, definition);
+    },
+    observableGauge: (alias, callback) => {
+        const definition = resolveDefinition(contract, alias, "observable_gauge");
+        return metrics.observableGauge(definition, () => callback().map((observation) => {
+            const attributes = parseContractAttributes(alias, definition, observation.attributes);
+            return registerContractGaugeObservation({ value: observation.value, attributes }, {
+                metrics,
+                metricAlias: alias,
+                metricName: definition.name,
+                definitionIdentity: definition,
+                attributes,
+                limits: cardinalityLimits(definition),
+            });
+        }));
+    },
+});