JavaScript APIopeninference-core

Core

Instrumentation

Integrations

JavaScript · Core

@arizeai/openinference-core

OpenInference Core provides utilities shared by all OpenInference SDK packages.

Version
2.8.4

Install

npm install @arizeai/openinference-core

@arizeai/openinference-core

toInputType

functionSource ↗
function toInputType(...args: unknown[]): SpanInput | undefined

Converts function arguments into a standardized SpanInput format for tracing.

This function processes variable arguments and determines the appropriate MIME type based on the input. Single string arguments are preserved as text, while other types are JSON stringified.

Parameters

NameTypeDescription
...argsunknown[]

The function arguments to process into span input format

Returns

TypeDescription
SpanInput | undefined

A SpanInput object with value and mimeType, or undefined if no args provided

Examples

// String input
toInputType("hello") // { value: "hello", mimeType: MimeType.TEXT }

// Object input
toInputType({ key: "value" }) // { value: '{"key":"value"}', mimeType: MimeType.JSON }

// Multiple arguments
toInputType("arg1", 42) // { value: '["arg1",42]', mimeType: MimeType.JSON }

toOutputType

functionSource ↗
function toOutputType(result: unknown): SpanOutput | undefined

Converts function output into a standardized SpanOutput format for tracing.

This function processes the return value of a traced function and determines the appropriate MIME type. String outputs are preserved as text, while other types are JSON stringified.

Parameters

NameTypeDescription
resultunknown

The function’s return value to process into span output format

Returns

TypeDescription
SpanOutput | undefined

A SpanOutput object with value and mimeType, or undefined if result is null/undefined

Examples

// String output
toOutputType("success") // { value: "success", mimeType: MimeType.TEXT }

// Object output
toOutputType({ status: "ok" }) // { value: '{"status":"ok"}', mimeType: MimeType.JSON }

// Null/undefined output
toOutputType(null) // undefined

defaultProcessInput

constantSource ↗
const defaultProcessInput: InputToAttributesFn

Default input processing function that converts function arguments to OpenTelemetry attributes.

This is a convenience function that combines toInputType and getInputAttributes to provide a complete input processing pipeline for tracing decorators.

Returns

Description

OpenTelemetry attributes representing the input

Examples

const attrs = defaultProcessInput("hello", { key: "value" });
// Returns: { [INPUT_VALUE]: '["hello",{"key":"value"}]', [INPUT_MIME_TYPE]: MimeType.JSON }

defaultProcessOutput

constantSource ↗
const defaultProcessOutput: OutputToAttributesFn

Default output processing function that converts function results to OpenTelemetry attributes.

This is a convenience function that combines toOutputType and getOutputAttributes to provide a complete output processing pipeline for tracing decorators.

Returns

Description

OpenTelemetry attributes representing the output

Examples

const attrs = defaultProcessOutput({ status: "success" });
// Returns: { [OUTPUT_VALUE]: '{"status":"success"}', [OUTPUT_MIME_TYPE]: MimeType.JSON }

getOutputAttributes

functionSource ↗
function getOutputAttributes(
  output: string | SpanOutput | null | undefined,
): Attributes

Converts a SpanOutput object or string into OpenTelemetry attributes.

This function transforms span output data into the standardized attribute format used by OpenTelemetry, mapping values to the appropriate semantic convention keys.

Parameters

NameTypeDescription
outputstring | SpanOutput | null | undefined

The SpanOutput object, string, or undefined to convert

Returns

TypeDescription
Attributes

OpenTelemetry attributes with OUTPUT_VALUE and OUTPUT_MIME_TYPE keys

Examples

// SpanOutput object
getOutputAttributes({ value: "result", mimeType: MimeType.TEXT })
// Returns: { [OUTPUT_VALUE]: "result", [OUTPUT_MIME_TYPE]: MimeType.TEXT }

// String input
getOutputAttributes("simple string")
// Returns: { [OUTPUT_VALUE]: "simple string", [OUTPUT_MIME_TYPE]: MimeType.TEXT }

// Undefined input
getOutputAttributes(undefined) // Returns: {}

getInputAttributes

functionSource ↗
function getInputAttributes(input: string | SpanInput | undefined): Attributes

Converts a SpanInput object or string into OpenTelemetry attributes.

This function transforms span input data into the standardized attribute format used by OpenTelemetry, mapping values to the appropriate semantic convention keys.

Parameters

NameTypeDescription
inputstring | SpanInput | undefined

The SpanInput object, string, or undefined to convert

Returns

TypeDescription
Attributes

OpenTelemetry attributes with INPUT_VALUE and INPUT_MIME_TYPE keys

Examples

// SpanInput object
getOutputAttributes({ value: "query", mimeType: MimeType.TEXT })
// Returns: { [INPUT_VALUE]: "query", [INPUT_MIME_TYPE]: MimeType.TEXT }

// String input
getOutputAttributes("simple string")
// Returns: { [INPUT_VALUE]: "simple string", [INPUT_MIME_TYPE]: MimeType.TEXT }

// Undefined input
getOutputAttributes(undefined) // Returns: {}

getEmbeddingAttributes

functionSource ↗
function getEmbeddingAttributes(
  options: { modelName?: string; embeddings?: Embedding[] },
): Attributes

Generates attributes for embedding operations.

Creates OpenTelemetry attributes for embedding-related data including model name and embedding vectors with associated text.

Parameters

NameTypeDescription
options{ modelName?: string; embeddings?: Embedding[] }

Configuration object for embedding attributes

options.modelName?string

The name of the embedding model used

options.embeddings?Embedding[]

Array of embedding objects containing text and vector data

Returns

TypeDescription
Attributes

OpenTelemetry attributes for embedding operations

Examples

const attrs = getEmbeddingAttributes({
  modelName: "text-embedding-ada-002",
  embeddings: [
    { text: "hello world", vector: [0.1, 0.2, 0.3] },
    { text: "goodbye", vector: [0.4, 0.5, 0.6] }
  ]
});

getRetrieverAttributes

functionSource ↗
function getRetrieverAttributes(options: { documents: Document[] }): Attributes

Generates attributes for retriever operations.

Creates OpenTelemetry attributes for document retrieval operations, including document content, IDs, metadata, and scores.

Parameters

NameTypeDescription
options{ documents: Document[] }

Configuration object for retriever attributes

options.documentsDocument[]

Array of documents retrieved

Returns

TypeDescription
Attributes

OpenTelemetry attributes for retriever operations

Examples

const attrs = getRetrieverAttributes({
  documents: [
    { content: "Document 1", id: "doc1", score: 0.95 },
    { content: "Document 2", id: "doc2", metadata: { source: "web" } }
  ]
});

getDocumentAttributes

functionSource ↗
function getDocumentAttributes(
  document: Document,
  documentIndex: number,
  keyPrefix: string,
): Attributes

