Semantic Conventions

Overview

The @arizeai/openinference-semantic-conventions package provides TypeScript constants for OpenInference tracing attributes. These conventions ensure consistent attribute names across traces.

Installation

npm install --save @arizeai/openinference-semantic-conventions

Package Exports

The package exports constants for trace attributes and resource attributes:

import {
  // Span kinds
  OpenInferenceSpanKind,
  
  // Input/Output attributes
  INPUT_VALUE,
  INPUT_MIME_TYPE,
  OUTPUT_VALUE,
  OUTPUT_MIME_TYPE,
  
  // LLM attributes
  LLM_MODEL_NAME,
  LLM_PROVIDER,
  LLM_INPUT_MESSAGES,
  LLM_OUTPUT_MESSAGES,
  LLM_INVOCATION_PARAMETERS,
  LLM_TOKEN_COUNT_PROMPT,
  LLM_TOKEN_COUNT_COMPLETION,
  LLM_TOKEN_COUNT_TOTAL,
  
  // Context attributes
  SESSION_ID,
  USER_ID,
  METADATA,
  TAG_TAGS,
  
  // Resource attributes
  SEMRESATTRS_PROJECT_NAME,
  
  // MIME types
  MimeType,
  
  // Semantic conventions
  SemanticConventions,
} from "@arizeai/openinference-semantic-conventions";

Span Kinds

OpenInference defines semantic span kinds for AI/LLM operations:

enum OpenInferenceSpanKind {
  CHAIN = "CHAIN",
  LLM = "LLM",
  RETRIEVER = "RETRIEVER",
  RERANKER = "RERANKER",
  EMBEDDING = "EMBEDDING",
  TOOL = "TOOL",
  AGENT = "AGENT",
  EVALUATOR = "EVALUATOR",
}

Usage Example

import { trace } from "@opentelemetry/api";
import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";

const tracer = trace.getTracer("my-service");

const span = tracer.startSpan("llm-call", {
  attributes: {
    ["openinference.span.kind"]: OpenInferenceSpanKind.LLM,
  },
});

Input/Output Attributes

Standard attributes for span inputs and outputs:

import {
  INPUT_VALUE,
  INPUT_MIME_TYPE,
  OUTPUT_VALUE,
  OUTPUT_MIME_TYPE,
  MimeType,
} from "@arizeai/openinference-semantic-conventions";

span.setAttributes({
  [INPUT_VALUE]: "What is OpenInference?",
  [INPUT_MIME_TYPE]: MimeType.TEXT,
  [OUTPUT_VALUE]: "OpenInference is a framework...",
  [OUTPUT_MIME_TYPE]: MimeType.TEXT,
});

Available MIME Types

enum MimeType {
  TEXT = "text/plain",
  JSON = "application/json",
}

LLM Attributes

Attributes specific to LLM operations:

import {
  LLM_MODEL_NAME,
  LLM_PROVIDER,
  LLM_INPUT_MESSAGES,
  LLM_OUTPUT_MESSAGES,
  LLM_INVOCATION_PARAMETERS,
  LLM_TOKEN_COUNT_PROMPT,
  LLM_TOKEN_COUNT_COMPLETION,
  LLM_TOKEN_COUNT_TOTAL,
} from "@arizeai/openinference-semantic-conventions";

span.setAttributes({
  [LLM_MODEL_NAME]: "gpt-4o-mini",
  [LLM_PROVIDER]: "openai",
  [LLM_TOKEN_COUNT_PROMPT]: 12,
  [LLM_TOKEN_COUNT_COMPLETION]: 44,
  [LLM_TOKEN_COUNT_TOTAL]: 56,
  [LLM_INVOCATION_PARAMETERS]: JSON.stringify({ temperature: 0.7 }),
});

Message Attributes

For chat completions with message arrays:

import {
  LLM_INPUT_MESSAGES,
  LLM_OUTPUT_MESSAGES,
  SemanticConventions,
} from "@arizeai/openinference-semantic-conventions";

const inputMessages = [
  { role: "user", content: "What is OpenInference?" },
];

span.setAttribute(
  `${LLM_INPUT_MESSAGES}.0.${SemanticConventions.MESSAGE_ROLE}`,
  "user"
);
span.setAttribute(
  `${LLM_INPUT_MESSAGES}.0.${SemanticConventions.MESSAGE_CONTENT}`,
  "What is OpenInference?"
);

Retrieval Attributes

For document retrieval operations:

import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";

span.setAttribute(
  `${SemanticConventions.RETRIEVAL_DOCUMENTS}.0.${SemanticConventions.DOCUMENT_ID}`,
  "doc-123"
);
span.setAttribute(
  `${SemanticConventions.RETRIEVAL_DOCUMENTS}.0.${SemanticConventions.DOCUMENT_CONTENT}`,
  "Document content..."
);
span.setAttribute(
  `${SemanticConventions.RETRIEVAL_DOCUMENTS}.0.${SemanticConventions.DOCUMENT_SCORE}`,
  0.95
);

Embedding Attributes

For embedding operations:

import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";

span.setAttribute(
  SemanticConventions.EMBEDDING_MODEL_NAME,
  "text-embedding-3-small"
);
span.setAttribute(
  `${SemanticConventions.EMBEDDING_EMBEDDINGS}.0.${SemanticConventions.EMBEDDING_TEXT}`,
  "Text to embed"
);

Tool Attributes

For function/tool calling:

import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";

span.setAttribute(
  `${SemanticConventions.TOOL_CALL}.0.${SemanticConventions.TOOL_NAME}`,
  "get_weather"
);
span.setAttribute(
  `${SemanticConventions.TOOL_CALL}.0.${SemanticConventions.TOOL_PARAMETERS}`,
  JSON.stringify({ city: "Seattle" })
);

Context Attributes

For session and user tracking:

import {
  SESSION_ID,
  USER_ID,
  METADATA,
  TAG_TAGS,
} from "@arizeai/openinference-semantic-conventions";

span.setAttributes({
  [SESSION_ID]: "session-123",
  [USER_ID]: "user-456",
  [METADATA]: JSON.stringify({ tenant: "acme" }),
  [TAG_TAGS]: JSON.stringify(["production", "api"]),
});

Resource Attributes

For identifying the project:

import { Resource } from "@opentelemetry/resources";
import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";

const resource = new Resource({
  [SEMRESATTRS_PROJECT_NAME]: "my-ai-app",
});