@superlog/otel-helpers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Superlog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @superlog/otel-helpers
+
+[![npm](https://img.shields.io/npm/v/@superlog/otel-helpers?color=2E4BFF&label=npm)](https://www.npmjs.com/package/@superlog/otel-helpers)
+[![npm downloads](https://img.shields.io/npm/dm/@superlog/otel-helpers?color=2E4BFF)](https://www.npmjs.com/package/@superlog/otel-helpers)
+[![CI](https://img.shields.io/github/actions/workflow/status/superloglabs/otel-helpers/ci.yml?branch=main&label=CI)](https://github.com/superloglabs/otel-helpers/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2E4BFF)](LICENSE)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-2E4BFF)](package.json)
+
+Tiny TypeScript helpers for native OpenTelemetry.
+
+- Add spans with minimal diff impact
+- Record LLM costs
+
+```sh
+npm i @superlog/otel-helpers @opentelemetry/api
+```
+
+## `withSpan`
+
+`withSpan` allows you to create a span around a function in a way that is easy to review.
+Here is the same `handleCheckout` instrumented two ways.
+
+Original:
+
+```ts
+async function handleCheckout(orderId: string) {
+  const order = await loadOrder(orderId);
+  await chargeCard(order);
+  return order;
+}
+```
+
+Vanilla OpenTelemetry SDK:
+
+```diff
+--- original.ts
++++ manual.ts
+@@ -1,5 +1,20 @@
++import { trace, SpanStatusCode } from "@opentelemetry/api";
++
++const tracer = trace.getTracer("checkout");
++
+ async function handleCheckout(orderId: string) {
+-  const order = await loadOrder(orderId);
+-  await chargeCard(order);
+-  return order;
++  return tracer.startActiveSpan("api.checkout", async (span) => {
++    try {
++      span.setAttribute("order.id", orderId);
++      const order = await loadOrder(orderId);
++      await chargeCard(order);
++      return order;
++    } catch (err) {
++      span.recordException(err as Error);
++      span.setStatus({ code: SpanStatusCode.ERROR });
++      throw err;
++    } finally {
++      span.end();
++    }
++  });
+ }
+```
+
+Notice that:
+- The entire function is indented, creating a long diff hunk. 
+  - The reviewer needs to visually compare versions to analyze changes.
+- The try/catch block creates code changes around the key logic of the function.
+
+Here's the diff produced by `withSpan`:
+
+```diff
+--- original.ts
++++ helper.ts
+@@ -1,5 +1,8 @@
+-async function handleCheckout(orderId: string) {
++import { withSpan } from "@superlog/otel-helpers";
++
++const handleCheckout = withSpan("api.checkout", async (span, orderId: string) => {
++  span.setAttribute("order.id", orderId);
+   const order = await loadOrder(orderId);
+   await chargeCard(order);
+   return order;
+-}
++});
+```
+
+- The diff is now purely additive
+- It is easy to identify the scope of the changes and their potential impact.
+
+## GenAI spans
+
+- Creates spans and metrics for LLM calls 
+- Respects OTel Semantic conventions
+
+```ts
+import { withGenAiSpan, recordGenAiUsage, anthropicUsage } from "@superlog/otel-helpers";
+
+const response = await withGenAiSpan(
+  {
+    operation: "chat",
+    provider: "anthropic",
+    requestModel: MODEL,
+    useCase: "stylist",
+    callSite: "initial",
+  },
+  async (span) => {
+    const res = await client.messages.create({
+      model: MODEL,
+      max_tokens: 2048,
+      system: SYSTEM_PROMPT,
+      tools,
+      messages,
+    });
+
+    recordGenAiUsage(span, anthropicUsage(res));
+    return res;
+  },
+);
+```
+
+The package emits current OpenTelemetry GenAI semantic convention attributes:
+
+- `gen_ai.operation.name`
+- `gen_ai.provider.name`
+- `gen_ai.request.model`
+- `gen_ai.response.model`
+- `gen_ai.usage.input_tokens`
+- `gen_ai.usage.output_tokens`
+- `gen_ai.response.finish_reasons`
+
+The GenAI semantic conventions are currently marked Development by OpenTelemetry. This package follows the current names, and keeps product-specific dimensions under `app.gen_ai.*`.
+
+## Publishing a new version
+
+Tag a release. GitHub Actions publishes to npm with provenance:
+
+```sh
+pnpm version patch   # or minor / major
+git push origin main --tags
+```
+
+## License
+
+MIT

package/dist/gen-ai.d.ts

@@ -0,0 +1,59 @@
+import { type Attributes, type Histogram, type Meter, type Span } from "@opentelemetry/api";
+import { type WithSpanOptions } from "./span.js";
+export type GenAiOperationName = "chat" | "create_agent" | "embeddings" | "execute_tool" | "generate_content" | "invoke_agent" | "invoke_workflow" | "retrieval" | "text_completion" | (string & {});
+export type GenAiProviderName = "anthropic" | "aws.bedrock" | "azure.ai.inference" | "azure.ai.openai" | "cohere" | "deepseek" | "gcp.gemini" | "gcp.gen_ai" | "gcp.vertex_ai" | "groq" | "ibm.watsonx.ai" | "mistral_ai" | "openai" | "perplexity" | "x_ai" | (string & {});
+export type GenAiOutputType = "image" | "json" | "speech" | "text" | (string & {});
+export type GenAiTokenType = "input" | "output";
+export type GenAiSpanConfig = {
+    operation: GenAiOperationName;
+    provider: GenAiProviderName;
+    requestModel?: string;
+    responseModel?: string;
+    conversationId?: string;
+    outputType?: GenAiOutputType;
+    useCase?: string;
+    callSite?: string;
+    attributes?: Attributes;
+    spanName?: string;
+};
+export type GenAiUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+    reasoningOutputTokens?: number;
+    responseModel?: string;
+    finishReasons?: string[];
+    costUsd?: number;
+};
+export type GenAiCostInput = {
+    inputTokens?: number;
+    outputTokens?: number;
+    inputUsdPer1M: number;
+    outputUsdPer1M: number;
+};
+export type GenAiMetrics = {
+    tokenUsage: Histogram;
+    operationDuration: Histogram;
+};
+export type GenAiMetricRecorder = {
+    metrics: GenAiMetrics;
+    operation: GenAiOperationName;
+    provider: GenAiProviderName;
+    requestModel?: string;
+    responseModel?: string;
+    useCase?: string;
+    callSite?: string;
+    durationSeconds?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+};
+export declare function genAiSpanName(config: Pick<GenAiSpanConfig, "operation" | "requestModel">): string;
+export declare function genAiAttributes(config: GenAiSpanConfig & GenAiUsage): Attributes;
+export declare function withGenAiSpan<TResult>(config: GenAiSpanConfig, fn: (span: Span) => TResult | Promise<TResult>, options?: WithSpanOptions): Promise<Awaited<TResult>>;
+export declare function recordGenAiUsage(span: Span, usage: GenAiUsage): void;
+export declare function createGenAiMetrics(meter?: Meter): GenAiMetrics;
+export declare function recordGenAiMetrics(input: GenAiMetricRecorder): void;
+export declare function estimateGenAiCostUsd(input: GenAiCostInput): number;
+export declare function anthropicUsage(response: unknown): GenAiUsage;
+export declare function openAiUsage(response: unknown): GenAiUsage;

package/dist/gen-ai.js

@@ -0,0 +1,113 @@
+import { SpanKind, metrics, } from "@opentelemetry/api";
+import { withSpan } from "./span.js";
+const defaultMeter = metrics.getMeter("@superlog/otel-helpers");
+export function genAiSpanName(config) {
+    return config.requestModel ? `${config.operation} ${config.requestModel}` : config.operation;
+}
+export function genAiAttributes(config) {
+    return compactAttributes({
+        "gen_ai.operation.name": config.operation,
+        "gen_ai.provider.name": config.provider,
+        "gen_ai.request.model": config.requestModel,
+        "gen_ai.response.model": config.responseModel,
+        "gen_ai.conversation.id": config.conversationId,
+        "gen_ai.output.type": config.outputType,
+        "gen_ai.usage.input_tokens": config.inputTokens,
+        "gen_ai.usage.output_tokens": config.outputTokens,
+        "gen_ai.usage.cache_read.input_tokens": config.cacheReadInputTokens,
+        "gen_ai.usage.cache_creation.input_tokens": config.cacheCreationInputTokens,
+        "gen_ai.usage.reasoning.output_tokens": config.reasoningOutputTokens,
+        "gen_ai.response.finish_reasons": config.finishReasons,
+        "app.gen_ai.use_case": config.useCase,
+        "app.gen_ai.call_site": config.callSite,
+        "app.gen_ai.cost_usd": config.costUsd,
+        ...config.attributes,
+    });
+}
+export async function withGenAiSpan(config, fn, options = {}) {
+    return withSpan(config.spanName ?? genAiSpanName(config), fn, {
+        ...options,
+        kind: options.kind ?? SpanKind.CLIENT,
+        attributes: {
+            ...genAiAttributes(config),
+            ...options.attributes,
+        },
+    });
+}
+export function recordGenAiUsage(span, usage) {
+    span.setAttributes(genAiAttributes({ operation: "", provider: "", ...usage }));
+}
+export function createGenAiMetrics(meter = defaultMeter) {
+    return {
+        tokenUsage: meter.createHistogram("gen_ai.client.token.usage", {
+            description: "Measures number of input and output tokens used.",
+            unit: "{token}",
+        }),
+        operationDuration: meter.createHistogram("gen_ai.client.operation.duration", {
+            description: "GenAI operation duration.",
+            unit: "s",
+        }),
+    };
+}
+export function recordGenAiMetrics(input) {
+    const attrs = compactAttributes({
+        "gen_ai.operation.name": input.operation,
+        "gen_ai.provider.name": input.provider,
+        "gen_ai.request.model": input.requestModel,
+        "gen_ai.response.model": input.responseModel,
+        "app.gen_ai.use_case": input.useCase,
+        "app.gen_ai.call_site": input.callSite,
+    });
+    if (input.inputTokens !== undefined) {
+        input.metrics.tokenUsage.record(input.inputTokens, {
+            ...attrs,
+            "gen_ai.token.type": "input",
+        });
+    }
+    if (input.outputTokens !== undefined) {
+        input.metrics.tokenUsage.record(input.outputTokens, {
+            ...attrs,
+            "gen_ai.token.type": "output",
+        });
+    }
+    if (input.durationSeconds !== undefined) {
+        input.metrics.operationDuration.record(input.durationSeconds, attrs);
+    }
+}
+export function estimateGenAiCostUsd(input) {
+    return (((input.inputTokens ?? 0) * input.inputUsdPer1M) / 1_000_000 +
+        ((input.outputTokens ?? 0) * input.outputUsdPer1M) / 1_000_000);
+}
+export function anthropicUsage(response) {
+    const usage = getObject(getObject(response).usage);
+    const stopReason = getObject(response).stop_reason;
+    return {
+        inputTokens: numberOrUndefined(usage.input_tokens),
+        outputTokens: numberOrUndefined(usage.output_tokens),
+        cacheReadInputTokens: numberOrUndefined(usage.cache_read_input_tokens),
+        cacheCreationInputTokens: numberOrUndefined(usage.cache_creation_input_tokens),
+        finishReasons: typeof stopReason === "string" ? [stopReason] : undefined,
+    };
+}
+export function openAiUsage(response) {
+    const obj = getObject(response);
+    const usage = getObject(obj.usage);
+    const choice = Array.isArray(obj.choices) ? getObject(obj.choices[0]) : {};
+    const finishReason = choice.finish_reason;
+    return {
+        inputTokens: numberOrUndefined(usage.prompt_tokens),
+        outputTokens: numberOrUndefined(usage.completion_tokens),
+        responseModel: typeof obj.model === "string" ? obj.model : undefined,
+        finishReasons: typeof finishReason === "string" ? [finishReason] : undefined,
+    };
+}
+function compactAttributes(attrs) {
+    return Object.fromEntries(Object.entries(attrs).filter(([, value]) => value !== undefined && value !== null && value !== ""));
+}
+function numberOrUndefined(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function getObject(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+//# sourceMappingURL=gen-ai.js.map

package/dist/gen-ai.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { recordSpanError, spanErrorAttributes, withSpan, type WithSpanOptions, } from "./span.js";
+export { anthropicUsage, createGenAiMetrics, estimateGenAiCostUsd, genAiAttributes, genAiSpanName, openAiUsage, recordGenAiMetrics, recordGenAiUsage, withGenAiSpan, type GenAiCostInput, type GenAiMetricRecorder, type GenAiMetrics, type GenAiOperationName, type GenAiOutputType, type GenAiProviderName, type GenAiSpanConfig, type GenAiTokenType, type GenAiUsage, } from "./gen-ai.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { recordSpanError, spanErrorAttributes, withSpan, } from "./span.js";
+export { anthropicUsage, createGenAiMetrics, estimateGenAiCostUsd, genAiAttributes, genAiSpanName, openAiUsage, recordGenAiMetrics, recordGenAiUsage, withGenAiSpan, } from "./gen-ai.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,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,QAAQ,GAET,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GAUd,MAAM,aAAa,CAAC"}

package/dist/span.d.ts

@@ -0,0 +1,9 @@
+import { SpanKind, type Attributes, type Span, type SpanOptions, type Tracer } from "@opentelemetry/api";
+export type WithSpanOptions = Omit<SpanOptions, "attributes" | "kind"> & {
+    attributes?: Attributes;
+    kind?: SpanKind;
+    tracer?: Tracer;
+};
+export declare function withSpan<TResult>(name: string, fn: (span: Span) => TResult | Promise<TResult>, options?: WithSpanOptions): Promise<Awaited<TResult>>;
+export declare function recordSpanError(span: Span, err: unknown): void;
+export declare function spanErrorAttributes(err: unknown): Attributes;

package/dist/span.js

@@ -0,0 +1,44 @@
+import { SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+const defaultTracer = trace.getTracer("@superlog/otel-helpers");
+export async function withSpan(name, fn, options = {}) {
+    const { tracer = defaultTracer, attributes, kind = SpanKind.INTERNAL, ...spanOptions } = options;
+    const result = await tracer.startActiveSpan(name, { ...spanOptions, attributes, kind }, async (span) => {
+        try {
+            return await fn(span);
+        }
+        catch (err) {
+            recordSpanError(span, err);
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+    return result;
+}
+export function recordSpanError(span, err) {
+    span.recordException(toException(err));
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    span.setAttributes(spanErrorAttributes(err));
+}
+export function spanErrorAttributes(err) {
+    return {
+        "error.type": errorType(err),
+    };
+}
+function toException(err) {
+    if (err instanceof Error)
+        return err;
+    return new Error(typeof err === "string" ? err : JSON.stringify(err));
+}
+function errorType(err) {
+    if (err instanceof Error)
+        return err.name || "Error";
+    if (typeof err === "object" && err !== null) {
+        const maybeCode = err.code;
+        if (typeof maybeCode === "string" && maybeCode.length > 0)
+            return maybeCode;
+    }
+    return typeof err;
+}
+//# sourceMappingURL=span.js.map

package/dist/span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,GAKN,MAAM,oBAAoB,CAAC;AAE5B,MAAM,aAAa,GAAG,KAAK,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC;AAQhE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,EAA8C,EAC9C,UAA2B,EAAE;IAE7B,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,UAAU,EAAE,IAAI,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,CAAC;IAEjG,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,GAAG,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACrG,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC3B,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAA0B,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAU,EAAE,GAAY;IACtD,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,aAAa,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO;QACL,YAAY,EAAE,SAAS,CAAC,GAAG,CAAC;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC;IACrC,OAAO,IAAI,KAAK,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,SAAS,GAAI,GAA0B,CAAC,IAAI,CAAC;QACnD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9E,CAAC;IACD,OAAO,OAAO,GAAG,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@superlog/otel-helpers",
+  "version": "0.1.0",
+  "description": "Tiny TypeScript helpers for native OpenTelemetry spans and GenAI semantic conventions.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "homepage": "https://github.com/superloglabs/otel-helpers#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superloglabs/otel-helpers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/superloglabs/otel-helpers/issues"
+  },
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "observability",
+    "genai",
+    "llm",
+    "ai"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}