Generates attributes for document operations.

Creates OpenTelemetry attributes for individual document processing, including content, ID, metadata, and score information.

Parameters

NameTypeDescription
documentDocument

The document to generate attributes for

documentIndexnumber

The index of the document in a collection

keyPrefixstring

The prefix for attribute keys (e.g., “reranker.input_documents”)

Returns

TypeDescription
Attributes

OpenTelemetry attributes for the document

Examples

const attrs = getDocumentAttributes(
  { content: "Sample document", id: "doc123", score: 0.8 },
  0,
  "reranker.input_documents"
);

getAnnotationAttributes

functionSource ↗
function getAnnotationAttributes(
  options: { annotations: readonly Annotation[]; scope?: AnnotationScope },
): Attributes

Generates annotation attributes for a span, trace, or session.

Collection indices are assigned in input order. Metadata objects are JSON-stringified, while metadata strings are preserved as provided.

Parameters

NameTypeDescription
options{ annotations: readonly Annotation[]; scope?: AnnotationScope }

Annotation values and target scope

options.annotationsreadonly Annotation[]

Ordered annotations to flatten

options.scope?AnnotationScope

Target scope; defaults to span

Returns

TypeDescription
Attributes

OpenTelemetry attributes using annotation terminology

Examples

getAnnotationAttributes({
  annotations: [{ name: "correctness", score: 0.95 }],
  scope: "trace",
});

getEvaluationAttributes

functionSource ↗
function getEvaluationAttributes(
  options: { evaluations: readonly Annotation[]; scope?: AnnotationScope },
): Attributes

Generates annotations using evaluation terminology for a span, trace, or session.

Collection indices are assigned in input order. Metadata objects are JSON-stringified, while metadata strings are preserved as provided.

Parameters

NameTypeDescription
options{ evaluations: readonly Annotation[]; scope?: AnnotationScope }

Annotation values and target scope

options.evaluationsreadonly Annotation[]

Ordered annotations to encode using evaluation terminology

options.scope?AnnotationScope

Target scope; defaults to span

Returns

TypeDescription
Attributes

OpenTelemetry attributes using evaluation terminology

Examples

getEvaluationAttributes({
  evaluations: [{ name: "correctness", label: "correct" }],
  scope: "session",
});

getMetadataAttributes

functionSource ↗
function getMetadataAttributes(metadata: Record<string, unknown>): Attributes

Generates attributes for metadata information.

Parameters

NameTypeDescription
metadataRecord<string, unknown>

The metadata to include in attributes

Returns

TypeDescription
Attributes

OpenTelemetry attributes containing the metadata

Examples

const attrs = getMetadataAttributes({ version: "1.0", env: "prod" });

getToolAttributes

functionSource ↗
function getToolAttributes(
  options: {
    name: string;
    description?: string;
    parameters: Record<string, unknown>;
  },
): Attributes

Generates attributes for tool definitions.

Creates OpenTelemetry attributes for tool information including name, description, and parameters schema.

Parameters

NameTypeDescription
options{ name: string; description?: string; parameters: Record<string, unknown> }

Configuration object for tool attributes

options.namestring

The name of the tool

options.description?string

Optional description of the tool

options.parametersRecord<string, unknown>

Tool parameters as string or object

Returns

TypeDescription
Attributes

OpenTelemetry attributes for the tool

Examples

const attrs = getToolAttributes({
  name: "search_tool",
  description: "Search for information",
  parameters: { query: { type: "string" } }
});

getLLMAttributes

functionSource ↗
function getLLMAttributes(
  options: {
    provider?: string;
    system?: string;
    modelName?: string;
    requestModelName?: string;
    responseModelName?: string;
    invocationParameters?: Record<string, unknown>;
    inputMessages?: Message[];
    outputMessages?: Message[];
    tokenCount?: TokenCount;
    tools?: Tool[];
  },
): Attributes

Generates attributes for LLM operations.

Creates comprehensive OpenTelemetry attributes for LLM interactions including provider, model, messages, token counts, and tools.

Parameters

NameTypeDescription
options{ provider?: string; system?: string; modelName?: string; requestModelName?: string; responseModelName?: string; invocationParameters?: Record<string, unknown>; inputMessages?: Message[]; outputMessages?: Message[]; tokenCount?: TokenCount; tools?: Tool[] }

Configuration object for LLM attributes

options.provider?string

The LLM provider (e.g., “openai”, “anthropic”)

options.system?string

The LLM system type

options.modelName?string

The name of the LLM model

options.requestModelName?string

The model requested by the caller, as sent in the request. When modelName is omitted, llm.model_name is mirrored from responseModelName ?? requestModelName

options.responseModelName?string

The model that actually generated the response, as reported by the provider

options.invocationParameters?Record<string, unknown>

Parameters used for the LLM invocation

options.inputMessages?Message[]

Input messages sent to the LLM

options.outputMessages?Message[]

Output messages received from the LLM

options.tokenCount?TokenCount

Token usage information

options.tools?Tool[]

Tools available to the LLM

Returns

TypeDescription
Attributes

OpenTelemetry attributes for LLM operations

Examples

const attrs = getLLMAttributes({
  provider: "openai",
  modelName: "gpt-4",
  inputMessages: [{ role: "user", content: "Hello" }],
  outputMessages: [{ role: "assistant", content: "Hi there!" }],
  tokenCount: { prompt: 10, completion: 5, total: 15 }
});

getDecisionAttributes

functionSource ↗
function getDecisionAttributes(
  options: {
    provider?: string;
    system?: string;
    modelName?: string;
    requestModelName?: string;
    responseModelName?: string;
    tokenCount?: DecisionTokenCount;
  },
): Attributes

Generates attributes for DECISION operations.

Creates OpenTelemetry attributes for a call to a decision model: a model that scores or selects among candidate options supplied in the request rather than generating free-form text. Decision spans identify the model under the decision.* namespace instead of llm.*, with the same semantics as getLLMAttributes: system names the decision API ecosystem the call conforms to, provider names who hosts the model, and the model name keys follow the same request/response mirroring rules.

Record the raw request and response with getInputAttributes and getOutputAttributes (or the default processors); decision spans have no input or output messages.

Parameters

NameTypeDescription
options{ provider?: string; system?: string; modelName?: string; requestModelName?: string; responseModelName?: string; tokenCount?: DecisionTokenCount }

Configuration object for DECISION attributes

options.provider?string

Who hosts the decision model (e.g., “typesafe”, “openai”). See DecisionProvider in the semantic conventions for well-known values

options.system?string

The decision API ecosystem the call conforms to (e.g., “typesafe” for the System One / Jev API, “openai” for the OpenAI Decisions API). See DecisionSystem in the semantic conventions for well-known values

