@lmnr-ai/lmnr 0.4.6 → 0.4.7-alpha

package/README.md

@@ -24,7 +24,7 @@ This will automatically instrument most of the LLM, Vector DB, and related
 calls with OpenTelemetry-compatible instrumentation.
 
 We rely on the amazing [OpenLLMetry](https://github.com/traceloop/openllmetry), open-source package
-by TraceLoop, to achieve that.
+by TraceLoop, to achieve that. Also this package uses Traceloop's [Openllmetry JS library](https://github.com/traceloop/openllmetry-js).
 
 ## Instrumentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lmnr-ai/lmnr",
-  "version": "0.4.6",
+  "version": "0.4.7-alpha",
   "description": "TypeScript SDK for Laminar AI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,18 +21,52 @@
   },
   "homepage": "https://github.com/lmnr-ai/lmnr-ts#README",
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.27.3",
+    "@aws-sdk/client-bedrock-runtime": "^3.649.0",
+    "@azure/openai": "2.0.0-beta.2",
+    "@google-cloud/aiplatform": "^3.29.0",
+    "@google-cloud/vertexai": "^1.7.0",
+    "@langchain/core": "^0.2.32",
+    "@pinecone-database/pinecone": "^3.0.2",
+    "@qdrant/js-client-rest": "^1.11.0",
     "@types/node": "^22.5.4",
     "@types/uuid": "^10.0.0",
     "bufferutil": "^4.0.8",
