@logbrew/sdk 0.1.7 → 0.1.8

package/README.md

@@ -250,6 +250,7 @@ Use `client.metric()` when application code already knows the measurement name,
 ```js
 client.metric("evt_metric_001", "2026-06-02T10:00:06Z", {
   name: "checkout.requests",
+  description: "Number of checkout requests accepted by the application.",
   kind: "counter",
   value: 42,
   unit: "{request}",
@@ -258,7 +259,7 @@ client.metric("evt_metric_001", "2026-06-02T10:00:06Z", {
 });
 ```
 
-Metric `kind` must be `counter`, `gauge`, or `histogram`. Counters and histograms must be non-negative and use `delta` or `cumulative` temporality; gauges use `instant` temporality and may be negative. Keep metric metadata primitive and low-cardinality, such as service, region, or route template.
+Metric `kind` must be `counter`, `gauge`, or `histogram`. Counters and histograms must be non-negative and use `delta` or `cumulative` temporality; gauges use `instant` temporality and may be negative. An optional `description` gives humans and investigation tools stable meaning for the measurement; keep it generic, single-line, between 1 and 1,024 Unicode characters, and free of identifiers, personal data, or changing values. It is not a query dimension. Keep metric metadata primitive and low-cardinality, such as service, region, or route template.
 
 ## W3C Trace Context
 

package/core.cjs

@@ -23,6 +23,7 @@ const PRODUCT_ANALYTICS_SCHEMA_VERSION = 1;
 const PRODUCT_ANALYTICS_KINDS = Object.freeze(["page_view", "screen_view", "interaction"]);
 const MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH = 256;
 const METRIC_KINDS = new Set(["counter", "gauge", "histogram"]);
+const MAX_METRIC_DESCRIPTION_LENGTH = 1024;
 const NON_NEGATIVE_METRIC_KINDS = new Set(["counter", "histogram"]);
 const METRIC_TEMPORALITIES_BY_KIND = new Map([
   ["counter", new Set(["delta", "cumulative"])],
@@ -2272,9 +2273,11 @@ function validateMetric(attributes) {
   if (NON_NEGATIVE_METRIC_KINDS.has(attributes.kind) && attributes.value < 0) {
     throw new SdkError("validation_error", `metric ${attributes.kind} value must be non-negative`);
   }
+  const description = metricDescriptionOrUndefined(attributes.description);
 
   return withMetadata({
     name: attributes.name,
+    ...(description === undefined ? {} : { description }),
     kind: attributes.kind,
     value: attributes.value,
     unit: attributes.unit,
@@ -2282,6 +2285,33 @@ function validateMetric(attributes) {
   }, attributes.metadata, attributes.context);
 }
 
+function metricDescriptionOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  const characters = typeof value === "string" ? Array.from(value) : [];
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || characters.length > MAX_METRIC_DESCRIPTION_LENGTH
+    || characters.some((character) => {
+      const code = character.codePointAt(0);
+      return code !== undefined && (
+        code <= 31
+        || (code >= 127 && code <= 159)
+        || code === 0x2028
+        || code === 0x2029
+      );
+    })
+  ) {
+    throw new SdkError(
+      "validation_error",
+      `metric description must be a non-blank string of at most ${MAX_METRIC_DESCRIPTION_LENGTH} non-control characters`
+    );
+  }
+  return value.trim();
+}
+
 function productActionDetails(action) {
   if (typeof action === "string") {
     return { name: action, status: "success" };

package/index.d.cts

@@ -623,6 +623,8 @@ export type SupportTicketDraft = {
 /** Public metric event attributes. Use low-cardinality metadata only. */
 export type MetricAttributes = {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "counter" | "histogram";
   value: number;
   unit: string;
@@ -631,6 +633,8 @@ export type MetricAttributes = {
   context?: TelemetryContext;
 } | {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "gauge";
   value: number;
   unit: string;

package/index.d.ts

@@ -623,6 +623,8 @@ export type SupportTicketDraft = {
 /** Public metric event attributes. Use low-cardinality metadata only. */
 export type MetricAttributes = {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "counter" | "histogram";
   value: number;
   unit: string;
@@ -631,6 +633,8 @@ export type MetricAttributes = {
   context?: TelemetryContext;
 } | {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "gauge";
   value: number;
   unit: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",