options.modelName?string

The name of the decision model (e.g., “jev-1.13.0”)

options.requestModelName?string

The model requested by the caller, as sent in the request (e.g., the alias “jev-latest”). When modelName is omitted, decision.model_name is mirrored from responseModelName ?? requestModelName

options.responseModelName?string

The model that actually produced the decision, as reported by the provider

options.tokenCount?DecisionTokenCount

Token usage: the tokens sent (input) and the tokens that make up the typed answers (output)

Returns

TypeDescription
Attributes

OpenTelemetry attributes for DECISION operations

Examples

const attrs = getDecisionAttributes({
  system: "typesafe",
  provider: "typesafe",
  requestModelName: "jev-latest",
  responseModelName: "jev-1.13.0",
  tokenCount: { input: 412, output: 2 },
});

observe

functionSource ↗
function observe<Fn extends AnyFn>(
  options?: SpanTraceOptions,
): (originalMethod: Fn, ctx: ClassMethodDecoratorContext) => (this: unknown, ...args: Parameters<Fn>) => any & Fn

A decorator factory for tracing operations in an LLM application.

This decorator wraps class methods to automatically create OpenTelemetry spans for tracing purposes. It leverages the withSpan function internally to ensure consistent tracing behavior across the library.

The decorator binds the original method at call time so the traced wrapper runs with the correct this value for each invocation.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
options?SpanTraceOptions

Configuration options for the tracing behavior

Returns

TypeDescription
(originalMethod: Fn, ctx: ClassMethodDecoratorContext) => (this: unknown, ...args: Parameters<Fn>) => any & Fn

A decorator function that can be applied to class methods

Examples

class MyService {
  @observe({ name: "processData", kind: "LLM" })
  async processData(input: string) {
    // Method implementation
    return `processed: ${input}`;
  }
}

wrapTracer

functionSource ↗
function wrapTracer(tracer: Tracer): OITracer

A function that ensures the tracer is wrapped in an OITracer if necessary.

Parameters

NameTypeDescription
tracerTracer

The tracer to wrap if necessary

Returns

TypeDescription
OITracer

an OpenInferenceTracer that wraps the OTel Tracer

getTracer

functionSource ↗
function getTracer(name?: string): OITracer

A helper function to get a tracer for the decorators.

AnyFn

type aliasSource ↗
type AnyFn = (...args: any[]) => any

SpanInput

type aliasSource ↗
type SpanInput = 

Represents the input data structure for OpenInference spans.

This type defines how function arguments or input data should be structured when creating span attributes. It provides both the serialized content and metadata about the content format for proper interpretation and display.

Examples

const textInput: SpanInput = {
  value: "Hello, world!",
  mimeType: MimeType.TEXT
};

const jsonInput: SpanInput = {
  value: '{"query": "search term", "limit": 10}',
  mimeType: MimeType.JSON
};

SpanOutput

type aliasSource ↗
type SpanOutput = 

Represents the output data structure for OpenInference spans.

This type defines how function return values or output data should be structured when creating span attributes. It provides both the serialized content and metadata about the content format for proper interpretation and display.

Examples

const textOutput: SpanOutput = {
  value: "Operation completed successfully",
  mimeType: MimeType.TEXT
};

const jsonOutput: SpanOutput = {
  value: '{"status": "success", "result": {"id": 123}}',
  mimeType: MimeType.JSON
};

InputToAttributesFn

type aliasSource ↗
type InputToAttributesFn<Fn extends AnyFn = AnyFn> = (...args: Parameters<Fn>) => Attributes

Function type for processing function arguments into OpenTelemetry attributes.

This function type defines the signature for custom input processors that convert function arguments into OpenTelemetry attributes for span enrichment. The function receives the original function arguments and should return an attributes object that will be added to the span.

Examples

const customInputProcessor: InputToAttributesFn = (...args) => {
  if (args.length === 1 && typeof args[0] === 'object') {
    const input = args[0] as Record<string, unknown>;
    return {
      'input.type': typeof input,
      'input.value': JSON.stringify(input)
    };
  }
  return { 'input.args_count': args.length };
};

OutputToAttributesFn

type aliasSource ↗
type OutputToAttributesFn<Fn extends AnyFn = AnyFn> = (result: Awaited<ReturnType<Fn>>) => Attributes

Function type for processing function results into OpenTelemetry attributes.

This function type defines the signature for custom output processors that convert function return values into OpenTelemetry attributes for span enrichment. The function receives the original function’s return value and should return an attributes object that will be added to the span.

Examples

const customOutputProcessor: OutputToAttributesFn = (result) => {
  if (result && typeof result === 'object') {
    return {
      'output.value': JSON.stringify(result)
    };
  }
  return {
    'output.value': String(result)
  };
};

SpanTraceOptions

interfaceSource ↗
interface SpanTraceOptions<Fn extends AnyFn = AnyFn>

Configuration options for span tracing in OpenInference.

This interface defines all the available options for customizing how functions are traced, including span naming, tracer selection, span classification, and custom input/output processing. These options are used by tracing decorators and wrapper functions to control the tracing behavior.

Examples

// Basic configuration with custom name
const basicOptions: SpanTraceOptions = {
  name: "my-custom-operation"
};

// Advanced configuration with custom processing and base attributes
const advancedOptions: SpanTraceOptions = {
  name: "llm-call",
  kind: "LLM",
  openTelemetrySpanKind: SpanKind.CLIENT,
  attributes: {
    'service.name': 'ai-assistant',
    'llm.model_name': 'gpt-4',
    'environment': 'production'
  },
  processInput: (...args) => ({ "llm.prompt": args[0] }),
  processOutput: (result) => ({ "llm.response": result })
};

// Agent-specific configuration with context attributes
const agentOptions: SpanTraceOptions = {
  kind: "AGENT",
  attributes: {
    'agent.type': 'decision-maker',
    'agent.version': '2.1.0'
  },
  processInput: (...args) => ({
    "agent.input": JSON.stringify(args[0]),
    "agent.context": args[1]?.context || "none"
  })
};

Properties

NameType
name?string

Custom name for the span.

If not provided, the name of the decorated function or wrapped function will be used as the span name. This is useful for providing more descriptive or standardized names for operations.

Examples

"user-authentication", "data-processing-pipeline", "llm-inference"
tracer?Tracer

Custom OpenTelemetry tracer instance to use for this span.

If not provided, the current global tracer provider is consulted when the wrapped function is invoked. This allows wrappers created before provider registration or replacement to pick up the latest global tracer unless you pin a specific tracer here.

Examples

const customTracer = trace.getTracer('my-service', '1.0.0');
const options: SpanTraceOptions = { tracer: customTracer };
openTelemetrySpanKind?SpanKind

The OpenTelemetry span kind to classify the span’s role in a trace.

