@posthog/core 1.39.6 → 1.40.0

package/dist/metrics/metrics-utils.js

@@ -0,0 +1,117 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    bucketIndexFor: ()=>bucketIndexFor,
+    buildMetricsResourceAttributes: ()=>buildMetricsResourceAttributes,
+    buildOtlpMetricsPayload: ()=>buildOtlpMetricsPayload,
+    msToUnixNano: ()=>msToUnixNano,
+    seriesKey: ()=>seriesKey,
+    DEFAULT_HISTOGRAM_BOUNDS: ()=>DEFAULT_HISTOGRAM_BOUNDS
+});
+const logs_utils_js_namespaceObject = require("../logs/logs-utils.js");
+const DEFAULT_HISTOGRAM_BOUNDS = [
+    0,
+    5,
+    10,
+    25,
+    50,
+    75,
+    100,
+    250,
+    500,
+    750,
+    1000,
+    2500,
+    5000,
+    7500,
+    10000
+];
+function msToUnixNano(ms) {
+    return String(ms) + '000000';
+}
+function seriesKey(type, name, unit, attributes) {
+    let attrsKey = '';
+    if (attributes) {
+        const keys = Object.keys(attributes).sort();
+        attrsKey = keys.map((k)=>`${JSON.stringify(k)}:${JSON.stringify(attributes[k])}`).join(',');
+    }
+    return `${type}\u0000${name}\u0000${unit ?? ''}\u0000${attrsKey}`;
+}
+function bucketIndexFor(value, bounds) {
+    for(let i = 0; i < bounds.length; i++)if (value <= bounds[i]) return i;
+    return bounds.length;
+}
+function buildMetricsResourceAttributes(config, scopeName, scopeVersion) {
+    return {
+        ...config.resourceAttributes,
+        'service.name': config.serviceName || 'unknown_service',
+        ...config.environment && {
+            'deployment.environment': config.environment
+        },
+        ...config.serviceVersion && {
+            'service.version': config.serviceVersion
+        },
+        'telemetry.sdk.name': scopeName,
+        'telemetry.sdk.version': scopeVersion
+    };
+}
+function buildOtlpMetricsPayload(metrics, resourceAttributes, scopeName, scopeVersion) {
+    return {
+        resourceMetrics: [
+            {
+                resource: {
+                    attributes: (0, logs_utils_js_namespaceObject.toOtlpKeyValueList)(resourceAttributes)
+                },
+                scopeMetrics: [
+                    {
+                        scope: {
+                            name: scopeName,
+                            version: scopeVersion
+                        },
+                        metrics
+                    }
+                ]
+            }
+        ]
+    };
+}
+exports.DEFAULT_HISTOGRAM_BOUNDS = __webpack_exports__.DEFAULT_HISTOGRAM_BOUNDS;
+exports.bucketIndexFor = __webpack_exports__.bucketIndexFor;
+exports.buildMetricsResourceAttributes = __webpack_exports__.buildMetricsResourceAttributes;
+exports.buildOtlpMetricsPayload = __webpack_exports__.buildOtlpMetricsPayload;
+exports.msToUnixNano = __webpack_exports__.msToUnixNano;
+exports.seriesKey = __webpack_exports__.seriesKey;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "DEFAULT_HISTOGRAM_BOUNDS",
+    "bucketIndexFor",
+    "buildMetricsResourceAttributes",
+    "buildOtlpMetricsPayload",
+    "msToUnixNano",
+    "seriesKey"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/metrics/metrics-utils.mjs

@@ -0,0 +1,68 @@
+import { toOtlpKeyValueList } from "../logs/logs-utils.mjs";
+const DEFAULT_HISTOGRAM_BOUNDS = [
+    0,
+    5,
+    10,
+    25,
+    50,
+    75,
+    100,
+    250,
+    500,
+    750,
+    1000,
+    2500,
+    5000,
+    7500,
+    10000
+];
+function msToUnixNano(ms) {
+    return String(ms) + '000000';
+}
+function seriesKey(type, name, unit, attributes) {
+    let attrsKey = '';
+    if (attributes) {
+        const keys = Object.keys(attributes).sort();
+        attrsKey = keys.map((k)=>`${JSON.stringify(k)}:${JSON.stringify(attributes[k])}`).join(',');
+    }
+    return `${type}\u0000${name}\u0000${unit ?? ''}\u0000${attrsKey}`;
+}
+function bucketIndexFor(value, bounds) {
+    for(let i = 0; i < bounds.length; i++)if (value <= bounds[i]) return i;
+    return bounds.length;
+}
+function buildMetricsResourceAttributes(config, scopeName, scopeVersion) {
+    return {
+        ...config.resourceAttributes,
+        'service.name': config.serviceName || 'unknown_service',
+        ...config.environment && {
+            'deployment.environment': config.environment
+        },
+        ...config.serviceVersion && {
+            'service.version': config.serviceVersion
+        },
+        'telemetry.sdk.name': scopeName,
+        'telemetry.sdk.version': scopeVersion
+    };
+}
+function buildOtlpMetricsPayload(metrics, resourceAttributes, scopeName, scopeVersion) {
+    return {
+        resourceMetrics: [
+            {
+                resource: {
+                    attributes: toOtlpKeyValueList(resourceAttributes)
+                },
+                scopeMetrics: [
+                    {
+                        scope: {
+                            name: scopeName,
+                            version: scopeVersion
+                        },
+                        metrics
+                    }
+                ]
+            }
+        ]
+    };
+}
+export { DEFAULT_HISTOGRAM_BOUNDS, bucketIndexFor, buildMetricsResourceAttributes, buildOtlpMetricsPayload, msToUnixNano, seriesKey };

