@haatlabs-core/observability 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Haatlabs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @haatlabs-core/observability
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tracing for the projects: spans that carry only allowed attributes, and trace context handed
+from one process to another as a `traceparent` string.
+
+    const tracing = startTracing({
+      serviceName: 'api',
+      tracerName: 'shop',
+      extraAttributes: ['source.id'], // a project's own, besides the shared list
+      otlpEndpoint: config.tracing.otlpEndpoint,
+    });
+
+`withSpan`, `currentTraceContext`, `runWithTraceContext` and `startHttpSpan` work whether or
+not tracing is on. Metrics stay in each project.
+
+The metrics prefix is the project's name in snake case; a prefix with anything but lowercase
+letters, digits and underscores is refused at start.
+
+## Install
+
+    pnpm add @haatlabs-core/observability
+
+It leaves one package to your app, so the app holds one copy: `prom-client`.

package/dist/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from './tracing.js';

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);
+__reExport(index_exports, require("./tracing.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./tracing.js")
+});

package/dist/cjs/metrics/index.d.ts

@@ -0,0 +1,5 @@
+export { DURATION_BUCKETS, SHOPIFY_OPERATIONS, createMetricsKit, oneOf } from './kit.js';
+export type { AiCallObservation, GaugeMaker, MetricsKit, MetricsKitOptions } from './kit.js';
+export { startMetricsServer } from './server.js';
+export { instrumentShopifyFetch } from './shopify-fetch.js';
+export { secondsSince, timed } from './timed.js';

package/dist/cjs/metrics/index.js

@@ -0,0 +1,44 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var metrics_exports = {};
+__export(metrics_exports, {
+  DURATION_BUCKETS: () => import_kit.DURATION_BUCKETS,
+  SHOPIFY_OPERATIONS: () => import_kit.SHOPIFY_OPERATIONS,
+  createMetricsKit: () => import_kit.createMetricsKit,
+  instrumentShopifyFetch: () => import_shopify_fetch.instrumentShopifyFetch,
+  oneOf: () => import_kit.oneOf,
+  secondsSince: () => import_timed.secondsSince,
+  startMetricsServer: () => import_server.startMetricsServer,
+  timed: () => import_timed.timed
+});
+module.exports = __toCommonJS(metrics_exports);
+var import_kit = require("./kit.js");
+var import_server = require("./server.js");
+var import_shopify_fetch = require("./shopify-fetch.js");
+var import_timed = require("./timed.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DURATION_BUCKETS,
+  SHOPIFY_OPERATIONS,
+  createMetricsKit,
+  instrumentShopifyFetch,
+  oneOf,
+  secondsSince,
+  startMetricsServer,
+  timed
+});

package/dist/cjs/metrics/kit.d.ts

@@ -0,0 +1,71 @@
+import { Counter, Gauge, Histogram, Registry } from 'prom-client';
+/** The buckets every project times by, in seconds. */
+export declare const DURATION_BUCKETS: number[];
+/** What a Shopify request can be: see `instrumentShopifyFetch`. */
+export declare const SHOPIFY_OPERATIONS: string[];
+/** One request to a model, as `@haatlabs-core/ai` reports it to `observeAiCalls`. */
+export interface AiCallObservation {
+    operation: 'chat' | 'embeddings';
+    model: string;
+    /** What the call served, as the app names it in its ledger; null when not named. */
+    feature: string | null;
+    outcome: 'ok' | 'error';
+    seconds: number;
+    /** What the provider said the call used; null when it did not say (or the call failed). */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number | null;
+    } | null;
+}
+/**
+ * A label value is one of a fixed set or it is "other". Labels are stored for ever and
+ * multiply the series: an ID, a domain or a secret must never become one.
+ */
+export declare const oneOf: (allowed: readonly string[], value: string) => string;
+export interface MetricsKitOptions {
+    /**
+     * Every metric's name starts with it and `_`: a project's `nameSnake`, as dashboards know
+     * it: a letter, then lowercase letters, digits and underscores.
+     */
+    prefix: string;
+    /** The dependencies a failure is counted for (`count.providerFailure`). */
+    providers: readonly string[];
+    /** What a plan limit can refuse (`count.planLimitRefusal`); none: every value is "other". */
+    usageMetrics?: readonly string[];
+    /** What a Shopify request can be; the default is every kind `instrumentShopifyFetch` names. */
+    shopifyOperations?: readonly string[];
+    /** What a model call can be for (the app's AI features); none: every value is "other". */
+    aiFeatures?: readonly string[];
+}
+export type GaugeMaker = (name: string, help: string, labelNames?: string[]) => Gauge;
+export interface MetricsKit {
+    readonly registry: Registry;
+    readonly contentType: string;
+    /** A duration histogram in seconds, with the shared buckets, named `<prefix>_<name>`. */
+    histogram(name: string, help: string, labelNames?: string[]): Histogram;
+    counter(name: string, help: string, labelNames?: string[]): Counter;
+    oneOf(allowed: readonly string[], value: string): string;
+    observe: {
+        http(method: string, route: string, status: number, seconds: number): void;
+        shopify(operation: string, outcome: string, seconds: number): void;
+        /** A request to a model: its duration, and the tokens and cost it used when known. */
+        ai(call: AiCallObservation): void;
+    };
+    count: {
+        providerFailure(provider: string): void;
+        planLimitRefusal(metric: string): void;
+    };
+    /**
+     * The totals read from the database when the metrics are scraped, in a registry of their
+     * own: `define` makes its gauges and returns how a snapshot sets them. Read at most every
+     * 30 seconds, and left out whenever they cannot be read: a stale or zero total is worse
+     * than a missing one.
+     */
+    business<S>(define: (gauge: GaugeMaker) => (snapshot: S) => void): {
+        setSource(source: () => Promise<S>): void;
+    };
+    render(): Promise<string>;
+}
+/** What every project measures the same way: HTTP, Shopify, provider failures, plan refusals. */
+export declare function createMetricsKit(options: MetricsKitOptions): MetricsKit;

