@hebo-ai/gateway 0.4.0-alpha.4 → 0.4.0-beta.1

package/README.md

@@ -301,7 +301,7 @@ const gw = gateway({
      */
     before: async (ctx: {
       body: ChatCompletionsBody | EmbeddingsBody;
-      operation: "text" | "embeddings";
+      operation: "chat" | "embeddings";
     }): Promise<ChatCompletionsBody | EmbeddingsBody | void> => {
       // Example Use Cases:
       // - Transform request body
@@ -328,7 +328,7 @@ const gw = gateway({
      * @param ctx.models ModelCatalog from config.
      * @param ctx.body The parsed body object with all call parameters.
      * @param ctx.modelId Resolved model ID.
-     * @param ctx.operation Operation type ("text" | "embeddings").
+     * @param ctx.operation Operation type ("chat" | "embeddings").
      * @returns ProviderV3 to override, or undefined to use default.
      */
     resolveProvider: async (ctx: {
@@ -336,7 +336,7 @@ const gw = gateway({
       models: ModelCatalog;
       body: ChatCompletionsBody | EmbeddingsBody;
       modelId: ModelId;
-      operation: "text" | "embeddings";
+      operation: "chat" | "embeddings";
     }): Promise<ProviderV3 | void> => {
       // Example Use Cases:
       // - Routing logic between providers
@@ -617,12 +617,21 @@ const gw = gateway({
     enabled: true,
     // default: TraceProivder from @opentelemetry/api singleton
     tracer: trace.getTracer("my-gateway"),
+    // "required" = minimal baseline attributes
+    // "recommended" = practical operational attributes (request/response metadata, genai model/usage fields)
+    // "full" = also include body fields (e.g. genai input/output messages)
+    attributes: "full",
   },
 });
 ```
 
+Attribute names and span semantics follow OpenTelemetry GenAI semantic conventions:
+https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+
 > [!TIP]
-> For observability integration that is not otel compliant (for example, Langfuse), you can disable built-in telemetry and manually instrument requests during `before` / `after` hooks.
+> To populate custom span attributes, the inbound W3C `baggage` header is supported. Keys in the `hebo.` namespace are mapped to span attributes, with the namespace stripped. For example: `baggage: hebo.user_id=u-123` becomes span attribute `user_id=u-123`.
+
+For observability integration that is not otel compliant, you can disable built-in telemetry and manually instrument requests during `before` / `after` hooks.
 
 ### Passing Framework State to Hooks
 

package/dist/config.js

@@ -55,8 +55,8 @@ export const parseConfig = (config) => {
         ...config,
         logger: config.logger,
         telemetry: {
+            ...config.telemetry,
             enabled: config.telemetry?.enabled ?? false,
-            tracer: config.telemetry?.tracer,
         },
         providers: parsedProviders,
         models: parsedModels,

package/dist/endpoints/chat-completions/handler.js

@@ -1,12 +1,11 @@
-import { generateText, streamText, wrapLanguageModel } from "ai";
+import { generateText, Output, streamText, wrapLanguageModel, } from "ai";
 import * as z from "zod/mini";
 import { GatewayError } from "../../errors/gateway";
 import { winterCgHandler } from "../../lifecycle";
 import { logger } from "../../logger";
 import { modelMiddlewareMatcher } from "../../middleware/matcher";
 import { resolveProvider } from "../../providers/registry";
-import { toAiSdkTelemetry } from "../../telemetry/otel";
-import { markPerf } from "../../telemetry/perf";
+import { addSpanEvent } from "../../telemetry/span";
 import { resolveRequestId } from "../../utils/headers";
 import { prepareForwardHeaders } from "../../utils/request";
 import { convertToTextCallOptions, toChatCompletions, toChatCompletionsStream } from "./converters";
@@ -14,6 +13,7 @@ import { ChatCompletionsBodySchema } from "./schema";
 export const chatCompletions = (config) => {
     const hooks = config.hooks;
     const handler = async (ctx) => {
+        addSpanEvent("hebo.handler.started");
         // Guard: enforce HTTP method early.
         if (!ctx.request || ctx.request.method !== "POST") {
             throw new GatewayError("Method Not Allowed", 405);
@@ -27,19 +27,28 @@ export const chatCompletions = (config) => {
         catch {
             throw new GatewayError("Invalid JSON", 400);
         }
+        addSpanEvent("hebo.request.deserialized");
         const parsed = ChatCompletionsBodySchema.safeParse(body);
         if (!parsed.success) {
             throw new GatewayError(z.prettifyError(parsed.error), 400);
         }
         ctx.body = parsed.data;
-        ctx.operation = "text";
-        ctx.body = (await hooks?.before?.(ctx)) ?? ctx.body;
+        addSpanEvent("hebo.request.parsed");
+        ctx.operation = "chat";
+        if (hooks?.before) {
+            ctx.body = (await hooks.before(ctx)) ?? ctx.body;
+            addSpanEvent("hebo.hooks.before.completed");
+        }
         // Resolve model + provider (hooks may override defaults).
         let inputs, stream;
         ({ model: ctx.modelId, stream, ...inputs } = ctx.body);
         ctx.resolvedModelId =
             (await hooks?.resolveModelId?.(ctx)) ?? ctx.modelId;
         logger.debug(`[chat] resolved ${ctx.modelId} to ${ctx.resolvedModelId}`);
+        addSpanEvent("hebo.model.resolved", {
+            "gen_ai.request.model": ctx.modelId ?? "",
+            "gen_ai.response.model": ctx.resolvedModelId ?? "",
+        });
         const override = await hooks?.resolveProvider?.(ctx);
         ctx.provider =
             override ??
@@ -52,36 +61,41 @@ export const chatCompletions = (config) => {
         const languageModel = ctx.provider.languageModel(ctx.resolvedModelId);
         ctx.resolvedProviderId = languageModel.provider;
         logger.debug(`[chat] using ${languageModel.provider} for ${ctx.resolvedModelId}`);
+        addSpanEvent("hebo.provider.resolved", { "gen_ai.provider.name": ctx.resolvedProviderId });
         // Convert inputs to AI SDK call options.
         const textOptions = convertToTextCallOptions(inputs);
         logger.trace({
             requestId,
             options: textOptions,
         }, "[chat] AI SDK options");
+        addSpanEvent("hebo.options.prepared");
         // Build middleware chain (model -> forward params -> provider).
         const languageModelWithMiddleware = wrapLanguageModel({
             model: languageModel,
             middleware: modelMiddlewareMatcher.for(ctx.resolvedModelId, languageModel.provider),
         });
         // Execute request (streaming vs. non-streaming).
-        markPerf(ctx.request, "aiSdkStart");
         if (stream) {
+            addSpanEvent("hebo.ai-sdk.started");
             const result = streamText({
                 model: languageModelWithMiddleware,
                 headers: prepareForwardHeaders(ctx.request),
-                experimental_telemetry: toAiSdkTelemetry(config, ctx.operation),
                 // No abort signal here, otherwise we can't detect upstream from client cancellations
                 // abortSignal: ctx.request.signal,
                 onError: ({ error }) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
                     logger.error({
                         requestId,
-                        err: error instanceof Error ? error : new Error(String(error)),
+                        err,
                     });
                     throw error;
                 },
                 onAbort: () => {
                     throw new DOMException("Upstream failed", "AbortError");
                 },
+                onFinish: (result) => {
+                    ctx.streamResult = toChatCompletions(result, ctx.resolvedModelId);
+                },
                 timeout: {
                     totalMs: 5 * 60 * 1000,
                 },
@@ -91,14 +105,19 @@ export const chatCompletions = (config) => {
                 includeRawChunks: false,
                 ...textOptions,
             });
-            markPerf(ctx.request, "aiSdkEnd");
-            ctx.result = toChatCompletionsStream(result, ctx.modelId);
-            return (await hooks?.after?.(ctx)) ?? ctx.result;
+            addSpanEvent("hebo.ai-sdk.completed");
+            ctx.result = toChatCompletionsStream(result, ctx.resolvedModelId);
+            addSpanEvent("hebo.result.transformed");
+            if (hooks?.after) {
+                ctx.result = (await hooks.after(ctx)) ?? ctx.result;
+                addSpanEvent("hebo.hooks.after.completed");
+            }
+            return ctx.result;
         }
+        addSpanEvent("hebo.ai-sdk.started");
         const result = await generateText({
             model: languageModelWithMiddleware,
             headers: prepareForwardHeaders(ctx.request),
-            experimental_telemetry: toAiSdkTelemetry(config, ctx.operation),
             // FUTURE: currently can't tell whether upstream or downstream abort
             abortSignal: ctx.request.signal,
             experimental_include: {
@@ -108,10 +127,15 @@ export const chatCompletions = (config) => {
             timeout: 5 * 60 * 1000,
             ...textOptions,
         });
-        markPerf(ctx.request, "aiSdkEnd");
         logger.trace({ requestId, result }, "[chat] AI SDK result");
-        ctx.result = toChatCompletions(result, ctx.modelId);
-        return (await hooks?.after?.(ctx)) ?? ctx.result;
+        addSpanEvent("hebo.ai-sdk.completed");
+        ctx.result = toChatCompletions(result, ctx.resolvedModelId);
+        addSpanEvent("hebo.result.transformed");
+        if (hooks?.after) {
+            ctx.result = (await hooks.after(ctx)) ?? ctx.result;
+            addSpanEvent("hebo.hooks.after.completed");
+        }
+        return ctx.result;
     };
     return { handler: winterCgHandler(handler, config) };
 };

package/dist/endpoints/embeddings/handler.js

@@ -5,8 +5,7 @@ import { winterCgHandler } from "../../lifecycle";
 import { logger } from "../../logger";
 import { modelMiddlewareMatcher } from "../../middleware/matcher";
 import { resolveProvider } from "../../providers/registry";
-import { toAiSdkTelemetry } from "../../telemetry/otel";
-import { markPerf } from "../../telemetry/perf";
+import { addSpanEvent } from "../../telemetry/span";
 import { resolveRequestId } from "../../utils/headers";
 import { prepareForwardHeaders } from "../../utils/request";
 import { convertToEmbedCallOptions, toEmbeddings } from "./converters";
@@ -14,6 +13,7 @@ import { EmbeddingsBodySchema } from "./schema";
 export const embeddings = (config) => {
     const hooks = config.hooks;
     const handler = async (ctx) => {
+        addSpanEvent("hebo.handler.started");
         // Guard: enforce HTTP method early.
         if (!ctx.request || ctx.request.method !== "POST") {
             throw new GatewayError("Method Not Allowed", 405);
@@ -27,19 +27,28 @@ export const embeddings = (config) => {
         catch {
             throw new GatewayError("Invalid JSON", 400);
         }
+        addSpanEvent("hebo.request.deserialized");
         const parsed = EmbeddingsBodySchema.safeParse(body);
         if (!parsed.success) {
             throw new GatewayError(z.prettifyError(parsed.error), 400);
         }
         ctx.body = parsed.data;
+        addSpanEvent("hebo.request.parsed");
         ctx.operation = "embeddings";
-        ctx.body = (await hooks?.before?.(ctx)) ?? ctx.body;
+        if (hooks?.before) {
+            ctx.body = (await hooks.before(ctx)) ?? ctx.body;
+            addSpanEvent("hebo.hooks.before.completed");
+        }
         // Resolve model + provider (hooks may override defaults).
         let inputs;
         ({ model: ctx.modelId, ...inputs } = ctx.body);
         ctx.resolvedModelId =
             (await hooks?.resolveModelId?.(ctx)) ?? ctx.modelId;
         logger.debug(`[embeddings] resolved ${ctx.modelId} to ${ctx.resolvedModelId}`);
+        addSpanEvent("hebo.model.resolved", {
+            "gen_ai.request.model": ctx.modelId ?? "",
+            "gen_ai.response.model": ctx.resolvedModelId ?? "",
+        });
         const override = await hooks?.resolveProvider?.(ctx);
         ctx.provider =
             override ??
@@ -52,27 +61,35 @@ export const embeddings = (config) => {
         const embeddingModel = ctx.provider.embeddingModel(ctx.resolvedModelId);
         ctx.resolvedProviderId = embeddingModel.provider;
         logger.debug(`[embeddings] using ${embeddingModel.provider} for ${ctx.resolvedModelId}`);
+        addSpanEvent("hebo.provider.resolved", {
+            "gen_ai.provider.name": ctx.resolvedProviderId,
+        });
         // Convert inputs to AI SDK call options.
         const embedOptions = convertToEmbedCallOptions(inputs);
         logger.trace({ requestId, options: embedOptions }, "[embeddings] AI SDK options");
+        addSpanEvent("hebo.options.prepared");
         // Build middleware chain (model -> forward params -> provider).
         const embeddingModelWithMiddleware = wrapEmbeddingModel({
             model: embeddingModel,
             middleware: modelMiddlewareMatcher.forEmbedding(ctx.resolvedModelId, embeddingModel.provider),
         });
         // Execute request.
-        markPerf(ctx.request, "aiSdkStart");
+        addSpanEvent("hebo.ai-sdk.started");
         const result = await embedMany({
             model: embeddingModelWithMiddleware,
             headers: prepareForwardHeaders(ctx.request),
-            experimental_telemetry: toAiSdkTelemetry(config, ctx.operation),
             abortSignal: ctx.request.signal,
             ...embedOptions,
         });
-        markPerf(ctx.request, "aiSdkEnd");
         logger.trace({ requestId, result }, "[embeddings] AI SDK result");
+        addSpanEvent("hebo.ai-sdk.completed");
         ctx.result = toEmbeddings(result, ctx.modelId);
-        return (await hooks?.after?.(ctx)) ?? ctx.result;
+        addSpanEvent("hebo.result.transformed");
+        if (hooks?.after) {
+            ctx.result = (await hooks.after(ctx)) ?? ctx.result;
+            addSpanEvent("hebo.hooks.after.completed");
+        }
+        return ctx.result;
     };
     return { handler: winterCgHandler(handler, config) };
 };

package/dist/endpoints/models/handler.js

@@ -8,6 +8,7 @@ export const models = (config) => {
         if (!request || request.method !== "GET") {
             throw new GatewayError("Method Not Allowed", 405);
         }
+        ctx.operation = "models";
         const rawId = request.url.split("/models/", 2)[1]?.split("?", 1)[0];
         if (!rawId) {
             return toModels(ctx.models);

package/dist/gateway.js

@@ -2,11 +2,15 @@ import { parseConfig } from "./config";
 import { chatCompletions } from "./endpoints/chat-completions/handler";
 import { embeddings } from "./endpoints/embeddings/handler";
 import { models } from "./endpoints/models/handler";
+import { GatewayError } from "./errors/gateway";
+import { winterCgHandler } from "./lifecycle";
 import { logger } from "./logger";
-import { getRequestMeta, getResponseMeta } from "./telemetry/utils";
 export function gateway(config) {
     const basePath = (config.basePath ?? "").replace(/\/+$/, "");
     const parsedConfig = parseConfig(config);
+    const notFoundHandler = winterCgHandler(() => {
+        throw new GatewayError("Not Found", 404);
+    }, parsedConfig);
     const routes = {
         ["/chat/completions"]: chatCompletions(parsedConfig),
         ["/embeddings"]: embeddings(parsedConfig),
@@ -14,23 +18,17 @@ export function gateway(config) {
     };
     const routeEntries = Object.entries(routes);
     const handler = (req, state) => {
-        const start = performance.now();
         let pathname = new URL(req.url).pathname;
         if (basePath && pathname.startsWith(basePath)) {
             pathname = pathname.slice(basePath.length);
         }
+        logger.debug(`[gateway] ${req.method} ${pathname}`);
         for (const [route, endpoint] of routeEntries) {
             if (pathname === route || pathname.startsWith(route + "/")) {
                 return endpoint.handler(req, state);
             }
         }
-        const response = new Response("Not Found", { status: 404 });
-        const durationMs = +(performance.now() - start).toFixed(2);
-        logger.warn({
-            req: getRequestMeta(req),
-            res: { ...getResponseMeta(response), durationMs, ttfbMs: durationMs },
-        }, `${req.method} ${pathname} 404`);
-        return Promise.resolve(response);
+        return notFoundHandler(req, state);
     };
     return { handler, routes };
 }

package/dist/lifecycle.js

@@ -1,7 +1,8 @@
 import { parseConfig } from "./config";
 import { toOpenAIErrorResponse } from "./errors/openai";
-import { isLoggerDisabled, logger } from "./logger";
-import { withAccessLog } from "./telemetry/access-log";
+import { logger } from "./logger";
+import { withOtel } from "./telemetry/otel";
+import { addSpanEvent } from "./telemetry/span";
 import { resolveRequestId } from "./utils/headers";
 import { maybeApplyRequestPatch, prepareRequestHeaders } from "./utils/request";
 import { prepareResponseInit, toResponse } from "./utils/response";
@@ -9,19 +10,26 @@ export const winterCgHandler = (run, config) => {
     const parsedConfig = parseConfig(config);
     const core = async (ctx) => {
         try {
-            const onRequest = await parsedConfig.hooks?.onRequest?.(ctx);
-            if (onRequest) {
-                if (onRequest instanceof Response) {
-                    ctx.response = onRequest;
-                    return;
+            if (parsedConfig.hooks?.onRequest) {
+                const onRequest = await parsedConfig.hooks.onRequest(ctx);
+                addSpanEvent("hebo.hooks.on_request.completed");
+                if (onRequest) {
+                    if (onRequest instanceof Response) {
+                        ctx.response = onRequest;
+                        return;
+                    }
+                    ctx.request = maybeApplyRequestPatch(ctx.request, onRequest);
                 }
-                ctx.request = maybeApplyRequestPatch(ctx.request, onRequest);
             }
             ctx.result = (await run(ctx));
             ctx.response = toResponse(ctx.result, prepareResponseInit(ctx.request));
-            const onResponse = await parsedConfig.hooks?.onResponse?.(ctx);
-            if (onResponse)
-                ctx.response = onResponse;
+            if (parsedConfig.hooks?.onResponse) {
+                const onResponse = await parsedConfig.hooks.onResponse(ctx);
+                addSpanEvent("hebo.hooks.on_response.completed");
+                if (onResponse) {
+                    ctx.response = onResponse;
+                }
+            }
         }
         catch (error) {
             logger.error({
@@ -31,7 +39,7 @@ export const winterCgHandler = (run, config) => {
             ctx.response = toOpenAIErrorResponse(error, prepareResponseInit(ctx.request));
         }
     };
-    const handler = isLoggerDisabled(parsedConfig.logger) ? core : withAccessLog(core);
+    const handler = parsedConfig.telemetry?.enabled ? withOtel(core, parsedConfig) : core;
     return async (request, state) => {
         const ctx = {
             request,

package/dist/middleware/matcher.js

@@ -1,4 +1,5 @@
 import { logger } from "../logger";
+import { addSpanEvent } from "../telemetry/span";
 import { forwardParamsEmbeddingMiddleware, forwardParamsMiddleware } from "./common";
 class SimpleMatcher {
     rules = [];
@@ -82,6 +83,7 @@ class ModelMiddlewareMatcher {
                     break;
             }
             logger.warn(`[middleware] cache eviction`);
+            addSpanEvent("hebo.middelware.cache.evicted");
         }
         this.cache.set(key, out);
         return out;

package/dist/providers/registry.d.ts

@@ -5,7 +5,7 @@ export declare const resolveProvider: (args: {
     providers: ProviderRegistry;
     models: ModelCatalog;
     modelId: ModelId;
-    operation: "text" | "embeddings";
+    operation: "chat" | "embeddings";
 }) => ProviderV3;
 export type CanonicalIdsOptions = {
     mapping?: Partial<Record<ModelId, string>>;

package/dist/providers/registry.js

@@ -7,7 +7,8 @@ export const resolveProvider = (args) => {
     if (!catalogModel) {
         throw new GatewayError(`Model '${modelId}' not found in catalog`, 422, "MODEL_NOT_FOUND");
     }
-    if (catalogModel.modalities && !catalogModel.modalities.output.includes(operation)) {
+    const modality = operation === "embeddings" ? "embeddings" : "text";
+    if (catalogModel.modalities && !catalogModel.modalities.output.includes(modality)) {
         throw new GatewayError(`Model '${modelId}' does not support '${operation}' output`, 422, "MODEL_UNSUPPORTED_OPERATION");
     }
     // FUTURE: implement fallback logic [e.g. runtime config invalid]

package/dist/telemetry/fetch.js

@@ -1,12 +1,10 @@
-import { markPerf, markPerfOnce } from "./perf";
+import { SpanKind } from "@opentelemetry/api";
+import { withSpan } from "./span";
 const ORIGINAL_FETCH_KEY = Symbol.for("@hebo/fetch/original-fetch");
 const g = globalThis;
-const perfFetch = async (input, init) => {
+const perfFetch = (input, init) => {
     const original = g[ORIGINAL_FETCH_KEY];
-    markPerfOnce(init ?? input, "fetchStart");
-    const response = await original(input, init);
-    markPerf(init ?? input, "fetchEnd");
-    return response;
+    return withSpan("fetch", () => original(input, init), { kind: SpanKind.CLIENT });
 };
 export const initFetch = () => {
     if (g[ORIGINAL_FETCH_KEY])

package/dist/telemetry/otel.d.ts

@@ -1,7 +1,2 @@
-import type { Tracer } from "@opentelemetry/api";
-import type { GatewayConfig } from "../types";
-export declare const toAiSdkTelemetry: (config: GatewayConfig, functionId: string) => {
-    isEnabled: boolean;
-    tracer?: Tracer;
-    functionId?: string;
-};
+import type { GatewayConfigParsed, GatewayContext } from "../types";
+export declare const withOtel: (run: (ctx: GatewayContext) => Promise<void>, config: GatewayConfigParsed) => (ctx: GatewayContext) => Promise<void>;

package/dist/telemetry/otel.js

@@ -1,5 +1,46 @@
-export const toAiSdkTelemetry = (config, functionId) => ({
-    isEnabled: config.telemetry?.enabled ?? false,
-    tracer: config.telemetry?.tracer,
-    functionId,
-});
+import { SpanStatusCode } from "@opentelemetry/api";
+import { initFetch } from "./fetch";
+import { startSpan } from "./span";
+import { instrumentStream } from "./stream";
+import { getAIAttributes, getBaggageAttributes, getRequestAttributes, getResponseAttributes, } from "./utils";
+export const withOtel = (run, config) => async (ctx) => {
+    const requestStart = performance.now();
+    const aiSpan = startSpan(ctx.request.url, undefined, config.telemetry?.tracer);
+    initFetch();
+    const endAiSpan = (status, stats) => {
+        const attrs = getAIAttributes(ctx.body, ctx.streamResult ?? ctx.result, config.telemetry?.attributes, ctx.resolvedProviderId);
+        attrs["gen_ai.server.request.duration"] = Number(((performance.now() - requestStart) / 1000).toFixed(4));
+        if (!aiSpan.isExisting) {
+            Object.assign(attrs, getRequestAttributes(ctx.request, config.telemetry?.attributes), getResponseAttributes(ctx.response, config.telemetry?.attributes));
+        }
+        Object.assign(attrs, getBaggageAttributes(ctx.request));
+        if (config.telemetry?.attributes === "full") {
+            attrs["http.request.body.size"] = Number(ctx.request.headers.get("content-length") || 0);
+            attrs["http.response.body.size"] =
+                stats?.bytes ?? Number(attrs["http.response.header.content-length"] || 0);
+        }
+        attrs["http.response.status_code_effective"] = status;
+        aiSpan.setStatus({ code: status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.OK });
+        if (ctx.operation && ctx.modelId) {
+            aiSpan.updateName(`${ctx.operation} ${ctx.modelId}`);
+        }
+        else if (ctx.operation) {
+            aiSpan.updateName(`${ctx.operation}`);
+        }
+        aiSpan.setAttributes(attrs);
+        aiSpan.finish();
+    };
+    await aiSpan.runWithContext(() => run(ctx));
+    if (ctx.response.body instanceof ReadableStream) {
+        const instrumented = instrumentStream(ctx.response.body, {
+            onComplete: (status, params) => endAiSpan(status, params),
+        }, ctx.request.signal);
+        ctx.response = new Response(instrumented, {
+            status: ctx.response.status,
+            statusText: ctx.response.statusText,
+            headers: ctx.response.headers,
+        });
+        return;
+    }
+    endAiSpan(ctx.response.status);
+};

package/dist/telemetry/span.d.ts

@@ -0,0 +1,9 @@
+import type { Attributes, Span, SpanOptions, Tracer } from "@opentelemetry/api";
+export declare const startSpan: (name: string, options?: SpanOptions, customTracer?: Tracer) => Span & {
+    runWithContext: <T>(fn: () => Promise<T> | T) => T | Promise<T>;
+    recordError: (_error: unknown) => void;
+    finish: () => void;
+    isExisting: boolean;
+};
+export declare const withSpan: <T>(name: string, run: () => Promise<T> | T, options?: SpanOptions) => Promise<T>;
+export declare const addSpanEvent: (name: string, attributes?: Attributes) => void;

package/dist/telemetry/span.js

@@ -0,0 +1,64 @@
+import { INVALID_SPAN_CONTEXT, SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+const DEFAULT_TRACER_NAME = "@hebo-ai/gateway";
+const mem = () => process?.memoryUsage?.();
+const toError = (error) => (error instanceof Error ? error : new Error(String(error)));
+const maybeSetDynamicAttributes = (span, getAttributes) => {
+    const attrs = getAttributes();
+    if (Object.keys(attrs).length === 0)
+        return;
+    span.setAttributes(attrs);
+};
+const getMemoryAttributes = () => {
+    const memory = mem();
+    if (!memory)
+        return {};
+    return {
+        "process.memory.usage": memory.rss,
+        "process.memory.heap.used": memory.heapUsed,
+        "process.memory.heap.total": memory.heapTotal,
+    };
+};
+const NOOP_SPAN = {
+    runWithContext: (fn) => fn(),
+    recordError: (_error) => { },
+    finish: () => { },
+    isExisting: true,
+};
+export const startSpan = (name, options, customTracer) => {
+    const tracer = customTracer ?? trace.getTracer(DEFAULT_TRACER_NAME);
+    const parentContext = context.active();
+    const activeSpan = trace.getActiveSpan();
+    const span = tracer.startSpan(name, { kind: activeSpan ? SpanKind.INTERNAL : SpanKind.SERVER, ...options }, parentContext);
+    if (!span.isRecording()) {
+        return Object.assign(trace.wrapSpanContext(INVALID_SPAN_CONTEXT), NOOP_SPAN);
+    }
+    maybeSetDynamicAttributes(span, getMemoryAttributes);
+    const runWithContext = (fn) => context.with(trace.setSpan(parentContext, span), fn);
+    const recordError = (error) => {
+        const err = toError(error);
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+    };
+    const finish = () => {
+        maybeSetDynamicAttributes(span, getMemoryAttributes);
+        span.end();
+    };
+    return Object.assign(span, { runWithContext, recordError, finish, isExisting: !!activeSpan });
+};
+export const withSpan = async (name, run, options) => {
+    const started = startSpan(name, options);
+    try {
+        return await started.runWithContext(run);
+    }
+    catch (error) {
+        started.recordError(error);
+        throw error;
+    }
+    finally {
+        started.finish();
+    }
+};
+export const addSpanEvent = (name, attributes) => {
+    const allAttributes = Object.assign(attributes ?? {}, getMemoryAttributes());
+    trace.getActiveSpan()?.addEvent(name, allAttributes);
+};

package/dist/telemetry/utils.d.ts

@@ -1,4 +1,4 @@
-import type { GatewayContext } from "../types";
-export declare const getRequestMeta: (request?: Request) => Record<string, unknown>;
-export declare const getAIMeta: (context?: Partial<GatewayContext>) => Record<string, unknown>;
-export declare const getResponseMeta: (result?: Response) => Record<string, unknown>;
+export declare const getRequestAttributes: (request?: Request, attributesLevel?: string) => {};
+export declare const getAIAttributes: (body?: object, result?: object, attributesLevel?: string, providerName?: string) => {};
+export declare const getResponseAttributes: (response?: Response, attributesLevel?: string) => {};
+export declare const getBaggageAttributes: (request?: Request) => Record<string, string>;