This determines how the span is categorized in the OpenTelemetry ecosystem and affects how tracing tools display and analyze the span.

Examples

- `SpanKind.CLIENT` for outbound requests
- `SpanKind.SERVER` for inbound request handling
- `SpanKind.INTERNAL` for internal operations
kind?OpenInferenceSpanKind | "LLM" | "CHAIN" | "TOOL" | "RETRIEVER" | "RERANKER" | "EMBEDDING" | "AGENT" | "GUARDRAIL" | "EVALUATOR" | "PROMPT" | "DECISION"

The OpenInference span kind for semantic categorization in LLM applications.

This provides domain-specific classification for AI/ML operations, helping to organize and understand the different types of operations in an LLM workflow.

Examples

- `LLM` for language model inference
- `CHAIN` for workflow sequences
- `AGENT` for autonomous decision-making
- `TOOL` for external tool usage
processInput?InputToAttributesFn<Fn>

Custom function to process input arguments into span attributes.

This allows for custom serialization and attribute extraction from function arguments. If not provided, the default input processor will be used, which safely JSON-stringifies the arguments.

Returns

Description

OpenTelemetry attributes object

Examples

processInput: (...args) => ({
  'input.value': JSON.stringify(args),
  'input.mime_type': MimeType.JSON
})
processOutput?OutputToAttributesFn<Fn>

Custom function to process output values into span attributes.

This allows for custom serialization and attribute extraction from function return values. If not provided, the default output processor will be used, which safely JSON-stringifies the result.

Returns

Description

OpenTelemetry attributes object

Examples

processOutput: (result) => ({
  'output.value': JSON.stringify(result),
  'output.mime_type': MimeType.JSON
})
attributes?Attributes

Base attributes to be added to every span created with these options.

These attributes will be merged with any attributes generated by input/output processors and OpenInference semantic attributes. Base attributes are useful for adding consistent metadata like service information, version numbers, environment details, or any other static attributes that should be present on all spans.

Examples

// Custom business context
attributes: {
  'metadata': JSON.stringify({ tenant: 'tenant-123', feature: 'new-algorithm-enabled', request: 'mobile-app' })
}

Image

interfaceSource ↗
interface Image

Image reference for message content.

Represents an image that can be included in message content, typically containing a URL or other reference to the image data.

Properties

NameType
url?string

TextMessageContent

interfaceSource ↗
interface TextMessageContent

Text-based message content.

Represents textual content within a message, used for standard text-based communication in LLM interactions.

Properties

NameType
type"text"
textstring

ImageMessageContent

interfaceSource ↗
interface ImageMessageContent

Image-based message content.

Represents image content within a message, used for multimodal LLM interactions that can process visual information.

Properties

NameType
type"image"
image?Image

ReasoningMessageContent

interfaceSource ↗
interface ReasoningMessageContent

Reasoning-based message content.

Represents an opaque reasoning entry produced by an LLM. The fields are vendor-issued echo tokens that should be preserved verbatim for stateless replay (e.g. Gemini thoughtSignature, Anthropic redacted_thinking.data, OpenAI Responses encrypted_content). No id is emitted for reasoning content — providers either omit it or it is captured separately.

Properties

NameType
type"reasoning"
text?string

Human-readable reasoning text emitted by the model (e.g. Anthropic thinking blocks, OpenAI Responses reasoning summary text). Emitted as message_content.text and therefore subject to hideInputText / hideOutputText masking.

signature?string

Opaque vendor-issued signature captured verbatim. Maps to provider signature fields and to Gemini thoughtSignature when the signature is attached to a non-tool content part.

data?string

Opaque vendor-issued data captured verbatim. Maps to Anthropic redacted_thinking.data.

encryptedContent?string

OpenAI encrypted_content captured verbatim.

MessageContent

type aliasSource ↗
type MessageContent = TextMessageContent | ImageMessageContent | ReasoningMessageContent

Union type for different types of message content.

Supports text, image, and reasoning content types for multimodal LLM applications that can handle various input formats.

ToolCallFunction

interfaceSource ↗
interface ToolCallFunction

Function call details for tool invocations.

Contains the function name and arguments for tool calls made by LLMs during execution.

Properties

NameType
name?string
arguments?string | Record<string, unknown>

ToolCall

interfaceSource ↗
interface ToolCall

Tool call information.

Represents a complete tool call made by an LLM, including the call ID and function details.

Properties

NameType
id?string
function?ToolCallFunction
reasoningSignature?string

Opaque vendor-issued reasoning echo token attached to a tool call. Maps to Gemini thoughtSignature when it is attached to a functionCall part. The value is preserved verbatim for stateless replay.

Message

interfaceSource ↗
interface Message

Message structure for LLM conversations.

Represents a single message in an LLM conversation, supporting various content types, roles, and tool interactions.

PromptDetails

interfaceSource ↗
interface PromptDetails

Detailed prompt token usage information.

Provides granular information about token usage in prompts, including cache read/write operations and audio processing.

Properties

NameType
audio?number
cacheRead?number
cacheWrite?number

TokenCount

interfaceSource ↗
interface TokenCount

Token count information for LLM operations.

Tracks token usage across different parts of LLM interactions, including prompt, completion, and total token counts.

Properties

DecisionTokenCount

interfaceSource ↗
interface DecisionTokenCount

Token count information for DECISION operations.

Decision models have no prompt/completion split, only the tokens sent (state, questions, and candidate options) and the tokens that make up the typed answers. There is no total: it is derivable as the sum when both counts are present.

Properties

NameType
input?number
output?number

Tool

interfaceSource ↗
interface Tool

Tool definition for LLM function calling.

Defines a tool that can be called by an LLM, including its JSON schema for parameter validation.

Properties

NameType
jsonSchemastring | Record<string, unknown>

Embedding

interfaceSource ↗
interface Embedding

Embedding representation with associated text.

Contains both the original text and its vector representation for embedding-based operations and similarity searches.

Properties

NameType
text?string
vector?number[]

Document

interfaceSource ↗
interface Document

Document structure for retrieval and search operations.

Represents a document in a knowledge base or search system, including content, metadata, and relevance scoring.

Properties

NameType
content?string
id?string | number
metadata?string | Record<string, unknown>
score?number

AnnotationScope

type aliasSource ↗
type AnnotationScope = "span" | "trace" | "session"

The target scope described by an annotation or evaluation.

Annotation

type aliasSource ↗
type Annotation = AnnotationBase & AnnotationResult

A single annotation or evaluation result.

Every result requires a name and at least one of score, label, or explanation.

withSpan

functionSource ↗
function withSpan<Fn extends AnyFn = AnyFn>(
  fn: Fn,
  options?: SpanTraceOptions<Fn>,
): Fn