package/dist/cjs/metrics/kit.js

@@ -0,0 +1,161 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var kit_exports = {};
+__export(kit_exports, {
+  DURATION_BUCKETS: () => DURATION_BUCKETS,
+  SHOPIFY_OPERATIONS: () => SHOPIFY_OPERATIONS,
+  createMetricsKit: () => createMetricsKit,
+  oneOf: () => oneOf
+});
+module.exports = __toCommonJS(kit_exports);
+var import_prom_client = require("prom-client");
+const OTHER = "other";
+const UNMATCHED_ROUTE = "unmatched";
+const DURATION_BUCKETS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
+const BUSINESS_CACHE_MS = 3e4;
+const MIN_STATUS = 100;
+const MAX_STATUS = 599;
+const STATUS_CLASS_SIZE = 100;
+const METRICS_PREFIX = /^[a-z][a-z0-9_]*$/;
+const ROUTE_PATTERN = /^\/[A-Za-z0-9_\-/:.*]{0,119}$/;
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+const SHOPIFY_OUTCOMES = ["ok", "client_error", "throttled", "server_error", "network_error"];
+const SHOPIFY_OPERATIONS = ["graphql", "oauth", "upload", "bulk_download"];
+const MODEL_LABEL = /^[A-Za-z0-9._:/-]{1,80}$/;
+const AI_OPERATIONS = ["chat", "embeddings"];
+const AI_OUTCOMES = ["ok", "error"];
+const oneOf = (allowed, value) => allowed.includes(value) ? value : OTHER;
+function createMetricsKit(options) {
+  if (!METRICS_PREFIX.test(options.prefix)) {
+    throw new Error("a metrics prefix is lowercase letters, digits and underscores");
+  }
+  const name = (suffix) => `${options.prefix}_${suffix}`;
+  const registry = new import_prom_client.Registry();
+  const histogram = (suffix, help, labelNames = []) => new import_prom_client.Histogram({
+    name: name(suffix),
+    help,
+    labelNames,
+    buckets: DURATION_BUCKETS,
+    registers: [registry]
+  });
+  const counter = (suffix, help, labelNames = []) => new import_prom_client.Counter({ name: name(suffix), help, labelNames, registers: [registry] });
+  const shopify = histogram("shopify_request_duration_seconds", "Requests to Shopify", [
+    "operation",
+    "outcome"
+  ]);
+  const http = histogram("http_request_duration_seconds", "API requests", [
+    "method",
+    "route",
+    "status_class"
+  ]);
+  const providerFailures = counter("provider_failures_total", "Failed calls to a dependency", [
+    "provider"
+  ]);
+  const planLimitRefusals = counter("plan_limit_refusals_total", "Work refused because a plan limit was reached", ["metric"]);
+  const shopifyOperations = options.shopifyOperations ?? SHOPIFY_OPERATIONS;
+  const aiDurations = histogram("ai_request_duration_seconds", "Requests to a model", [
+    "operation",
+    "model",
+    "feature",
+    "outcome"
+  ]);
+  const aiTokens = counter("ai_tokens_total", "Tokens a model used, by direction", [
+    "model",
+    "feature",
+    "direction"
+  ]);
+  const aiCost = counter("ai_cost_usd_total", "What model calls cost, in US dollars", [
+    "model",
+    "feature"
+  ]);
+  let renderBusiness = async () => "";
+  function business(define) {
+    const totals = new import_prom_client.Registry();
+    const apply = define((suffix, help, labelNames = []) => new import_prom_client.Gauge({ name: name(suffix), help, labelNames, registers: [totals] }));
+    let source = null;
+    let cached = null;
+    renderBusiness = async () => {
+      if (!source)
+        return "";
+      if (cached && Date.now() - cached.at < BUSINESS_CACHE_MS)
+        return cached.text;
+      try {
+        const snapshot = await source();
+        totals.resetMetrics();
+        apply(snapshot);
+        cached = { at: Date.now(), text: await totals.metrics() };
+        return cached.text;
+      } catch {
+        return "";
+      }
+    };
+    return {
+      setSource: (next) => {
+        source = next;
+        cached = null;
+      }
+    };
+  }
+  return {
+    registry,
+    contentType: registry.contentType,
+    histogram,
+    counter,
+    oneOf,
+    observe: {
+      http: (method, route, status, seconds) => http.observe({
+        method: oneOf(METHODS, method),
+        route: ROUTE_PATTERN.test(route) ? route : UNMATCHED_ROUTE,
+        status_class: Number.isInteger(status) && status >= MIN_STATUS && status <= MAX_STATUS ? `${Math.floor(status / STATUS_CLASS_SIZE)}xx` : OTHER
+      }, seconds),
+      shopify: (operation, outcome, seconds) => shopify.observe({
+        operation: oneOf(shopifyOperations, operation),
+        outcome: oneOf(SHOPIFY_OUTCOMES, outcome)
+      }, seconds),
+      ai: (call) => {
+        const model = MODEL_LABEL.test(call.model) ? call.model : OTHER;
+        const feature = call.feature === null ? OTHER : oneOf(options.aiFeatures ?? [], call.feature);
+        aiDurations.observe({
+          operation: oneOf(AI_OPERATIONS, call.operation),
+          model,
+          feature,
+          outcome: oneOf(AI_OUTCOMES, call.outcome)
+        }, call.seconds);
+        if (!call.usage)
+          return;
+        aiTokens.inc({ model, feature, direction: "input" }, call.usage.inputTokens);
+        aiTokens.inc({ model, feature, direction: "output" }, call.usage.outputTokens);
+        if (call.usage.costUsd !== null)
+          aiCost.inc({ model, feature }, call.usage.costUsd);
+      }
+    },
+    count: {
+      providerFailure: (provider) => providerFailures.inc({ provider: oneOf(options.providers, provider) }),
+      planLimitRefusal: (metric) => planLimitRefusals.inc({ metric: oneOf(options.usageMetrics ?? [], metric) })
+    },
+    business,
+    render: async () => `${await registry.metrics()}${await renderBusiness()}`
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DURATION_BUCKETS,
+  SHOPIFY_OPERATIONS,
+  createMetricsKit,
+  oneOf
+});

