Skip to main content Link Search Menu Expand Document (external link)
effect

Telemetry.ts overview

The Telemetry module provides OpenTelemetry integration for operations performed against a large language model provider by defining telemetry attributes and utilities that follow the OpenTelemetry GenAI semantic conventions.

Example

import { Telemetry } from "@effect/ai"
import { Effect } from "effect"

// Add telemetry attributes to a span
const addTelemetry = Effect.gen(function* () {
  const span = yield* Effect.currentSpan

  Telemetry.addGenAIAnnotations(span, {
    system: "openai",
    operation: { name: "chat" },
    request: {
      model: "gpt-4",
      temperature: 0.7,
      maxTokens: 1000
    },
    usage: {
      inputTokens: 100,
      outputTokens: 50
    }
  })
})

Since v1.0.0

Exports Grouped by Category

Context

CurrentSpanTransformer (class)

Context tag for providing a span transformer to large langauge model operations.

The CurrentSpanTransformer allows you to inject custom span transformation logic into AI operations, enabling application-specific telemetry and observability patterns.

Example

import { Telemetry } from "@effect/ai"
import { Context, Effect } from "effect"

// Create a custom span transformer
const loggingTransformer: Telemetry.SpanTransformer = (options) => {
  console.log(`AI request completed: ${options.model}`)
  options.response.forEach((part, index) => {
    console.log(`Part ${index}: ${part.type}`)
  })
}

// Provide the transformer to your AI operations
const program = myAIOperation.pipe(
  Effect.provideService(Telemetry.CurrentSpanTransformer, Telemetry.CurrentSpanTransformer.of(loggingTransformer))
)

Signature

declare class CurrentSpanTransformer

Source

Since v1.0.0

Models

AllAttributes (type alias)

All telemetry attributes which are part of the GenAI specification.

Signature

type AllAttributes = BaseAttributes &
  OperationAttributes &
  TokenAttributes &
  UsageAttributes &
  RequestAttributes &
  ResponseAttributes

Source

Since v1.0.0

BaseAttributes (interface)

Telemetry attributes which are part of the GenAI specification and are namespaced by gen_ai.

Signature

export interface BaseAttributes {
  /**
   * The Generative AI product as identified by the client or server
   * instrumentation.
   */
  readonly system?: (string & {}) | WellKnownSystem | null | undefined
}

Source

Since v1.0.0

GenAITelemetryAttributeOptions (type alias)

Configuration options for GenAI telemetry attributes.

Combines base attributes with optional grouped attributes for comprehensive telemetry coverage of AI operations.

Example

import { Telemetry } from "@effect/ai"

const telemetryOptions: Telemetry.GenAITelemetryAttributeOptions = {
  system: "openai",
  operation: {
    name: "chat"
  },
  request: {
    model: "gpt-4-turbo",
    temperature: 0.7,
    maxTokens: 2000
  },
  response: {
    id: "chatcmpl-123",
    model: "gpt-4-turbo-2024-04-09",
    finishReasons: ["stop"]
  },
  usage: {
    inputTokens: 50,
    outputTokens: 25
  }
}

Signature

type GenAITelemetryAttributeOptions = BaseAttributes & {
  /**
   * Operation-specific attributes (e.g., operation name).
   */
  readonly operation?: OperationAttributes | undefined
  /**
   * Request-specific attributes (e.g., model parameters).
   */
  readonly request?: RequestAttributes | undefined
  /**
   * Response-specific attributes (e.g., response metadata).
   */
  readonly response?: ResponseAttributes | undefined
  /**
   * Token-specific attributes.
   */
  readonly token?: TokenAttributes | undefined
  /**
   * Usage statistics attributes (e.g., token counts).
   */
  readonly usage?: UsageAttributes | undefined
}

Source

Since v1.0.0

GenAITelemetryAttributes (type alias)

The attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses.

{@see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/}

Signature