Wraps a function with openinference tracing capabilities, creating spans for execution monitoring.

This function provides comprehensive tracing for both synchronous and asynchronous functions, automatically handling span lifecycle, input/output processing, error tracking, and promise resolution.

Agent-facing behavior to rely on:

  • Preserves the call-time this value, so wrapped methods still work when invoked as methods or via .call() / .apply()
  • Records both synchronous throws and rejected promises on the span, marks the span as ERROR, ends the span, and re-throws the original error
  • Resolves the default tracer when the wrapped function is invoked, so wrappers created before a global tracer provider change pick up the latest provider unless options.tracer was set

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with tracing capabilities

options?SpanTraceOptions<Fn>

Configuration options for tracing behavior

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates spans during execution

Examples

// Basic function wrapping
const add = (a: number, b: number) => a + b;
const tracedAdd = withSpan(add);
const result = tracedAdd(2, 3); // Creates a span named "add"

// Async function with custom options
const fetchData = async (url: string) => {
  const response = await fetch(url);
  return response.json();
};
const tracedFetch = withSpan(fetchData, {
  name: "api-request",
  kind: "LLM"
});

// Custom input/output processing with base attributes
const processUser = (user: User) => ({ ...user, processed: true });
const tracedProcess = withSpan(processUser, {
  attributes: {
    'service.name': 'user-processor',
    'service.version': '1.0.0'
  },
  processInput: (user) => ({ "user.id": user.id }),
  processOutput: (result) => ({ "result.processed": result.processed })
});

traceChain

functionSource ↗
function traceChain<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a CHAIN span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to CHAIN. Chain spans represent a sequence of operations or a workflow in an LLM application, such as a series of processing steps or a pipeline.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with CHAIN span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates CHAIN spans during execution

Examples

// Trace a data processing pipeline
const processData = (data: any[]) => {
  return data.map(item => transform(item)).filter(item => validate(item));
};
const tracedProcess = traceChain(processData, { name: "data-pipeline" });

// Trace a multi-step workflow
const executeWorkflow = async (input: WorkflowInput) => {
  const step1 = await preprocessInput(input);
  const step2 = await processStep(step1);
  return await finalizeOutput(step2);
};
const tracedWorkflow = traceChain(executeWorkflow);

traceAgent

functionSource ↗
function traceAgent<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as an AGENT span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to AGENT. Agent spans represent autonomous decision-making entities in an LLM application, such as AI agents, chat bots, or intelligent assistants that can reason, plan, and execute actions.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with AGENT span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates AGENT spans during execution

Examples

// Trace an AI agent's decision-making process
const makeDecision = async (context: AgentContext) => {
  const analysis = await analyzeContext(context);
  const plan = await createPlan(analysis);
  return await executePlan(plan);
};
const tracedAgent = traceAgent(makeDecision, { name: "decision-agent" });

// Trace a chatbot response generation
const generateResponse = (userMessage: string, history: Message[]) => {
  const intent = classifyIntent(userMessage);
  const context = buildContext(history);
  return generateReply(intent, context);
};
const tracedChatbot = traceAgent(generateResponse);

traceTool

functionSource ↗
function traceTool<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a TOOL span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to TOOL. Tool spans represent external tools, utilities, or services that an LLM application can invoke, such as APIs, databases, calculators, web scrapers, or any external function that provides specific capabilities.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with TOOL span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates TOOL spans during execution

Examples

// Trace an API call tool
const fetchWeather = async (city: string) => {
  const response = await fetch(`/api/weather?city=${city}`);
  return response.json();
};
const tracedWeatherTool = traceTool(fetchWeather, { name: "weather-api" });

// Trace a calculator tool
const calculate = (expression: string) => {
  return eval(expression); // Note: eval is dangerous, use proper parser
};
const tracedCalculator = traceTool(calculate, { name: "calculator" });

// Trace a database query tool
const queryDatabase = async (query: string, params: any[]) => {
  return await db.query(query, params);
};
const tracedDbTool = traceTool(queryDatabase);

traceLLM

functionSource ↗
function traceLLM<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as an LLM span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to LLM. LLM spans represent invocations of a large language model, such as chat completions, text completions, or other inference calls to a foundation model.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with LLM span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates LLM spans during execution

Examples

// Trace a chat completion call
const chatCompletion = async (messages: Message[]) => {
  return await client.chat.completions.create({ model: "gpt-4", messages });
};
const tracedCompletion = traceLLM(chatCompletion, { name: "chat-completion" });

traceRetriever

functionSource ↗
function traceRetriever<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a RETRIEVER span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to RETRIEVER. Retriever spans represent operations that fetch relevant documents or context from a knowledge base, vector store, or search index, typically as part of a retrieval-augmented generation (RAG) workflow.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with RETRIEVER span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates RETRIEVER spans during execution

Examples

// Trace a vector store similarity search
const retrieveDocuments = async (query: string) => {
  return await vectorStore.similaritySearch(query, 5);
};
const tracedRetriever = traceRetriever(retrieveDocuments, { name: "vector-search" });

traceReranker

functionSource ↗
function traceReranker<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a RERANKER span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to RERANKER. Reranker spans represent operations that reorder or score a set of candidate documents by relevance to a query, commonly used to refine the results returned by a retriever before passing them to a language model.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with RERANKER span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates RERANKER spans during execution

Examples

// Trace a document reranking operation
const rerankDocuments = async (query: string, documents: Document[]) => {
  return await reranker.rerank(query, documents);
};
const tracedReranker = traceReranker(rerankDocuments, { name: "rerank" });

traceEmbedding

functionSource ↗
function traceEmbedding<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as an EMBEDDING span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to EMBEDDING. Embedding spans represent operations that convert text or other data into vector representations, such as generating embeddings for documents or queries used in semantic search and retrieval.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with EMBEDDING span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates EMBEDDING spans during execution

Examples

// Trace an embedding generation call
const embedText = async (text: string) => {
  return await client.embeddings.create({ model: "text-embedding-3-small", input: text });
};
const tracedEmbedding = traceEmbedding(embedText, { name: "embed-text" });

traceGuardrail

functionSource ↗
function traceGuardrail<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a GUARDRAIL span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to GUARDRAIL. Guardrail spans represent safety, validation, or policy checks applied to inputs or outputs of an LLM application, such as content moderation, PII detection, or compliance enforcement.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with GUARDRAIL span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates GUARDRAIL spans during execution

Examples

// Trace a content moderation check
const moderateContent = async (text: string) => {
  return await moderationClient.check(text);
};
const tracedGuardrail = traceGuardrail(moderateContent, { name: "content-moderation" });

traceEvaluator