+    "chromadb": "^1.8.1",
+    "cohere-ai": "^7.13.0",
+    "langchain": "^0.2.18",
+    "llamaindex": "^0.5.23",
+    "openai": "^4.58.2",
+    "runnables": "link:@langchain/core/runnables",
     "tsup": "^8.2.4",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "vectorstores": "link:@langchain/core/vectorstores"
   },
   "dependencies": {
     "@grpc/grpc-js": "^1.11.2",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.26.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.53.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.53.0",
+    "@opentelemetry/instrumentation": "^0.53.0",
+    "@opentelemetry/resources": "^1.26.0",
+    "@opentelemetry/sdk-node": "^0.53.0",
+    "@opentelemetry/sdk-trace-base": "^1.26.0",
+    "@opentelemetry/sdk-trace-node": "^1.26.0",
+    "@opentelemetry/semantic-conventions": "^1.27.0",
     "@traceloop/ai-semantic-conventions": "^0.11.0",
-    "@traceloop/node-server-sdk": "^0.11.1",
+    "@traceloop/instrumentation-anthropic": "^0.11.1",
+    "@traceloop/instrumentation-azure": "^0.11.1",
+    "@traceloop/instrumentation-bedrock": "^0.11.1",
+    "@traceloop/instrumentation-chromadb": "^0.11.1",
+    "@traceloop/instrumentation-cohere": "^0.11.1",
+    "@traceloop/instrumentation-langchain": "^0.11.1",
+    "@traceloop/instrumentation-llamaindex": "^0.11.1",
+    "@traceloop/instrumentation-openai": "^0.11.1",
+    "@traceloop/instrumentation-pinecone": "^0.11.1",
+    "@traceloop/instrumentation-qdrant": "^0.11.1",
+    "@traceloop/instrumentation-vertexai": "^0.11.1",
+    "posthog-node": "^4.2.0",
     "uuid": "^10.0.0"
   },
   "scripts": {

package/src/decorators.ts

@@ -1,5 +1,4 @@
-import { withTask } from '@traceloop/node-server-sdk'
-import { Laminar } from './laminar';
+import { withEntity } from './sdk/node-server-sdk'
 
 interface ObserveOptions {
     name?: string;
@@ -32,9 +31,6 @@ export async function observe<A extends unknown[], F extends (...args: A) => Ret
         userId,
     }: ObserveOptions, fn: F, ...args: A): Promise<ReturnType<F>> {
 
-    if (!Laminar.initialized()) {
-        throw new Error('Laminar not initialized. Please call Laminar.initialize(projectApiKey) before using observe.');
-    };
     let associationProperties = {};
     if (sessionId) {
         associationProperties = { ...associationProperties, "session_id": sessionId };
@@ -42,5 +38,6 @@ export async function observe<A extends unknown[], F extends (...args: A) => Ret
     if (userId) {
         associationProperties = { ...associationProperties, "user_id": userId };
     }
-    return await withTask<A, F>({ name: name ?? fn.name, associationProperties }, fn, ...args);
+
+    return await withEntity<A, F>({ name: name ?? fn.name, associationProperties }, fn, undefined, ...args);
 }

package/src/laminar.ts

@@ -1,9 +1,10 @@
 import { PipelineRunResponse, PipelineRunRequest, EvaluationDatapoint, EvaluationStatus } from './types';
 import { Attributes, AttributeValue, context, createContextKey, isSpanContextValid, TimeInput, trace } from '@opentelemetry/api';
-import { InitializeOptions, initialize as traceloopInitialize } from '@traceloop/node-server-sdk'
+import { InitializeOptions, initialize as traceloopInitialize } from './sdk/node-server-sdk'
 import { otelSpanIdToUUID, otelTraceIdToUUID } from './utils';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
 import { Metadata } from '@grpc/grpc-js';
+import { ASSOCIATION_PROPERTIES_KEY } from './sdk/tracing/tracing';
 
 // quick patch to get the traceloop's default tracer, since their 
 // `getTracer` function is not exported.
@@ -37,6 +38,26 @@ export class Laminar {
      * @param baseUrl - Url of Laminar endpoint, or the custom open telemetry ingester.
      * If not specified, defaults to https://api.lmnr.ai:8443. For locally hosted Laminar,
      * default setting must be http://localhost:8001.
+     * @param instrumentModules - List of modules to instrument.
+     * If not specified, all auto-instrumentable modules will be instrumented, which include
+     * LLM calls (OpenAI, Anthropic, etc), Langchain, VectorDB calls (Pinecone, Qdrant, etc).
+     * Pass an empty object {} to disable any kind of automatic instrumentation.
+     * If you only want to auto-instrument specific modules, then pass them in the object.
+     * 
+     * Example:
+     * ```typescript
+     * import { Laminar as L } from '@lmnr-ai/lmnr';
+     * import { OpenAI } from 'openai';
+     * import * as ChainsModule from "langchain/chains";
+     * 
+     * // Initialize Laminar while auto-instrumenting Langchain and OpenAI modules.
+     * L.initialize({ projectApiKey: "<LMNR_PROJECT_API_KEY>", instrumentModules: {
+     *  langchain: {
+     *      chainsModule: ChainsModule
+     *  },
+     *  openAI: OpenAI
+     * } });
+     * ```
      *
      * @throws {Error} - If project API key is not set
      */
@@ -276,7 +297,17 @@ export class Laminar {
         if (userId) {
             associationProperties = { ...associationProperties, "user_id": userId };
         }
-        return context.active().setValue(createContextKey("association_properites"), associationProperties);
+
+        let entityContext = context.active();
+        const currentAssociationProperties = entityContext.getValue(ASSOCIATION_PROPERTIES_KEY);
+        if (associationProperties) {
+            entityContext = entityContext.setValue(
+                ASSOCIATION_PROPERTIES_KEY,
+                { ...(currentAssociationProperties ?? {}), ...associationProperties },
+            );
+        }
+
+        return entityContext;
     }
 
     public static async createEvaluation(name: string) {

package/src/sdk/configuration/index.ts

@@ -0,0 +1,68 @@
+import { InitializeOptions } from "../interfaces";
+import { startTracing } from "../tracing";
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { InitializationError } from "../errors";
+
+export let _configuration: InitializeOptions | undefined;
+
+/**
+ * Initializes the SDK.
+ * Must be called once before any other SDK methods.
+ *
+ * @param options - The options to initialize the SDK. See the {@link InitializeOptions} for details.
+ * @throws {InitializationError} if the configuration is invalid or if failed to fetch feature data.
+ */
+export const initialize = (options: InitializeOptions) => {
+  if (_configuration) {
+    return;
+  }
+
+  if (!options.baseUrl) {
+    options.baseUrl =
+      process.env.LMNR_BASE_URL || "https://api.lmnr.ai:8443";
+  }
+  if (!options.apiKey) {
+    options.apiKey = process.env.LMNR_PROJECT_API_KEY;
+  }
+  if (options.apiKey && typeof options.apiKey !== "string") {
+    throw new InitializationError('"apiKey" must be a string');
+  }
+
+  if (!options.appName) {
+    options.appName = process.env.npm_package_name;
+  }
+
+  _configuration = Object.freeze(options);
+
+  if (options.logLevel) {
+    diag.setLogger(
+      new DiagConsoleLogger(),
+      logLevelToOtelLogLevel(options.logLevel),
+    );
+  }
+
+  if (!options.silenceInitializationMessage) {
+    console.log(
+      `Laminar exporting traces to ${
+        _configuration.exporter ? "a custom exporter" : _configuration.baseUrl
+      }`,
+    );
+  }
+
+  startTracing(_configuration);
+};
+
+const logLevelToOtelLogLevel = (
+  logLevel: "debug" | "info" | "warn" | "error",
+) => {
+  switch (logLevel) {
+    case "debug":
+      return DiagLogLevel.DEBUG;
+    case "info":
+      return DiagLogLevel.INFO;
+    case "warn":
+      return DiagLogLevel.WARN;
+    case "error":
+      return DiagLogLevel.ERROR;
+  }
+};

package/src/sdk/errors/index.ts

@@ -0,0 +1,57 @@
+/**
+ * The severity of an error.
+ */
+export const SEVERITY = {
+  Warning: "Warning",
+  Error: "Error",
+  Critical: "Critical",
+} as const;
+
+export type Severity = (typeof SEVERITY)[keyof typeof SEVERITY];
+
+/**
+ * Base class for all Traceloop errors.
+ */
+export class TraceloopError extends Error {
+  /**
+   * The severity of the error.
+   */
+  severity: Severity;
+  /**
+   * The underlying cause of the error.
+   */
+  underlyingCause?: Error;
+
+  constructor(message: string, severity: Severity = SEVERITY.Error) {
+    super(message);
+    this.severity = severity;
+  }
+}
+
+export class NotInitializedError extends TraceloopError {
+  constructor() {
+    super(
+      `The Traceloop SDK must be initialized by calling the "initialize" function prior to use.`,
+      SEVERITY.Critical,
+    );
+  }
+}
+
+export class InitializationError extends TraceloopError {
+  constructor(message?: string, cause?: Error) {
+    super(message ?? "Failed to initialize Traceloop SDK", SEVERITY.Critical);
+    this.underlyingCause = cause;
+  }
+}
+
+export class ArgumentNotProvidedError extends TraceloopError {
+  constructor(argumentName: string) {
+    super(`The "${argumentName}" argument is required and must be a string.`);
+  }
+}
+
+export class PromptNotFoundError extends TraceloopError {
+  constructor(key: string) {
+    super(`The prompt "${key}" was not found in the registry.`);
+  }
+}

package/src/sdk/interfaces/index.ts

@@ -0,0 +1 @@
+export * from "./initialize-options.interface";

package/src/sdk/interfaces/initialize-options.interface.ts

@@ -0,0 +1,114 @@
+import { SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { TextMapPropagator, ContextManager } from "@opentelemetry/api";
+import type * as openai from "openai";
+import type * as anthropic from "@anthropic-ai/sdk";
+import type * as azure from "@azure/openai";
+import type * as cohere from "cohere-ai";
+import type * as bedrock from "@aws-sdk/client-bedrock-runtime";
+import type * as aiplatform from "@google-cloud/aiplatform";
+import type * as vertexAI from "@google-cloud/vertexai";
+import type * as pinecone from "@pinecone-database/pinecone";
+import type * as ChainsModule from "langchain/chains";
+import type * as AgentsModule from "langchain/agents";
+import type * as ToolsModule from "langchain/tools";
+import type * as RunnableModule from "@langchain/core/runnables";
+import type * as VectorStoreModule from "@langchain/core/vectorstores";
+import type * as llamaindex from "llamaindex";
+import type * as chromadb from "chromadb";
+import type * as qdrant from "@qdrant/js-client-rest";
+
+/**
+ * Options for initializing the Traceloop SDK.
+ */
+export interface InitializeOptions {
+  /**
+   * The app name to be used when reporting traces. Optional.
+   * Defaults to the package name.
+   */
+  appName?: string;
+
+  /**
+   * The API Key for sending traces data. Optional.
+   * Defaults to the TRACELOOP_API_KEY environment variable.
+   */
+  apiKey?: string;
+
+  /**
+   * The OTLP endpoint for sending traces data. Optional.
+   * Defaults to TRACELOOP_BASE_URL environment variable or https://api.traceloop.com/
+   */
+  baseUrl?: string;
+
+  /**
+   * Sends traces and spans without batching, for local developement. Optional.
+   * Defaults to false.
+   */
+  disableBatch?: boolean;
+
+  /**
+   * Defines default log level for SDK and all instrumentations. Optional.
+   * Defaults to error.
+   */
+  logLevel?: "debug" | "info" | "warn" | "error";
+
+  /**
+   * Whether to log prompts, completions and embeddings on traces. Optional.
+   * Defaults to true.
+   */
+  traceContent?: boolean;
+
+  /**
+   * The OpenTelemetry SpanExporter to be used for sending traces data. Optional.
+   * Defaults to the OTLP exporter.
+   */
+  exporter?: SpanExporter;
+
+  /**
+   * The OpenTelemetry SpanProcessor to be used for processing traces data. Optional.
+   * Defaults to the BatchSpanProcessor.
+   */
+  processor?: SpanProcessor;
+
+  /**
+   * The OpenTelemetry Propagator to use. Optional.
+   * Defaults to OpenTelemetry SDK defaults.
+   */
+  propagator?: TextMapPropagator;
+
+  /**
+   * The OpenTelemetry ContextManager to use. Optional.
+   * Defaults to OpenTelemetry SDK defaults.
+   */
+  contextManager?: ContextManager;
+
+  /**
+   * Explicitly specify modules to instrument. Optional.
+   * This is a workaround specific to Next.js, see https://www.traceloop.com/docs/openllmetry/getting-started-nextjs
+   */
+  instrumentModules?: {
+    openAI?: typeof openai.OpenAI;
+    anthropic?: typeof anthropic;
+    azureOpenAI?: typeof azure;
+    cohere?: typeof cohere;
+    bedrock?: typeof bedrock;
+    google_vertexai?: typeof vertexAI;
+    google_aiplatform?: typeof aiplatform;
+    pinecone?: typeof pinecone;
+    langchain?: {
+      chainsModule?: typeof ChainsModule;
+      agentsModule?: typeof AgentsModule;
+      toolsModule?: typeof ToolsModule;
+      runnablesModule?: typeof RunnableModule;
+      vectorStoreModule?: typeof VectorStoreModule;
+    };
+    llamaIndex?: typeof llamaindex;
+    chromadb?: typeof chromadb;
+    qdrant?: typeof qdrant;
+  };
+
+  /**
+   * Whether to silence the initialization message. Optional.
+   * Defaults to false.
+   */
+  silenceInitializationMessage?: boolean;
+}

package/src/sdk/node-server-sdk.ts

@@ -0,0 +1,7 @@
+export * from "./errors";
+export { InitializeOptions } from "./interfaces";
+export { initialize } from "./configuration";
+export { forceFlush } from "./tracing";
+export * from "./tracing/decorators";
+export * from "./tracing/manual";
+export * from "./tracing/association";

package/src/sdk/telemetry/telemetry.ts

@@ -0,0 +1,86 @@
+import * as os from "os";
+import * as fs from "fs";
+import * as path from "path";
+import { v4 as uuid } from "uuid";
+import { PostHog } from "posthog-node";
+const { version } = require('../../../package.json');
+
+export class Telemetry {
+  private static instance: Telemetry;
+
+  private static readonly ANON_ID_PATH = `${os.homedir()}/.cache/lmnr/telemetry_anon_id`;
+  private static readonly UNKNOWN_ANON_ID = "UNKNOWN";
+
+  private telemetryEnabled: boolean;
+  private posthog: PostHog | undefined;
+  private anonId: string | undefined;
+
+  public static getInstance(): Telemetry {
+    if (!Telemetry.instance) {
+      Telemetry.instance = new Telemetry();
+    }
+    return Telemetry.instance;
+  }
+
+  private constructor() {
+    this.telemetryEnabled =
+      !process.env.LMNR_TELEMETRY ||
+      process.env.LMNR_TELEMETRY.toLowerCase() === "true";
+
+    if (this.telemetryEnabled) {
+      this.posthog = new PostHog(
+        "phc_dUMdjfNKf11jcHgtn7juSnT4P1pO0tafsPUWt4PuwG7",
+      );
+    }
+  }
+
+  private getAnonId() {
+    if (this.anonId) {
+      return this.anonId;
+    }
+
+    try {
+      if (!fs.existsSync(Telemetry.ANON_ID_PATH)) {
+        fs.mkdirSync(path.dirname(Telemetry.ANON_ID_PATH), { recursive: true });
+        const anonIdFile = fs.openSync(Telemetry.ANON_ID_PATH, "w");
+        this.anonId = uuid();
+        fs.writeSync(anonIdFile, this.anonId);
+        fs.closeSync(anonIdFile);
+      } else {
+        const anonIdFile = fs.openSync(Telemetry.ANON_ID_PATH, "r");
+        this.anonId = fs.readFileSync(anonIdFile, "utf8");
+        fs.closeSync(anonIdFile);
+      }
+      return this.anonId;
+    } catch (e) {
+      return Telemetry.UNKNOWN_ANON_ID;
+    }
+  }
+
+  private getContext() {
+    return {
+      sdk: "typescript",
+      sdk_version: version,
+    };
+  }
+
+  public capture(event: string, properties?: Record<string, string>) {
+    if (this.telemetryEnabled && this.posthog) {
+      this.posthog.capture({
+        distinctId: this.getAnonId(),
+        event,
+        properties: {
+          ...properties,
+          ...this.getContext(),
+        },
+      });
+      this.posthog.flush();
+    }
+  }
+
+  public logException(error: Error) {
+    if (this.telemetryEnabled) {
+      this.capture("error", { error: error.message, stack: error.stack || "" });
+    }
+  }
+}

package/src/sdk/tracing/association.ts

@@ -0,0 +1,21 @@
+import { context } from "@opentelemetry/api";
+import { ASSOCIATION_PROPERTIES_KEY } from "./tracing";
+
+export function withAssociationProperties<
+  A extends unknown[],
+  F extends (...args: A) => ReturnType<F>,
+>(
+  properties: { [name: string]: string },
+  fn: F,
+  thisArg?: ThisParameterType<F>,
+  ...args: A
+) {
+  if (Object.keys(properties).length === 0) {
+    return fn.apply(thisArg, args);
+  }
+
+  const newContext = context
+    .active()
+    .setValue(ASSOCIATION_PROPERTIES_KEY, properties);
+  return context.with(newContext, fn, thisArg, ...args);
+}

package/src/sdk/tracing/decorators.ts

@@ -0,0 +1,140 @@
+import { Span, context } from "@opentelemetry/api";
+import { suppressTracing } from "@opentelemetry/core";
+import {
+  ASSOCIATION_PROPERTIES_KEY,
+  getTracer,
+} from "./tracing";
+import {
+  SpanAttributes,
+} from "@traceloop/ai-semantic-conventions";
+import { shouldSendTraces } from ".";
+import { Telemetry } from "../telemetry/telemetry";
+
+export type DecoratorConfig = {
+  name: string;
+  associationProperties?: { [name: string]: string };
+  inputParameters?: unknown[];
+  suppressTracing?: boolean;
+};
+
+export function withEntity<
+  A extends unknown[],
+  F extends (...args: A) => ReturnType<F>,
+>(
+  {
+    name,
+    associationProperties,
+    inputParameters,
+    suppressTracing: shouldSuppressTracing,
+  }: DecoratorConfig,
+  fn: F,
+  thisArg?: ThisParameterType<F>,
+  ...args: A
+) {
+  let entityContext = context.active();
+
+  const currentAssociationProperties = entityContext.getValue(ASSOCIATION_PROPERTIES_KEY);
+
+  if (associationProperties) {
+    entityContext = entityContext.setValue(
+      ASSOCIATION_PROPERTIES_KEY,
+      { ...(currentAssociationProperties ?? {}), ...associationProperties },
+    );
+  }
+
+  if (shouldSuppressTracing) {
+    entityContext = suppressTracing(entityContext);
+  }
+
+  return context.with(entityContext, () =>
+    getTracer().startActiveSpan(
+      name,
+      {},
+      entityContext,
+      async (span: Span) => {
+        if (shouldSendTraces()) {
+          try {
+            const input = inputParameters ?? args;
+            if (
+              input.length === 1 &&
+              typeof input[0] === "object" &&
+              !(input[0] instanceof Map)
+            ) {
+              span.setAttribute(
+                SpanAttributes.TRACELOOP_ENTITY_INPUT,
+                serialize({ args: [], kwargs: input[0] }),
+              );
+            } else {
+              span.setAttribute(
+                SpanAttributes.TRACELOOP_ENTITY_INPUT,
+                serialize({
+                  args: input,
+                  kwargs: {},
+                }),
+              );
+            }
+          } catch (error) {
+            Telemetry.getInstance().logException(error as any);
+          }
+        }
+
+        const res = fn.apply(thisArg, args);
+        if (res instanceof Promise) {
+          return res.then((resolvedRes) => {
+            try {
+              if (shouldSendTraces()) {
+                span.setAttribute(
+                  SpanAttributes.TRACELOOP_ENTITY_OUTPUT,
+                  serialize(resolvedRes),
+                );
+              }
+            } catch (error) {
+              Telemetry.getInstance().logException(error as any);
+            } finally {
+              span.end();
+            }
+
+            return resolvedRes;
+          });
+        }
+        try {
+          if (shouldSendTraces()) {
+            span.setAttribute(
+              SpanAttributes.TRACELOOP_ENTITY_OUTPUT,
+              serialize(res),
+            );
+          }
+        } catch (error) {
+          Telemetry.getInstance().logException(error as any);
+        } finally {
+          span.end();
+        }
+
+        return res;
+      },
+    ),
+  );
+}
+
+function cleanInput(input: unknown): unknown {
+  if (input instanceof Map) {
+    return Array.from(input.entries());
+  } else if (Array.isArray(input)) {
+    return input.map((value) => cleanInput(value));
+  } else if (!input) {
+    return input;
+  } else if (typeof input === "object") {
+    // serialize object one by one
+    const output: any = {};
+    Object.entries(input as any).forEach(([key, value]) => {
+      output[key] = cleanInput(value);
+    });
+    return output;
+  }
+
+  return input;
+}
+
+function serialize(input: unknown): string {
+  return JSON.stringify(cleanInput(input));
+}

package/src/sdk/tracing/index.ts

@@ -0,0 +1,357 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import {
+  SimpleSpanProcessor,
+  BatchSpanProcessor,
+  SpanProcessor,
+} from "@opentelemetry/sdk-trace-node";
+import { baggageUtils } from "@opentelemetry/core";
+import { Span, context, diag } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { Resource } from "@opentelemetry/resources";
+import { SEMRESATTRS_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+import { InitializeOptions } from "../interfaces";
+import {
+  Detector,
+  DetectorSync,
+  IResource,
+  ResourceDetectionConfig,
+  envDetectorSync,
+  hostDetectorSync,
+  processDetectorSync,
+} from "@opentelemetry/resources"
+import {
+  ASSOCIATION_PROPERTIES_KEY,
+} from "./tracing";
+import { Telemetry } from "../telemetry/telemetry";
+import { _configuration } from "../configuration";
+import {
+  SpanAttributes,
+} from "@traceloop/ai-semantic-conventions";
+import { AnthropicInstrumentation } from "@traceloop/instrumentation-anthropic";
+import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";
+import { AzureOpenAIInstrumentation } from "@traceloop/instrumentation-azure";
+import { LlamaIndexInstrumentation } from "@traceloop/instrumentation-llamaindex";
+import {
+  AIPlatformInstrumentation,
+  VertexAIInstrumentation,
+} from "@traceloop/instrumentation-vertexai";
+import { BedrockInstrumentation } from "@traceloop/instrumentation-bedrock";
+import { CohereInstrumentation } from "@traceloop/instrumentation-cohere";
+import { PineconeInstrumentation } from "@traceloop/instrumentation-pinecone";
+import { LangChainInstrumentation } from "@traceloop/instrumentation-langchain";
+import { ChromaDBInstrumentation } from "@traceloop/instrumentation-chromadb";
+import { QdrantInstrumentation } from "@traceloop/instrumentation-qdrant";
+
+let _sdk: NodeSDK;
+let _spanProcessor: SimpleSpanProcessor | BatchSpanProcessor;
+let openAIInstrumentation: OpenAIInstrumentation | undefined;
+let anthropicInstrumentation: AnthropicInstrumentation | undefined;
+let azureOpenAIInstrumentation: AzureOpenAIInstrumentation | undefined;
+let cohereInstrumentation: CohereInstrumentation | undefined;
+let vertexaiInstrumentation: VertexAIInstrumentation | undefined;
+let aiplatformInstrumentation: AIPlatformInstrumentation | undefined;
+let bedrockInstrumentation: BedrockInstrumentation | undefined;
+let langchainInstrumentation: LangChainInstrumentation | undefined;
+let llamaIndexInstrumentation: LlamaIndexInstrumentation | undefined;
+let pineconeInstrumentation: PineconeInstrumentation | undefined;
+let chromadbInstrumentation: ChromaDBInstrumentation | undefined;
+let qdrantInstrumentation: QdrantInstrumentation | undefined;
+
+
+const instrumentations: Instrumentation[] = [];
+
+const initInstrumentations = () => {
+  const exceptionLogger = (e: Error) => Telemetry.getInstance().logException(e);
+  const enrichTokens =
+    (process.env.TRACELOOP_ENRICH_TOKENS || "true").toLowerCase() === "true";
+
+  openAIInstrumentation = new OpenAIInstrumentation({
+    enrichTokens,
+    exceptionLogger,
+  });
+  instrumentations.push(openAIInstrumentation);
+
+  anthropicInstrumentation = new AnthropicInstrumentation({ exceptionLogger });
+  instrumentations.push(anthropicInstrumentation);
+
+  azureOpenAIInstrumentation = new AzureOpenAIInstrumentation({
+    exceptionLogger,
+  });
+  instrumentations.push(azureOpenAIInstrumentation);
+
+  cohereInstrumentation = new CohereInstrumentation({ exceptionLogger });
+  instrumentations.push(cohereInstrumentation);
+
+  vertexaiInstrumentation = new VertexAIInstrumentation({
+    exceptionLogger,
+  });
+  instrumentations.push(vertexaiInstrumentation);
+
+  aiplatformInstrumentation = new AIPlatformInstrumentation({
+    exceptionLogger,
+  });
+  instrumentations.push(aiplatformInstrumentation);
+
+  bedrockInstrumentation = new BedrockInstrumentation({ exceptionLogger });
+  instrumentations.push(bedrockInstrumentation);
+
+  pineconeInstrumentation = new PineconeInstrumentation({ exceptionLogger });
+  instrumentations.push(pineconeInstrumentation);
+
+  langchainInstrumentation = new LangChainInstrumentation({ exceptionLogger });
+  instrumentations.push(langchainInstrumentation);
+
+  llamaIndexInstrumentation = new LlamaIndexInstrumentation({
+    exceptionLogger,
+  });
+  instrumentations.push(llamaIndexInstrumentation);
+
+  chromadbInstrumentation = new ChromaDBInstrumentation({ exceptionLogger });
+  instrumentations.push(chromadbInstrumentation);
+
+  qdrantInstrumentation = new QdrantInstrumentation({ exceptionLogger });
+  instrumentations.push(qdrantInstrumentation);
+};
+
+const manuallyInitInstrumentations = (
+  instrumentModules: InitializeOptions["instrumentModules"],
+) => {
+  const exceptionLogger = (e: Error) => Telemetry.getInstance().logException(e);
+  const enrichTokens =
+    (process.env.TRACELOOP_ENRICH_TOKENS || "true").toLowerCase() === "true";
+
+  instrumentations.length = 0;
+
+  if (instrumentModules?.openAI) {
+    openAIInstrumentation = new OpenAIInstrumentation({
+      enrichTokens,
+      exceptionLogger,
+    });
+    instrumentations.push(openAIInstrumentation);
+    openAIInstrumentation.manuallyInstrument(instrumentModules.openAI);
+  }
+
+  if (instrumentModules?.anthropic) {
+    anthropicInstrumentation = new AnthropicInstrumentation({
+      exceptionLogger,
+    });
+    instrumentations.push(anthropicInstrumentation);
+    anthropicInstrumentation.manuallyInstrument(instrumentModules.anthropic);
+  }
+
+  if (instrumentModules?.azureOpenAI) {
+    const instrumentation = new AzureOpenAIInstrumentation({ exceptionLogger });
+    instrumentations.push(instrumentation as Instrumentation);
+    azureOpenAIInstrumentation = instrumentation;
+    instrumentation.manuallyInstrument(instrumentModules.azureOpenAI);
+  }
+
+  if (instrumentModules?.cohere) {
+    cohereInstrumentation = new CohereInstrumentation({ exceptionLogger });
+    instrumentations.push(cohereInstrumentation);
+    cohereInstrumentation.manuallyInstrument(instrumentModules.cohere);
+  }
+
+  if (instrumentModules?.google_vertexai) {
+    vertexaiInstrumentation = new VertexAIInstrumentation({
+      exceptionLogger,
+    });
+    instrumentations.push(vertexaiInstrumentation);
+    vertexaiInstrumentation.manuallyInstrument(
+      instrumentModules.google_vertexai,
+    );
+  }
+
+  if (instrumentModules?.google_aiplatform) {
+    aiplatformInstrumentation = new AIPlatformInstrumentation({
+      exceptionLogger,
+    });
+    instrumentations.push(aiplatformInstrumentation);
+    aiplatformInstrumentation.manuallyInstrument(
+      instrumentModules.google_aiplatform,
+    );
+  }
+
+  if (instrumentModules?.bedrock) {
+    bedrockInstrumentation = new BedrockInstrumentation({ exceptionLogger });
+    instrumentations.push(bedrockInstrumentation);
+    bedrockInstrumentation.manuallyInstrument(instrumentModules.bedrock);
+  }
+
+  if (instrumentModules?.pinecone) {
+    const instrumentation = new PineconeInstrumentation({ exceptionLogger });
+    instrumentations.push(instrumentation as Instrumentation);
+    instrumentation.manuallyInstrument(instrumentModules.pinecone);
+  }
+
+  if (instrumentModules?.langchain) {
+    langchainInstrumentation = new LangChainInstrumentation({
+      exceptionLogger,
+    });
+    instrumentations.push(langchainInstrumentation);
+    langchainInstrumentation.manuallyInstrument(instrumentModules.langchain);
+  }
+
+  if (instrumentModules?.llamaIndex) {
+    llamaIndexInstrumentation = new LlamaIndexInstrumentation({
+      exceptionLogger,
+    });
+    instrumentations.push(llamaIndexInstrumentation);
+    llamaIndexInstrumentation.manuallyInstrument(instrumentModules.llamaIndex);
+  }
+
+  if (instrumentModules?.chromadb) {
+    chromadbInstrumentation = new ChromaDBInstrumentation({ exceptionLogger });
+    instrumentations.push(chromadbInstrumentation);
+    chromadbInstrumentation.manuallyInstrument(instrumentModules.chromadb);
+  }
+
+  if (instrumentModules?.qdrant) {
+    qdrantInstrumentation = new QdrantInstrumentation({ exceptionLogger });
+    instrumentations.push(qdrantInstrumentation);
+    qdrantInstrumentation.manuallyInstrument(instrumentModules.qdrant);
+  }
+};
+
+function awaitAttributes(detector: DetectorSync): Detector {
+  return {
+    async detect(config?: ResourceDetectionConfig): Promise<IResource> {
+      const resource = detector.detect(config)
+      await resource.waitForAsyncAttributes?.()
+
+      return resource
+    },
+  }
+}
+
+/**
+ * Initializes the Traceloop SDK.
+ * Must be called once before any other SDK methods.
+ *
+ * @param options - The options to initialize the SDK. See the {@link InitializeOptions} for details.
+ */
+export const startTracing = (options: InitializeOptions) => {
+  if (options.instrumentModules !== undefined) {
+    // If options.instrumentModules is empty, it will not initialize anything,
+    // so empty dict can essentially be passed to disable any kind of automatic instrumentation.
+    manuallyInitInstrumentations(options.instrumentModules);
+  } else {
+    initInstrumentations();
+  }
+
+  if (!shouldSendTraces()) {
+    openAIInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    azureOpenAIInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    llamaIndexInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    vertexaiInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    aiplatformInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    bedrockInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    cohereInstrumentation?.setConfig({
+      traceContent: false,
+    });
+    chromadbInstrumentation?.setConfig({
+      traceContent: false,
+    });
+  }
+
+  const headers = process.env.TRACELOOP_HEADERS
+    ? baggageUtils.parseKeyPairsIntoRecord(process.env.TRACELOOP_HEADERS)
+    : { Authorization: `Bearer ${options.apiKey}` };
+
+  const traceExporter =
+    options.exporter ??
+    new OTLPTraceExporter({
+      url: `${options.baseUrl}/v1/traces`,
+      headers,
+    });
+  _spanProcessor = options.disableBatch
+    ? new SimpleSpanProcessor(traceExporter)
+    : new BatchSpanProcessor(traceExporter);
+
+  _spanProcessor.onStart = (span: Span) => {
+    // This sets the properties only if the context has them
+    const associationProperties = context
+      .active()
+      .getValue(ASSOCIATION_PROPERTIES_KEY);
+    if (associationProperties) {
+      for (const [key, value] of Object.entries(associationProperties)) {
+        span.setAttribute(
+          `${SpanAttributes.TRACELOOP_ASSOCIATION_PROPERTIES}.${key}`,
+          value,
+        );
+      }
+    }
+  };
+
+  if (options.exporter) {
+    Telemetry.getInstance().capture("tracer:init", {
+      exporter: "custom",
+      processor: options.disableBatch ? "simple" : "batch",
+    });
+  } else {
+    Telemetry.getInstance().capture("tracer:init", {
+      exporter: options.baseUrl ?? "",
+      processor: options.disableBatch ? "simple" : "batch",
+    });
+  }
+
+  const spanProcessors: SpanProcessor[] = [_spanProcessor];
+  if (options.processor) {
+    spanProcessors.push(options.processor);
+  }
+
+  _sdk = new NodeSDK({
+    resource: new Resource({
+      [SEMRESATTRS_SERVICE_NAME]:
+        options.appName || process.env.npm_package_name,
+    }),
+    spanProcessors,
+    contextManager: options.contextManager,
+    textMapPropagator: options.propagator,
+    traceExporter,
+    instrumentations,
+    // We should re-consider removing irrelevant spans here in the future
+    // sampler: new TraceloopSampler(),
+    resourceDetectors: [
+      awaitAttributes(envDetectorSync),
+      awaitAttributes(processDetectorSync),
+      awaitAttributes(hostDetectorSync),
+    ],
+  });
+
+  _sdk.start();
+};
+
+export const shouldSendTraces = () => {
+  if (!_configuration) {
+    diag.warn("Traceloop not initialized");
+    return false;
+  }
+
+  if (
+    _configuration.traceContent === false ||
+    (process.env.TRACELOOP_TRACE_CONTENT || "true").toLowerCase() === "false"
+  ) {
+    return false;
+  }
+
+  return true;
+};
+
+export const forceFlush = async () => {
+  await _spanProcessor.forceFlush();
+};

package/src/sdk/tracing/manual.ts

@@ -0,0 +1,179 @@
+import { Span, context, trace } from "@opentelemetry/api";
+import { getTracer } from "./tracing";
+import {
+  Events,
+  EventAttributes,
+  SpanAttributes,
+} from "@traceloop/ai-semantic-conventions";
+import { shouldSendTraces } from ".";
+
+type VectorDBCallConfig = {
+  vendor: string;
+  type: "query" | "upsert" | "delete";
+};
+
+type LLMCallConfig = {
+  vendor: string;
+  type: "chat" | "completion";
+};
+
+export class VectorSpan {
+  private span: Span;
+
+  constructor(span: Span) {
+    this.span = span;
+  }
+
+  reportQuery({ queryVector }: { queryVector: number[] }) {
+    if (!shouldSendTraces()) {
+      this.span.addEvent(Events.DB_QUERY_EMBEDDINGS);
+    }
+
+    this.span.addEvent(Events.DB_QUERY_EMBEDDINGS, {
+      [EventAttributes.DB_QUERY_EMBEDDINGS_VECTOR]: JSON.stringify(queryVector),
+    });
+  }
+
+  reportResults({
+    results,
+  }: {
+    results: {
+      ids?: string;
+      scores?: number;
+      distances?: number;
+      metadata?: Record<string, unknown>;
+      vectors?: number[];
+      documents?: string;
+    }[];
+  }) {
+    for (let i = 0; i < results.length; i++) {
+      this.span.addEvent(Events.DB_QUERY_RESULT, {
+        [EventAttributes.DB_QUERY_RESULT_ID]: results[i].ids,
+        [EventAttributes.DB_QUERY_RESULT_SCORE]: results[i].scores,
+        [EventAttributes.DB_QUERY_RESULT_DISTANCE]: results[i].distances,
+        [EventAttributes.DB_QUERY_RESULT_METADATA]: JSON.stringify(
+          results[i].metadata,
+        ),
+        [EventAttributes.DB_QUERY_RESULT_VECTOR]: results[i].vectors,
+        [EventAttributes.DB_QUERY_RESULT_DOCUMENT]: results[i].documents,
+      });
+    }
+  }
+}
+
+export class LLMSpan {
+  private span: Span;
+
+  constructor(span: Span) {
+    this.span = span;
+  }
+
+  reportRequest({
+    model,
+    messages,
+  }: {
+    model: string;
+    messages: {
+      role: string;
+      content?: string | unknown;
+    }[];
+  }) {
+    this.span.setAttributes({
+      [SpanAttributes.LLM_REQUEST_MODEL]: model,
+    });
+
+    messages.forEach((message, index) => {
+      this.span.setAttributes({
+        [`${SpanAttributes.LLM_PROMPTS}.${index}.role`]: message.role,
+        [`${SpanAttributes.LLM_PROMPTS}.${index}.content`]:
+          typeof message.content === "string"
+            ? message.content
+            : JSON.stringify(message.content),
+      });
+    });
+  }
+
+  reportResponse({
+    model,
+    usage,
+    completions,
+  }: {
+    model: string;
+    usage?: {
+      prompt_tokens: number;
+      completion_tokens: number;
+      total_tokens: number;
+    };
+    completions?: {
+      finish_reason: string;
+      message: {
+        role: "system" | "user" | "assistant";
+        content: string | null;
+      };
+    }[];
+  }) {
+    this.span.setAttribute(SpanAttributes.LLM_RESPONSE_MODEL, model);
+
+    if (usage) {
+      this.span.setAttributes({
+        [SpanAttributes.LLM_USAGE_PROMPT_TOKENS]: usage.prompt_tokens,
+        [SpanAttributes.LLM_USAGE_COMPLETION_TOKENS]: usage.completion_tokens,
+        [SpanAttributes.LLM_USAGE_TOTAL_TOKENS]: usage.total_tokens,
+      });
+    }
+
+    completions?.forEach((completion, index) => {
+      this.span.setAttributes({
+        [`${SpanAttributes.LLM_COMPLETIONS}.${index}.finish_reason`]:
+          completion.finish_reason,
+        [`${SpanAttributes.LLM_COMPLETIONS}.${index}.role`]:
+          completion.message.role,
+        [`${SpanAttributes.LLM_COMPLETIONS}.${index}.content`]:
+          completion.message.content || "",
+      });
+    });
+  }
+}
+
+export function withVectorDBCall<
+  F extends ({ span }: { span: VectorSpan }) => ReturnType<F>,
+>({ vendor, type }: VectorDBCallConfig, fn: F, thisArg?: ThisParameterType<F>) {
+  const entityContext = context.active();
+
+  return getTracer().startActiveSpan(
+    `${vendor}.${type}`,
+    { [SpanAttributes.LLM_REQUEST_TYPE]: type },
+    entityContext,
+    (span: Span) => {
+      const res = fn.apply(thisArg, [{ span: new VectorSpan(span) }]);
+      if (res instanceof Promise) {
+        return res.then((resolvedRes) => {
+          span.end();
+          return resolvedRes;
+        });
+      }
+
+      span.end();
+      return res;
+    },
+  );
+}
+
+export function withLLMCall<
+  F extends ({ span }: { span: LLMSpan }) => ReturnType<F>,
+>({ vendor, type }: LLMCallConfig, fn: F, thisArg?: ThisParameterType<F>) {
+  const span = getTracer().startSpan(`${vendor}.${type}`, {}, context.active());
+  span.setAttribute(SpanAttributes.LLM_REQUEST_TYPE, type);
+  trace.setSpan(context.active(), span);
+
+  const res = fn.apply(thisArg, [{ span: new LLMSpan(span) }]);
+  if (res instanceof Promise) {
+    return res.then((resolvedRes) => {
+      span.end();
+      return resolvedRes;
+    });
+  }
+
+  span.end();
+  return res;
+}

package/src/sdk/tracing/sampler.ts

@@ -0,0 +1,35 @@
+import {
+  Sampler,
+  SamplingResult,
+  SamplingDecision,
+} from "@opentelemetry/sdk-trace-base";
+import { Context, SpanKind, Attributes } from "@opentelemetry/api";
+
+const FILTERED_ATTRIBUTE_KEYS = ["next.span_name"];
+
+export class TraceloopSampler implements Sampler {
+  shouldSample(
+    _context: Context,
+    _traceId: string,
+    _spanName: string,
+    _spanKind: SpanKind,
+    attributes: Attributes,
+  ): SamplingResult {
+    let filter = false;
+    FILTERED_ATTRIBUTE_KEYS.forEach((key) => {
+      if (attributes?.[key]) {
+        filter = true;
+      }
+    });
+
+    return {
+      decision: filter
+        ? SamplingDecision.NOT_RECORD
+        : SamplingDecision.RECORD_AND_SAMPLED,
+    };
+  }
+
+  toString(): string {
+    return "TraceloopSampler";
+  }
+}

package/src/sdk/tracing/tracing.ts

@@ -0,0 +1,19 @@
+import { trace, createContextKey } from "@opentelemetry/api";
+import { Context } from "@opentelemetry/api/build/src/context/types";
+
+const TRACER_NAME = "traceloop.tracer";
+export const WORKFLOW_NAME_KEY = createContextKey("workflow_name");
+export const ENTITY_NAME_KEY = createContextKey("entity_name");
+export const ASSOCIATION_PROPERTIES_KEY = createContextKey(
+  "association_properties",
+);
+
+export const getTracer = () => {
+  return trace.getTracer(TRACER_NAME);
+};
+
+export const getEntityPath = (entityContext: Context): string | undefined => {
+  const path = entityContext.getValue(ENTITY_NAME_KEY);
+
+  return path ? `${path}` : undefined;
+};