type GenAITelemetryAttributes = Simplify<
  AttributesWithPrefix<BaseAttributes, "gen_ai"> &
    AttributesWithPrefix<OperationAttributes, "gen_ai.operation"> &
    AttributesWithPrefix<TokenAttributes, "gen_ai.token"> &
    AttributesWithPrefix<UsageAttributes, "gen_ai.usage"> &
    AttributesWithPrefix<RequestAttributes, "gen_ai.request"> &
    AttributesWithPrefix<ResponseAttributes, "gen_ai.response">
>

Source

Since v1.0.0

OperationAttributes (interface)

Telemetry attributes which are part of the GenAI specification and are namespaced by gen_ai.operation.

Signature

export interface OperationAttributes {
  readonly name?: (string & {}) | WellKnownOperationName | null | undefined
}

Source

Since v1.0.0

RequestAttributes (interface)

Telemetry attributes which are part of the GenAI specification and are namespaced by gen_ai.request.

Signature

export interface RequestAttributes {
  /**
   * The name of the GenAI model a request is being made to.
   */
  readonly model?: string | null | undefined
  /**
   * The temperature setting for the GenAI request.
   */
  readonly temperature?: number | null | undefined
  /**
   * The temperature setting for the GenAI request.
   */
  readonly topK?: number | null | undefined
  /**
   * The top_k sampling setting for the GenAI request.
   */
  readonly topP?: number | null | undefined
  /**
   * The top_p sampling setting for the GenAI request.
   */
  readonly maxTokens?: number | null | undefined
  /**
   * The encoding formats requested in an embeddings operation, if specified.
   */
  readonly encodingFormats?: ReadonlyArray<string> | null | undefined
  /**
   * List of sequences that the model will use to stop generating further
   * tokens.
   */
  readonly stopSequences?: ReadonlyArray<string> | null | undefined
  /**
   * The frequency penalty setting for the GenAI request.
   */
  readonly frequencyPenalty?: number | null | undefined
  /**
   * The presence penalty setting for the GenAI request.
   */
  readonly presencePenalty?: number | null | undefined
  /**
   * The seed setting for the GenAI request. Requests with same seed value
   * are more likely to return same result.
   */
  readonly seed?: number | null | undefined
}

Source

Since v1.0.0

ResponseAttributes (interface)

Telemetry attributes which are part of the GenAI specification and are namespaced by gen_ai.response.

Signature

export interface ResponseAttributes {
  /**
   * The unique identifier for the completion.
   */
  readonly id?: string | null | undefined
  /**
   * The name of the model that generated the response.
   */
  readonly model?: string | null | undefined
  /**
   * Array of reasons the model stopped generating tokens, corresponding to
   * each generation received.
   */
  readonly finishReasons?: ReadonlyArray<string> | null | undefined
}

Source

Since v1.0.0

SpanTransformer (interface)

A function that can transform OpenTelemetry spans based on AI operation data.

Span transformers receive the complete request/response context from AI operations and can add custom telemetry attributes, metrics, or other observability data.

Example

import { Telemetry } from "@effect/ai"

const customTransformer: Telemetry.SpanTransformer = (options) => {
  // Add custom attributes based on the response
  const textParts = options.response.filter((part) => part.type === "text")
  const totalTextLength = textParts.reduce((sum, part) => sum + (part.type === "text" ? part.text.length : 0), 0)

  // Add custom metrics
  console.log(`Generated ${totalTextLength} characters of text`)
}

Signature

export interface SpanTransformer {
  (
    options: ProviderOptions & {
      /**
       * Array of response parts generated by the AI model.
       */
      readonly response: ReadonlyArray<Response.AllParts<any>>
    }
  ): void
}

Source

Since v1.0.0

TokenAttributes (interface)

Telemetry attributes which are part of the GenAI specification and are namespaced by gen_ai.token.

Signature

export interface TokenAttributes {
  readonly type?: string | null | undefined
}

Source

Since v1.0.0

UsageAttributes (interface)

Telemetry attributes which are part of the GenAI specification and are namespaced by gen_ai.usage.

Signature

export interface UsageAttributes {
  readonly inputTokens?: number | null | undefined
  readonly outputTokens?: number | null | undefined
}

Source

Since v1.0.0

WellKnownOperationName (type alias)