package/dist/cjs/metrics/server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Serves the metrics on their own listener. It is separate from the API's public
+ * listener on purpose: bind it to an address only the monitoring system can reach.
+ */
+export declare function startMetricsServer(options: {
+    port: number;
+    host: string;
+    metrics: {
+        render(): Promise<string>;
+        readonly contentType: string;
+    };
+}): Promise<{
+    port: number;
+    close(): Promise<void>;
+}>;

package/dist/cjs/metrics/server.js

@@ -0,0 +1,54 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_exports = {};
+__export(server_exports, {
+  startMetricsServer: () => startMetricsServer
+});
+module.exports = __toCommonJS(server_exports);
+var import_node_http = require("node:http");
+const HTTP_OK = 200;
+const HTTP_NOT_FOUND = 404;
+const HTTP_UNAVAILABLE = 503;
+async function startMetricsServer(options) {
+  const server = (0, import_node_http.createServer)((request, response) => {
+    if (request.method !== "GET" || request.url !== "/metrics") {
+      response.writeHead(HTTP_NOT_FOUND).end();
+      return;
+    }
+    options.metrics.render().then((text) => {
+      response.writeHead(HTTP_OK, { "Content-Type": options.metrics.contentType }).end(text);
+    }, () => {
+      response.writeHead(HTTP_UNAVAILABLE).end();
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, options.host, resolve);
+  });
+  return {
+    port: server.address().port,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections();
+    })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  startMetricsServer
+});

package/dist/cjs/metrics/shopify-fetch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wraps the `fetch` used for Shopify so every request is timed and classified. A
+ * response is passed back untouched; a server error or an unreachable host also counts
+ * as a failure of the provider.
+ */
+export declare function instrumentShopifyFetch(fetchImpl: typeof fetch, metrics: {
+    observe: {
+        shopify(operation: string, outcome: string, seconds: number): void;
+    };
+    count: {
+        providerFailure(provider: string): void;
+    };
+}): typeof fetch;