functionSource ↗
function traceEvaluator<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as an EVALUATOR span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to EVALUATOR. Evaluator spans represent operations that assess or score the quality of an LLM application’s output, such as relevance scoring, correctness checks, or LLM-as-a-judge evaluations.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with EVALUATOR span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates EVALUATOR spans during execution

Examples

// Trace an LLM-as-a-judge evaluation
const evaluateAnswer = async (question: string, answer: string) => {
  return await judge.score({ question, answer });
};
const tracedEvaluator = traceEvaluator(evaluateAnswer, { name: "answer-evaluation" });

tracePrompt

functionSource ↗
function tracePrompt<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a PROMPT span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to PROMPT. Prompt spans represent operations that construct, render, or template a prompt before it is sent to a language model, such as formatting a prompt template with variables or assembling a set of messages.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with PROMPT span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates PROMPT spans during execution

Examples

// Trace a prompt template rendering
const renderPrompt = (variables: Record<string, string>) => {
  return promptTemplate.format(variables);
};
const tracedPrompt = tracePrompt(renderPrompt, { name: "render-prompt" });

traceDecision

functionSource ↗
function traceDecision<Fn extends AnyFn>(
  fn: Fn,
  options?: Omit<SpanTraceOptions<AnyFn>, "kind">,
): Fn

Wraps a function with tracing capabilities, specifically marking it as a DECISION span.

This is a convenience function that wraps withSpan with the OpenInference span kind pre-configured to DECISION. Decision spans represent calls to a decision model that scores or selects among candidate options provided in the request rather than generating free-form text, such as choosing a route, judging a condition, or scoring an item against a rubric.

This API is experimental and may change in future versions

Parameters

NameTypeDescription
fnFn

The function to wrap with DECISION span tracing

options?Omit<SpanTraceOptions<AnyFn>, "kind">

Configuration options for tracing behavior (excluding kind)

Returns

TypeDescription
Fn

A wrapped function with identical signature that creates DECISION spans during execution

Examples

// Trace a route selection decision
const selectRoute = async (query: string, routes: Route[]) => {
  return await decisionModel.choose({ query, candidates: routes });
};
const tracedDecision = traceDecision(selectRoute, { name: "route-selection" });

ContextAttributes

constantSource ↗
const ContextAttributes

Properties

NameType
llm.prompt_template.templatesymbol = ...
llm.prompt_template.variablessymbol = ...
llm.prompt_template.versionsymbol = ...
session.idsymbol = ...
metadatasymbol = ...
user.idsymbol = ...
tag.tagssymbol = ...
attributessymbol = ...

setPromptTemplate

functionSource ↗
function setPromptTemplate(
  context: Context,
  promptTemplate: PromptTemplate,
): Context

Sets the prompt template in the given OpenTelemetry context. If OI tracer is used in spans created during this active context, the prompt template will be added to the span as an attribute.

Parameters

NameTypeDescription
contextContext

The context to set the prompt template on.

promptTemplatePromptTemplate

The prompt template to set on the context.

Returns

TypeDescription
Context

The context

Examples

context.with(
  setPromptTemplate(context.active(), {
    template: "hello {name}",
    variables: { name: "world" },
    version: "V1.0"
  }),
  () => {
    // Spans created here will have prompt template attributes
  }
);

clearPromptTemplate

functionSource ↗
function clearPromptTemplate(context: Context): Context

Clears the prompt template from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to clear the prompt template from.

Returns

TypeDescription
Context

The context

getPromptTemplate

functionSource ↗
function getPromptTemplate(
  context: Context,
): Partial<PromptTemplate> | undefined

Gets the prompt template from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to get the prompt template from.

Returns

TypeDescription
Partial<PromptTemplate> | undefined

The prompt template

Examples

const promptTemplate = getPromptTemplate(context.active());

setSession

functionSource ↗
function setSession(context: Context, session: Session): Context

Sets the session ID in the given OpenTelemetry context. If OI tracer is used in spans created during this active context, the session ID will be added to the span as an attribute.

Parameters

NameTypeDescription
contextContext

The context to set the session ID on.

sessionSession

The session to set on the context.

Returns

TypeDescription
Context

The context

Examples

context.with(
  setSession(context.active(), { sessionId: "session-123" }),
  () => {
    // Spans created here will have session ID attribute
  }
);

clearSession

functionSource ↗
function clearSession(context: Context): Context

getSession

functionSource ↗
function getSession(context: Context): Session | undefined

Retrieves the session ID from the given context.

Parameters

NameTypeDescription
contextContext

The context object.

Returns

TypeDescription
Session | undefined

The session ID if it exists, otherwise undefined.

setMetadata

functionSource ↗
function setMetadata(context: Context, metadata: Metadata): Context

Sets the metadata in the given OpenTelemetry context. If OI tracer is used in spans created during this active context, the metadata will be added to the span as an attribute.

Parameters

NameTypeDescription
contextContext

The context to set the metadata on.

metadataMetadata

The metadata to set on the context.

Returns

TypeDescription
Context

The context

Examples

context.with(
  setMetadata(context.active(), { key: "value", numeric: 1 }),
  () => {
    // Spans created here will have metadata attribute
  }
);

clearMetadata

functionSource ↗
function clearMetadata(context: Context): Context

Clears the metadata from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to clear the metadata from.

Returns

TypeDescription
Context

The context

getMetadata

functionSource ↗
function getMetadata(context: Context): Metadata | undefined

Gets the metadata from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to get the metadata from.

Returns

TypeDescription
Metadata | undefined

The metadata

Examples

const metadata = getMetadata(context.active());

setUser

functionSource ↗
function setUser(context: Context, user: User): Context

Sets the user ID in the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to set the user ID on.

userUser

The user to set on the context.

Returns

TypeDescription
Context

The context

Examples

context.with(
  setUser(context.active(), { userId: "user-123" }),
  () => {
    // Spans created here will have user ID attribute
  }
);

clearUser

functionSource ↗
function clearUser(context: Context): Context

Clears the user ID from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to clear the user ID from.

Returns

TypeDescription
Context

The context

getUser

functionSource ↗
function getUser(context: Context): User | undefined

Gets the user ID from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to get the user ID from.

Returns

TypeDescription
User | undefined

The user

Examples

const user = getUser(context.active());

setTags

functionSource ↗
function setTags(context: Context, tags: Tags): Context

Sets the tags in the given OpenTelemetry context. If OI tracer is used in spans created during this active context, the tags will be added to the span as an attribute.

Parameters

NameTypeDescription
contextContext

The context to set the tags on.

tagsTags

The tags to set on the context.

Returns

TypeDescription
Context

The context

Examples

context.with(
  setTags(context.active(), ["tag1", "tag2"]),
  () => {
    // Spans created here will have tags attribute
  }
);

clearTags

functionSource ↗
function clearTags(context: Context): Context

Clears the tags from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to clear the tags from.

Returns

