Skip to content
Effect Days 2026 Get your ticket

OpenAiTelemetry

The OpenAiTelemetry module defines OpenAI-specific telemetry attributes and a helper for adding them to a tracing span. It keeps the standard GenAI telemetry attributes and adds request and response metadata, such as response format, service tier, and system fingerprint, under the gen_ai.openai.* OpenTelemetry namespaces.

8 exports Added in v4.0.0 Source

Models

AllAttributes type

Added in v4.0.0 Source

All telemetry attributes which are part of the GenAI specification, including the OpenAI-specific attributes.

Signature

type AllAttributes = Telemetry.AllAttributes & RequestAttributes & ResponseAttributes

OpenAiTelemetryAttributes type

Added in v4.0.0 Source

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

Details

These attributes follow the OpenTelemetry generative AI semantic conventions: https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/

Signature

type OpenAiTelemetryAttributes = Simplify<Telemetry.GenAITelemetryAttributes & Telemetry.AttributesWithPrefix<RequestAttributes, "gen_ai.openai.request"> & Telemetry.AttributesWithPrefix<ResponseAttributes, "gen_ai.openai.response">>

RequestAttributes interface

Added in v4.0.0 Source

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

Signature

interface RequestAttributes {
  readonly responseFormat?: string & {} | WellKnownResponseFormat | null;
  readonly serviceTier?: string & {} | WellKnownServiceTier | null;
}

ResponseAttributes interface

Added in v4.0.0 Source

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

Signature

interface ResponseAttributes {
  readonly serviceTier?: string | null;
  readonly systemFingerprint?: string | null;
}

WellKnownResponseFormat type

Added in v4.0.0 Source

The gen_ai.openai.request.response_format attribute has the following list of well-known values.

Details

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

Signature

type WellKnownResponseFormat = "json_object" | "json_schema" | "text"

WellKnownServiceTier type

Added in v4.0.0 Source

The gen_ai.openai.request.service_tier attribute has the following list of well-known values.

Details

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

Signature

type WellKnownServiceTier = "auto" | "default"

Options

OpenAiTelemetryAttributeOptions type

Added in v4.0.0 Source

Options accepted by addGenAIAnnotations, combining standard GenAI telemetry attributes with optional OpenAI request and response attributes.

Signature

type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
  openai?: {
    request?: RequestAttributes;
    response?: ResponseAttributes;
  };
}

Tracing

addGenAIAnnotations

Added in v4.0.0 Source

Applies the specified OpenAI GenAI telemetry attributes to the provided Span.

When to use

Use to annotate an existing OpenTelemetry span with standard GenAI attributes plus OpenAI-specific request and response metadata.

Gotchas

Mutates the supplied Span in place.

See

Signature

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