package/dist/metrics/types.d.ts

@@ -0,0 +1,69 @@
+export type { MetricAttributeValue, MetricAttributes, MetricType, CaptureMetricOptions, MetricSample, BeforeSendMetricFn, Metrics, OtlpNumberDataPoint, OtlpHistogramDataPoint, OtlpMetric, OtlpMetricsPayload, } from '@posthog/types';
+import type { BeforeSendMetricFn, MetricAttributeValue, OtlpMetricsPayload } from '@posthog/types';
+/** Same tagged outcome shape as `SendLogsBatchOutcome` — one policy for both signals. */
+export type SendMetricsBatchOutcome = {
+    kind: 'ok';
+} | {
+    kind: 'retry-later';
+    error: unknown;
+} | {
+    kind: 'too-large';
+} | {
+    kind: 'fatal';
+    error: unknown;
+};
+/**
+ * The minimal host surface `PostHogMetrics` depends on. `PostHogCoreStateless`
+ * satisfies it structurally; the browser supplies an adapter backed by its
+ * own request layer.
+ */
+export interface MetricsHost {
+    readonly isDisabled: boolean;
+    readonly optedOut: boolean;
+    _sendMetricsBatch(payload: OtlpMetricsPayload): Promise<SendMetricsBatchOutcome>;
+    getLibraryId(): string;
+    getLibraryVersion(): string;
+}
+/**
+ * Configuration for the metrics feature on `new PostHog(key, { metrics: ... })`.
+ * All fields are optional; per-SDK defaults apply.
+ */
+export interface PostHogMetricsConfig {
+    /**
+     * Service name attached as the OTLP `service.name` resource attribute.
+     * Part of every series' identity; used by the Metrics UI for filtering.
+     * Defaults to `'unknown_service'` when unset.
+     */
+    serviceName?: string;
+    /** Service version attached as OTLP `service.version`. */
+    serviceVersion?: string;
+    /** Deployment environment attached as OTLP `deployment.environment`. */
+    environment?: string;
+    /**
+     * Extra OTLP resource attributes attached to every batch. Spread first;
+     * SDK-controlled keys are layered on top so users can't clobber them.
+     */
+    resourceAttributes?: Record<string, MetricAttributeValue>;
+    /**
+     * How often the aggregated window is flushed (ms). Samples are aggregated
+     * in memory between flushes — one data point per series per window, no
+     * matter how many calls. Default: 10000.
+     */
+    flushIntervalMs?: number;
+    /**
+     * Cardinality guardrail: max distinct series (name + type + unit +
+     * attribute combination) held per flush window. Samples for series beyond
+     * the cap are dropped with one warning per window. Default: 1000.
+     */
+    maxSeriesPerFlush?: number;
+    /**
+     * Pre-aggregation filter. See {@link BeforeSendMetricFn}. Configure as a
+     * single function or a chain.
+     */
+    beforeSend?: BeforeSendMetricFn | BeforeSendMetricFn[];
+}
+export interface ResolvedPostHogMetricsConfig extends PostHogMetricsConfig {
+    flushIntervalMs: number;
+    maxSeriesPerFlush: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/metrics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAElG,yFAAyF;AACzF,MAAM,MAAM,uBAAuB,GAC/B;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAErC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;IAChF,YAAY,IAAI,MAAM,CAAA;IACtB,iBAAiB,IAAI,MAAM,CAAA;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;IAEzD;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAA;CACvD;AAID,MAAM,WAAW,4BAA6B,SAAQ,oBAAoB;IACxE,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;CAC1B"}

package/dist/metrics/types.js

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/core",
-  "version": "1.39.6",
+  "version": "1.40.0",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -70,7 +70,7 @@
     }
   },
   "dependencies": {
-    "@posthog/types": "^1.392.0"
+    "@posthog/types": "^1.393.0"
   },
   "devDependencies": {
     "@rslib/core": "0.10.6",

package/src/index.ts

@@ -37,6 +37,26 @@ export type {
 // via the `logs/types` barrel so consumers don't have to import from two
 // packages to type their `captureLog` calls.
 export type { CaptureLogOptions, LogAttributeValue, LogAttributes, LogSeverityLevel } from './logs/types'
+export {
+  PostHogMetrics,
+  buildOtlpMetricsPayload,
+  buildMetricsResourceAttributes,
+  DEFAULT_HISTOGRAM_BOUNDS,
+} from './metrics'
+export type {
+  MetricsHost,
+  PostHogMetricsConfig,
+  ResolvedPostHogMetricsConfig,
+  SendMetricsBatchOutcome,
+} from './metrics'
+// Same barrel convention as logs for the user-facing metric types.
+export type {
+  CaptureMetricOptions,
+  MetricAttributes,
+  MetricAttributeValue,
+  MetricSample,
+  MetricType,
+} from './metrics/types'
 export { uuidv7 } from './vendor/uuidv7'
 export * from './cookie'
 export * from './posthog-core'