TypeDescription
Context

The context

getTags

functionSource ↗
function getTags(context: Context): Tags | undefined

Gets the tags from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to get the tags from.

Returns

TypeDescription
Tags | undefined

The tags

Examples

const tags = getTags(context.active());

setAttributes

functionSource ↗
function setAttributes(context: Context, attributes: Attributes): Context

Sets the attributes in the given OpenTelemetry context. If OI tracer is used in spans created during this active context, the attributes will be added to the span as an attribute.

Parameters

NameTypeDescription
contextContext

The context to set the attributes on.

attributesAttributes

The attributes to set on the context.

Returns

TypeDescription
Context

The context

Examples

context.with(
  setAttributes(context.active(), { custom: "value", test: "attribute" }),
  () => {
    // Spans created here will have custom attributes
  }
);

clearAttributes

functionSource ↗
function clearAttributes(context: Context): Context

Clears the attributes from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to clear the attributes from.

Returns

TypeDescription
Context

The context

getAttributes

functionSource ↗
function getAttributes(context: Context): Attributes | undefined

Gets the attributes from the given OpenTelemetry context.

Parameters

NameTypeDescription
contextContext

The context to get the attributes from.

Returns

TypeDescription
Attributes | undefined

The attributes

Examples

const attributes = getAttributes(context.active());

getAttributesFromContext

functionSource ↗
function getAttributesFromContext(context: Context): Attributes

Gets the OpenInference attributes from the given context

Examples

// Chaining multiple attributes
context.with(
  setSession(
    setPromptTemplate(context.active(), {
      template: "hello {name}",
      variables: { name: "world" },
      version: "V1.0"
    }),
    { sessionId: "session-123" }
  ),
  () => {
    // Extract all attributes for span
    const attributes = getAttributesFromContext(context.active());
    span.setAttributes(attributes);
  }
);

Returns

TypeDescription
Attributes

The OpenInference attributes formatted as OpenTelemetry span attributes.

OISpan

interfaceSource ↗
interface OISpan implements Span

A wrapper around the OpenTelemetry Span interface that masks sensitive information based on the passed in TraceConfig.

setAttribute

methodSource ↗
setAttribute(key: string, value: AttributeValue): this

Sets an attribute to the span.

Sets a single Attribute with the key and value passed as arguments.

Parameters

NameTypeDescription
keystring

the key for this attribute.

valueAttributeValue

the value for this attribute. Setting a value null or undefined is invalid and will result in undefined behavior.

setAttributes

methodSource ↗
setAttributes(attributes: Attributes): this

Sets attributes to the span.

Parameters

NameTypeDescription
attributesAttributes

the attributes that will be added. null or undefined attribute values are invalid and will result in undefined behavior.

addEvent

methodSource ↗
addEvent(
  name: string,
  attributesOrStartTime?: Attributes | TimeInput,
  startTime?: TimeInput,
): this

Adds an event to the Span.

Parameters

NameTypeDescription
namestring

the name of the event.

attributesOrStartTime?Attributes | TimeInput

the attributes that will be added; these are associated with this event. Can be also a start time if type is TimeInput and 3rd param is undefined

startTime?TimeInput

start time of the event.

setStatus

methodSource ↗
setStatus(status: SpanStatus): this

Sets a status to the span. If used, this will override the default Span status. Default is SpanStatusCode.UNSET. SetStatus overrides the value of previous calls to SetStatus on the Span.

Parameters

NameTypeDescription
statusSpanStatus

the SpanStatus to set.

updateName

methodSource ↗
updateName(name: string): this

Updates the Span name.

This will override the name provided via Tracer.startSpan.

Upon this update, any sampling behavior based on Span name will depend on the implementation.

Parameters

NameTypeDescription
namestring

the Span name.

end

methodSource ↗
end(endTime?: TimeInput): void

Marks the end of Span execution.

Call to End of a Span MUST not have any effects on child spans. Those may still be running and can be ended later.

Do not return this. The Span generally should not be used after it is ended so chaining is not desired in this context.

Parameters

NameTypeDescription
endTime?TimeInput

the time to set as Span’s end time. If not provided, use the current time as the span’s end time.

isRecording

methodSource ↗
isRecording(): boolean

Returns the flag whether this span will be recorded.

Returns

TypeDescription
boolean

true if this Span is active and recording information like events with the AddEvent operation and attributes using setAttributes.

recordException

methodSource ↗
recordException(exception: Exception, time?: TimeInput): void

Sets exception as a span event

Parameters

NameTypeDescription
exceptionException

the exception the only accepted values are string or Error

time?TimeInput

the time to set as Span’s event time. If not provided, use the current time.

spanContext

methodSource ↗
spanContext(): SpanContext

Returns the SpanContext object associated with this Span.

Get an immutable, serializable identifier for this span that can be used to create new child spans. Returned SpanContext is usable even after the span ends.

Returns

TypeDescription
SpanContext

the SpanContext object associated with this Span.

OITracer

classSource ↗
class OITracer implements Tracer

A wrapper around the OpenTelemetry Tracer interface that masks sensitive information based on the passed in TraceConfig.

new OITracer

constructorSource ↗
new OITracer(
  params: { tracer: Tracer; traceConfig?: TraceConfigOptions },
): OITracer

Parameters

NameTypeDescription
params{ tracer: Tracer; traceConfig?: TraceConfigOptions }

The parameters for the OITracer constructor

params.tracerTracer

The OpenTelemetry Tracer to wrap

params.traceConfig?TraceConfigOptions

The TraceConfigOptions to set to control the behavior of the tracer

startActiveSpan

methodSource ↗
startActiveSpan<F extends (span: OISpan) => unknown>(
  name: string,
  fn: F,
): ReturnType<F>
startActiveSpan<F extends (span: OISpan) => unknown>(
  name: string,
  options: SpanOptions,
  fn: F,
): ReturnType<F>
startActiveSpan<F extends (span: OISpan) => unknown>(
  name: string,
  options: SpanOptions,
  context: Context,
  fn: F,
): ReturnType<F>

Overload 1

Starts a new Span and calls the given function passing it the created span as first argument. Additionally the new span gets set in context and this context is activated for the duration of the function call.

Parameters

NameTypeDescription
namestring

The name of the span

fnF

function called in the context of the span and receives the newly created span as an argument

Returns

TypeDescription
ReturnType<F>

return value of fn

Examples

const something = tracer.startActiveSpan('op', span => {
      try {
        do some work
        span.setStatus({code: SpanStatusCode.OK});
        return something;
      } catch (err) {
        span.setStatus({
          code: SpanStatusCode.ERROR,
          message: err.message,
        });
        throw err;
      } finally {
        span.end();
      }
    });

Examples

