weflayr 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# Weflayr JS SDK
+
+Drop-in instrumented wrapper for the OpenAI Node.js SDK — add telemetry to your LLM calls in two lines.
+
+```
+your code  →  instrument(openai)  →  OpenAI SDK  →  OpenAI API
+                     ↓
+            Weflayr Intake API
+            (before · after · error events, fire-and-forget)
+```
+
+---
+
+## Installation
+
+```bash
+npm install weflayr
+```
+
+Requires Node.js 18+ and `openai>=4.0.0`.
+
+---
+
+## Implementation steps
+
+### 1. Get your credentials
+
+Sign in at [weflayr.com](https://weflayr.com), create a **Flare**, and copy your `client_id` and `client_secret`.
+
+### 2. Set environment variables
+
+```bash
+WEFLAYR_INTAKE_URL=https://api.weflayr.com
+WEFLAYR_CLIENT_ID=<your-client-id>
+WEFLAYR_CLIENT_SECRET=<your-client-secret>
+```
+
+Or add them to a `.env` file — the SDK uses `dotenv` automatically.
+
+### 3. Initialize Weflayr at startup
+
+Call `setupWeflayr()` once, before any LLM calls. This registers the OpenTelemetry trace provider that powers telemetry.
+
+```js
+import { setupWeflayr } from "weflayr/openai";
+
+await setupWeflayr();
+```
+
+### 4. Instrument your OpenAI client
+
+Wrap your existing client with `instrument()`. The returned client is a drop-in replacement.
+
+```js
+import OpenAI from "openai";
+import { instrument } from "weflayr/openai";
+
+const openai = instrument(new OpenAI());
+```
+
+### 5. Use it normally
+
+No other changes needed.
+
+```js
+const response = await openai.chat.completions.create({
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "Hello!" }],
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### 6. (Optional) Add tags
+
+Pass a `tags` object in any call params to attach metadata — useful for slicing analytics by feature, user, or environment.
+
+```js
+const response = await openai.chat.completions.create({
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "Summarize this." }],
+    tags: { feature: "summarization", userId: "u_123", env: "production" },
+});
+```
+
+Tags are stripped before the request reaches OpenAI — they never affect the API call.
+
+---
+
+## Covered endpoints
+
+All token-consuming OpenAI endpoints are instrumented with precise extractors. Any endpoint not in the list below is wrapped automatically by a fallback proxy.
+
+| Endpoint | Fields tracked |
+|---|---|
+| `chat.completions.create` | `model`, `message_count`, `prompt_tokens`, `completion_tokens` |
+| `completions.create` (legacy) | `model`, `prompt_length`, `prompt_tokens`, `completion_tokens` |
+| `embeddings.create` | `model`, `input_count`, `prompt_tokens`, `total_tokens` |
+| `responses.create` | `model`, `input_count`, `input_tokens`, `output_tokens`, `cached_tokens` |
+| `audio.speech.create` (TTS) | `model`, `voice`, `char_count` |
+| `audio.transcriptions.create` (STT) | `model`, `language`, token/duration usage |
+| `audio.translations.create` | `model`, token/duration usage |
+
+Any other method on the client is wrapped by a fallback proxy and tracked under its dotted path (e.g. `images.generate`).
+
+---
+
+## Telemetry events
+
+Each call emits up to two events to your intake API:
+
+| Event | When | Key fields |
+|---|---|---|
+| `<endpoint>.before` | Before the call | `model`, call-specific params, `tags` |
+| `<endpoint>.after` | On success | all `.before` fields + `elapsed_ms` + token usage |
+| `<endpoint>.error` | On failure | all `.before` fields + `elapsed_ms` + `error_type`, `error_message` |
+
+Events are sent **fire-and-forget** — they never block your code or throw.
+
+By default, message content and prompt text are stripped before sending. Fields omitted: `messages`, `prompt`, `response_content`.
+
+---
+
+## Optional: forward traces to your own collector
+
+Set `WEFLAYR_COLLECTOR_ENDPOINT` to also send OTLP traces to a collector of your choice (e.g. Jaeger, Grafana Tempo):
+
+```bash
+WEFLAYR_COLLECTOR_ENDPOINT=http://localhost:4318/v1/traces
+```
+
+---
+
+## Full example
+
+```js
+import OpenAI from "openai";
+import { setupWeflayr, instrument } from "weflayr/openai";
+
+await setupWeflayr();
+
+const openai = instrument(new OpenAI());
+
+const response = await openai.chat.completions.create({
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "What is 2 + 2?" }],
+    tags: { feature: "math", env: "production" },
+});
+
+console.log(response.choices[0].message.content);
+```
+
+---
+
+## License
+
+[Elastic License 2.0](LICENSE) — free to use, modifications and redistribution not permitted.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "weflayr",
+  "version": "0.1.0",
+  "description": "Drop-in instrumented wrappers for AI clients with zero-overhead telemetry",
+  "type": "module",
+  "exports": {
+    ".": "./src/weflayr.js",
+    "./openai": "./src/openai.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --test tests/weflayr.test.js tests/openai.test.js",
+    "prepublishOnly": "node --input-type=module --eval \"import './src/weflayr.js'\" 2>/dev/null; echo 'pre-publish check passed'"
+  },
+  "keywords": [
+    "llm",
+    "telemetry",
+    "observability",
+    "openai",
+    "instrumentation",
+    "tracing",
+    "ai",
+    "otel",
+    "opentelemetry"
+  ],
+  "author": "Weflayr <contact@weflayr.com>",
+  "license": "Elastic-2.0",
+  "homepage": "https://weflayr.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WeFlayr/public-mirror-js-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/WeFlayr/public-mirror-js-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "dotenv": "^16.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0"
+  },
+  "optionalDependencies": {
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0"
+  },
+  "peerDependencies": {
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
+  }
+}

package/src/openai.js

@@ -0,0 +1,114 @@
+import { trace } from "@opentelemetry/api";
+import { setupWeflayr, makeWrapper, deepFallbackProxy } from "./weflayr.js";
+
+export { setupWeflayr };
+
+// ── STT usage helper ──────────────────────────────────────────────────────────
+function sttUsage(r) {
+  const usage = r?.usage;
+  if (!usage) return {};
+  if (usage.type === "tokens") {
+    return {
+      usage_type: "tokens",
+      input_tokens: usage.input_tokens,
+      audio_tokens: usage.input_token_details?.audio_tokens,
+    };
+  }
+  if (usage.type === "duration") {
+    return { usage_type: "duration", duration_seconds: usage.seconds };
+  }
+  return {};
+}
+
+// ── Route map ─────────────────────────────────────────────────────────────────
+// Each entry defines one instrumented OpenAI method:
+//   name    — event_type prefix sent to Weflayr
+//   get     — retrieves the original bound method from the client
+//   set     — patches the method back on the client
+//   before  — extracts fields from call params for the .before event
+//   after   — extracts fields from the response for the .after event
+
+const ROUTES = [
+  // client.chat.completions.create
+  {
+    name: "chat.completions.create",
+    get: (c) => c.chat.completions.create.bind(c.chat.completions),
+    set: (c, fn) => { c.chat.completions.create = fn; },
+    before: (p) => ({ model: p.model, message_count: p.messages?.length ?? 0 }),
+    after:  (r) => ({ prompt_tokens: r.usage?.prompt_tokens, completion_tokens: r.usage?.completion_tokens }),
+  },
+
+  // client.completions.create  (legacy text completions)
+  {
+    name: "completions.create",
+    get: (c) => c.completions.create.bind(c.completions),
+    set: (c, fn) => { c.completions.create = fn; },
+    before: (p) => ({ model: p.model, prompt_length: typeof p.prompt === "string" ? p.prompt.length : (p.prompt?.length ?? 0) }),
+    after:  (r) => ({ prompt_tokens: r.usage?.prompt_tokens, completion_tokens: r.usage?.completion_tokens }),
+  },
+
+  // client.embeddings.create
+  {
+    name: "embeddings.create",
+    get: (c) => c.embeddings.create.bind(c.embeddings),
+    set: (c, fn) => { c.embeddings.create = fn; },
+    before: (p) => ({ model: p.model, input_count: Array.isArray(p.input) ? p.input.length : 1 }),
+    after:  (r) => ({ prompt_tokens: r.usage?.prompt_tokens, total_tokens: r.usage?.total_tokens }),
+  },
+
+  // client.responses.create  (Responses API)
+  {
+    name: "responses.create",
+    get: (c) => c.responses.create.bind(c.responses),
+    set: (c, fn) => { c.responses.create = fn; },
+    before: (p) => ({ model: p.model, input_count: Array.isArray(p.input) ? p.input.length : 1 }),
+    after:  (r) => ({
+      input_tokens:   r.usage?.input_tokens,
+      output_tokens:  r.usage?.output_tokens,
+      cached_tokens:  r.usage?.input_tokens_details?.cached_tokens,
+    }),
+  },
+
+  // client.audio.speech.create  (TTS — billed by char count)
+  {
+    name: "audio.speech.create",
+    get: (c) => c.audio.speech.create.bind(c.audio.speech),
+    set: (c, fn) => { c.audio.speech.create = fn; },
+    before: (p) => ({ model: p.model, voice: p.voice, char_count: p.input?.length ?? 0 }),
+    after:  ()  => ({}),
+  },
+
+  // client.audio.transcriptions.create  (STT)
+  {
+    name: "audio.transcriptions.create",
+    get: (c) => c.audio.transcriptions.create.bind(c.audio.transcriptions),
+    set: (c, fn) => { c.audio.transcriptions.create = fn; },
+    before: (p) => ({ model: p.model, language: p.language }),
+    after:  (r) => sttUsage(r),
+  },
+
+  // client.audio.translations.create  (whisper-1 only — billed by duration)
+  {
+    name: "audio.translations.create",
+    get: (c) => c.audio.translations.create.bind(c.audio.translations),
+    set: (c, fn) => { c.audio.translations.create = fn; },
+    before: (p) => ({ model: p.model }),
+    after:  (r) => sttUsage(r),
+  },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Paths already covered by ROUTES — the fallback Proxy skips these.
+const PATCHED_PATHS = new Set(ROUTES.map((r) => r.name));
+
+export function instrument(client) {
+  const tracer = trace.getTracer("weflayr-openai");
+
+  // 1. Patch all explicitly defined routes with their precise extractors.
+  for (const route of ROUTES) {
+    route.set(client, makeWrapper(route.get(client), route, tracer));
+  }
+
+  // 2. Wrap the whole client in a Proxy that handles anything not in ROUTES.
+  return deepFallbackProxy(client, tracer, PATCHED_PATHS);
+}

package/src/weflayr.js

@@ -0,0 +1,228 @@
+import "dotenv/config";
+import { SpanStatusCode } from "@opentelemetry/api";
+import {
+  BasicTracerProvider,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { randomUUID } from "node:crypto";
+
+// ── Weflayr Intake API ────────────────────────────────────────────────────────
+export const INTAKE_URL = (
+  process.env.WEFLAYR_INTAKE_URL ?? "https://api.weflayr.com"
+).replace(/\/$/, "");
+export const CLIENT_ID = process.env.WEFLAYR_CLIENT_ID ?? "";
+export const CLIENT_SECRET = process.env.WEFLAYR_CLIENT_SECRET ?? "";
+
+// ── INFO TO SEND ──────────────────────────────────────────────────────────────
+// Global tags attached to every event. Populate via env vars or hardcode values.
+// Per-call tags can also be passed directly in the create() params (see main.js).
+export const GLOBAL_TAGS = Object.fromEntries(
+  Object.entries({
+    env: process.env.WEFLAYR_TAG_ENV,
+    feature: process.env.WEFLAYR_TAG_FEATURE,
+    version: process.env.WEFLAYR_TAG_VERSION,
+  }).filter(([, v]) => v != null)
+);
+
+// ── INFO TO HIDE ──────────────────────────────────────────────────────────────
+// Keys stripped from every Weflayr event before it is sent.
+// Prevents PII or sensitive content from leaving the process.
+export const HIDDEN_FIELDS = new Set([
+  "messages",         // prompt message content (chat completions)
+  "prompt",           // prompt text (legacy completions)
+  "response_content", // completion response text
+]);
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function _post(payload) {
+  if (!CLIENT_ID || !CLIENT_SECRET) return;
+
+  for (const key of HIDDEN_FIELDS) delete payload[key];
+  for (const [k, v] of Object.entries(payload)) {
+    if (v == null) delete payload[k];
+  }
+
+  try {
+    await fetch(`${INTAKE_URL}/${CLIENT_ID}/`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${CLIENT_SECRET}`,
+      },
+      body: JSON.stringify(payload),
+    });
+  } catch {
+    // fire-and-forget — never throws
+  }
+}
+
+export class WeflayrSpanProcessor {
+  onStart(span) {
+    const a = span.attributes;
+    const before = JSON.parse(a["weflayr.before"] ?? "{}");
+    const tags = JSON.parse(a["weflayr.tags"] ?? "{}");
+    _post({
+      event_id: a["weflayr.event_id"],
+      event_type: `${span.name}.before`,
+      ...before,
+      tags: Object.keys(tags).length ? tags : undefined,
+    });
+  }
+
+  onEnd(span) {
+    const [ss, sns] = span.startTime;
+    const [es, ens] = span.endTime;
+    const elapsed_ms = Math.round((es - ss) * 1000 + (ens - sns) / 1_000_000);
+
+    const isError = span.status.code === SpanStatusCode.ERROR;
+    const a = span.attributes;
+    const before = JSON.parse(a["weflayr.before"] ?? "{}");
+    const after = JSON.parse(a["weflayr.after"] ?? "{}");
+    const tags = JSON.parse(a["weflayr.tags"] ?? "{}");
+
+    _post({
+      event_id: a["weflayr.event_id"],
+      event_type: `${span.name}.${isError ? "error" : "after"}`,
+      ...before,
+      ...after,
+      elapsed_ms,
+      tags: Object.keys(tags).length ? tags : undefined,
+      ...(isError
+        ? { error_type: a["error.type"], error_message: a["error.message"] }
+        : {}),
+    });
+  }
+
+  forceFlush() { return Promise.resolve(); }
+  shutdown()   { return Promise.resolve(); }
+}
+
+export async function setupWeflayr() {
+  // Direct path: always send to the Weflayr Intake API
+  const spanProcessors = [new WeflayrSpanProcessor()];
+
+  // Optional collector path: also forward OTLP traces to your own collector.
+  // Set WEFLAYR_COLLECTOR_ENDPOINT in .env to enable (e.g. http://localhost:4318/v1/traces).
+  if (process.env.WEFLAYR_COLLECTOR_ENDPOINT) {
+    const { OTLPTraceExporter } = await import(
+      "@opentelemetry/exporter-trace-otlp-http"
+    );
+    spanProcessors.push(
+      new SimpleSpanProcessor(
+        new OTLPTraceExporter({ url: process.env.WEFLAYR_COLLECTOR_ENDPOINT })
+      )
+    );
+  }
+
+  new BasicTracerProvider({ spanProcessors }).register();
+}
+
+export function makeWrapper(original, route, tracer) {
+  return async function ({ tags: callTags, ...params }) {
+    const tags = { ...GLOBAL_TAGS, ...callTags };
+    const span = tracer.startSpan(route.name, {
+      attributes: {
+        "weflayr.event_id": randomUUID(),
+        "weflayr.before":   JSON.stringify(route.before(params)),
+        "weflayr.tags":     JSON.stringify(tags),
+      },
+    });
+
+    try {
+      const response = await original(params);
+      span.setAttribute("weflayr.after", JSON.stringify(route.after(response)));
+      span.setStatus({ code: SpanStatusCode.OK });
+      return response;
+    } catch (err) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+      span.setAttribute("error.type", err.constructor.name);
+      span.setAttribute("error.message", err.message);
+      throw err;
+    } finally {
+      span.end();
+    }
+  };
+}
+
+export function makeFallbackWrapper(fn, target, name, tracer) {
+  return function (...args) {
+    let callArgs = args;
+    let tags = GLOBAL_TAGS;
+
+    // If the first argument is a plain params object, extract `tags` from it.
+    if (args[0] !== null && typeof args[0] === "object" && !Array.isArray(args[0])) {
+      const { tags: callTags, ...rest } = args[0];
+      callArgs = [rest, ...args.slice(1)];
+      tags = { ...GLOBAL_TAGS, ...callTags };
+    }
+
+    const before = { model: callArgs[0]?.model };
+    const span = tracer.startSpan(name, {
+      attributes: {
+        "weflayr.event_id": randomUUID(),
+        "weflayr.before":   JSON.stringify(before),
+        "weflayr.tags":     JSON.stringify(tags),
+      },
+    });
+
+    let result;
+    try {
+      result = fn.apply(target, callArgs);
+    } catch (err) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+      span.setAttribute("error.type", err.constructor.name);
+      span.setAttribute("error.message", err.message);
+      span.end();
+      throw err;
+    }
+
+    // Handle both sync and async return values.
+    if (result && typeof result.then === "function") {
+      return result.then(
+        (response) => {
+          span.setAttribute("weflayr.after", "{}");
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          return response;
+        },
+        (err) => {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+          span.setAttribute("error.type", err.constructor.name);
+          span.setAttribute("error.message", err.message);
+          span.end();
+          throw err;
+        }
+      );
+    }
+
+    span.setAttribute("weflayr.after", "{}");
+    span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+    return result;
+  };
+}
+
+// Recursively wraps every function on `obj` that is not already covered by patchedPaths.
+// `path` tracks the dotted property path (e.g. "images.generate").
+export function deepFallbackProxy(obj, tracer, patchedPaths, path = "") {
+  return new Proxy(obj, {
+    get(target, prop) {
+      if (typeof prop !== "string") return Reflect.get(target, prop);
+
+      const val = Reflect.get(target, prop);
+      const fullPath = path ? `${path}.${prop}` : prop;
+
+      if (typeof val === "function") {
+        // Already patched by explicit routes — return the existing wrapper as-is.
+        if (patchedPaths.has(fullPath)) return val;
+        return makeFallbackWrapper(val, target, fullPath, tracer);
+      }
+
+      if (val !== null && typeof val === "object") {
+        return deepFallbackProxy(val, tracer, patchedPaths, fullPath);
+      }
+
+      return val;
+    },
+  });
+}