The gen_ai.operation.name attribute has the following list of well-known values.

If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Signature

type WellKnownOperationName = "chat" | "embeddings" | "text_completion"

Source

Since v1.0.0

WellKnownSystem (type alias)

The gen_ai.system attribute has the following list of well-known values.

If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Signature

type WellKnownSystem =
  | "anthropic"
  | "aws.bedrock"
  | "az.ai.inference"
  | "az.ai.openai"
  | "cohere"
  | "deepseek"
  | "gemini"
  | "groq"
  | "ibm.watsonx.ai"
  | "mistral_ai"
  | "openai"
  | "perplexity"
  | "vertex_ai"
  | "xai"

Source

Since v1.0.0

Utilities

addGenAIAnnotations

Applies GenAI telemetry attributes to an OpenTelemetry span.

This function adds standardized GenAI attributes to a span following OpenTelemetry semantic conventions. It supports both curried and direct application patterns.

Note: This function mutates the provided span in-place.

Example

import { Telemetry } from "@effect/ai"
import { Effect } from "effect"

const directUsage = Effect.gen(function* () {
  const span = yield* Effect.currentSpan

  Telemetry.addGenAIAnnotations(span, {
    system: "openai",
    request: { model: "gpt-4", temperature: 0.7 },
    usage: { inputTokens: 100, outputTokens: 50 }
  })
})

Signature

declare const addGenAIAnnotations: {
  (options: GenAITelemetryAttributeOptions): (span: Span) => void
  (span: Span, options: GenAITelemetryAttributeOptions): void
}

Source

Since v1.0.0

addSpanAttributes

Creates a function to add attributes to a span with a given prefix and key transformation.

This utility function is used internally to create specialized functions for adding different types of telemetry attributes to OpenTelemetry spans.

Example

import { Telemetry } from "@effect/ai"
import { String, Tracer } from "effect"

const addCustomAttributes = Telemetry.addSpanAttributes("custom.ai", String.camelToSnake)

// Usage with a span
declare const span: Tracer.Span
addCustomAttributes(span, {
  modelName: "gpt-4",
  maxTokens: 1000
})
// Results in attributes: "custom.ai.model_name" and "custom.ai.max_tokens"

Signature

declare const addSpanAttributes: (
  keyPrefix: string,
  transformKey: (key: string) => string
) => <Attributes extends Record<string, any>>(span: Span, attributes: Attributes) => void

Source

Since v1.0.0

Utility Types

AttributesWithPrefix (type alias)

Utility type for prefixing attribute names with a namespace.

Transforms attribute keys by adding a prefix and formatting them according to OpenTelemetry conventions (camelCase to snake_case).

Example

import { Telemetry } from "@effect/ai"

type RequestAttrs = {
  modelName: string
  maxTokens: number
}

type PrefixedAttrs = Telemetry.AttributesWithPrefix<RequestAttrs, "gen_ai.request">
// Results in: {
//   "gen_ai.request.model_name": string
//   "gen_ai.request.max_tokens": number
// }

Signature

type AttributesWithPrefix<Attributes, Prefix> = {
  [Name in keyof Attributes as `${Prefix}.${FormatAttributeName<Name>}`]: Attributes[Name]
}

Source

Since v1.0.0

FormatAttributeName (type alias)

Utility type for converting camelCase names to snake_case format.

This type recursively transforms string literal types from camelCase to snake_case, which is the standard format for OpenTelemetry attributes.

Example

import { Telemetry } from "@effect/ai"

type Formatted1 = Telemetry.FormatAttributeName<"modelName"> // "model_name"
type Formatted2 = Telemetry.FormatAttributeName<"maxTokens"> // "max_tokens"
type Formatted3 = Telemetry.FormatAttributeName<"temperature"> // "temperature"

Signature

type FormatAttributeName<T> = T extends string
  ? T extends `${infer First}${infer Rest}`
    ? `${First extends Uppercase<First> ? "_" : ""}${Lowercase<First>}${FormatAttributeName<Rest>}`
    : T
  : never

Source

Since v1.0.0