const span = tracer.startActiveSpan('op', span => {
      try {
        do some work
        return span;
      } catch (err) {
        span.setStatus({
          code: SpanStatusCode.ERROR,
          message: err.message,
        });
        throw err;
      }
    });
    do some more work
    span.end();

startSpan

methodSource ↗
startSpan(name: string, options?: SpanOptions, context?: Context): OISpan

Starts a new Span. Start the span without setting it on context.

This method do NOT modify the current Context.

Parameters

NameTypeDescription
namestring

The name of the span

options?SpanOptions

SpanOptions used for span creation

context?Context

Context to use to extract parent

Returns

TypeDescription
OISpan

Span The newly created span

Examples

const span = tracer.startSpan('op');
    span.setAttribute('key', 'value');
    span.end();

generateTraceConfig

functionSource ↗
function generateTraceConfig(options?: TraceConfigOptions): TraceConfig

Generates a full trace config object based on passed in options, environment variables, and default values. The order of precedence is: optionValue > envValue > defaultValue

Parameters

NameTypeDescription
options?TraceConfigOptions

The user provided TraceConfigOptions.

Returns

TypeDescription
TraceConfig

A full TraceConfig object with all options set to their final values.

TraceConfigOptions

type aliasSource ↗
type TraceConfigOptions = 

Tracing configuration options that can be set to hide or redact sensitive information from traces

TraceConfig

type aliasSource ↗
type TraceConfig = Readonly<Required<TraceConfigOptions>>

A full tracing configuration object that includes all possible options with their final values

Session

type aliasSource ↗
type Session = 

A session that can be attached to context

Metadata

type aliasSource ↗
type Metadata = Record<string, unknown>

Metadata that can be attached to context

User

type aliasSource ↗
type User = 

A user that can be attached to context

PromptTemplate

type aliasSource ↗
type PromptTemplate = 

A prompt template that can be attached to context

Tags

type aliasSource ↗
type Tags = string[]

A set of tags that can be attached to context

withSafety

functionSource ↗
function withSafety<T extends GenericFunction>(
  fn: { fn: T; onError?: (error: unknown) => void },
): SafeFunction<T>

Wraps a function with a try-catch block to catch and log any errors.

Parameters

NameTypeDescription
fn{ fn: T; onError?: (error: unknown) => void }

A function to wrap with a try-catch block.

fn.fnT
fn.onError?(error: unknown) => void

Returns

TypeDescription
SafeFunction<T>

A function that returns null if an error is thrown.

safelyJSONStringify

constantSource ↗
const safelyJSONStringify: SafeFunction<(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number) => string>

safelyJSONParse

constantSource ↗
const safelyJSONParse: SafeFunction<(...args: [text: string, reviver?: (this: any, key: string, value: any) => any]) => unknown>

isStringArray

functionSource ↗
function isStringArray(value: unknown): value is string[]

Type guard to determine whether or not a value is an array of strings.

Returns

TypeDescription
value is string[]

true if the value is an array of strings, false otherwise.

isObjectWithStringKeys

functionSource ↗
function isObjectWithStringKeys(
  value: unknown,
): value is Record<string, unknown>

Type guard to determine whether or not a value is an object with string keys.

Returns

TypeDescription
value is Record<string, unknown>

true if the value is an object with string keys, false otherwise.

isPromise

functionSource ↗
function isPromise<T = unknown>(value: unknown): value is Promise<T>

Type guard for if a function is a Promise

Returns

TypeDescription
value is Promise<T>

true if it is a Promise

isAttributes

functionSource ↗
function isAttributes(value: unknown): value is Attributes

Type guard to determine whether or not a value is an object with string keys and attribute values.

Returns

TypeDescription
value is Attributes

true if the value is an object with string keys and attribute values, false otherwise.

assertUnreachable

functionSource ↗
function assertUnreachable(value: never): never

A type check function to ensure that a switch or set of conditionals is exhaustive. Typescript will throw an error if the switch or conditionals are not exhaustive.

Examples

type MyType = "a" | "b";
function myFunction(value: MyType) {
  switch (value) {
    case "a":
     return "A";
   case "b":
     return "B";
   default:
     assertUnreachable(value);
  }
}

GenericFunction

type aliasSource ↗
type GenericFunction = (...args: any[]) => any

SafeFunction

type aliasSource ↗
type SafeFunction<T extends GenericFunction> = (...args: Parameters<T>) => ReturnType<T> | null

Constants

NameValue
OPENINFERENCE_HIDE_LLM_TOOLS"OPENINFERENCE_HIDE_LLM_TOOLS"

Hides the tool definitions advertised to the LLM

OPENINFERENCE_HIDE_INPUTS"OPENINFERENCE_HIDE_INPUTS"

Hides input value & messages

OPENINFERENCE_HIDE_OUTPUTS"OPENINFERENCE_HIDE_OUTPUTS"

Hides output value & messages

OPENINFERENCE_HIDE_INPUT_MESSAGES"OPENINFERENCE_HIDE_INPUT_MESSAGES"

Hides all input messages

OPENINFERENCE_HIDE_OUTPUT_MESSAGES"OPENINFERENCE_HIDE_OUTPUT_MESSAGES"

Hides all output messages

OPENINFERENCE_HIDE_INPUT_IMAGES"OPENINFERENCE_HIDE_INPUT_IMAGES"

Hides images from input messages

OPENINFERENCE_HIDE_INPUT_TEXT"OPENINFERENCE_HIDE_INPUT_TEXT"

Hides text from input messages

OPENINFERENCE_HIDE_OUTPUT_TEXT"OPENINFERENCE_HIDE_OUTPUT_TEXT"

Hides text from output messages

OPENINFERENCE_HIDE_EMBEDDING_VECTORS"OPENINFERENCE_HIDE_EMBEDDING_VECTORS"

Hides embedding vectors

OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH"OPENINFERENCE_BASE64_IMAGE_MAX_LENGTH"

Limits characters of a base64 encoding of an image

OPENINFERENCE_HIDE_PROMPTS"OPENINFERENCE_HIDE_PROMPTS"

Hides LLM prompts

DEFAULT_HIDE_LLM_TOOLSfalse
DEFAULT_HIDE_INPUTSfalse
DEFAULT_HIDE_OUTPUTSfalse
DEFAULT_HIDE_INPUT_MESSAGESfalse
DEFAULT_HIDE_OUTPUT_MESSAGESfalse
DEFAULT_HIDE_INPUT_IMAGESfalse
DEFAULT_HIDE_INPUT_TEXTfalse
DEFAULT_HIDE_OUTPUT_TEXTfalse
DEFAULT_HIDE_EMBEDDING_VECTORSfalse
DEFAULT_BASE64_IMAGE_MAX_LENGTH32000
REDACTED_VALUE"__REDACTED__"

When a value is hidden, it will be replaced by this redacted value