Translating Semantic Conventions

Why Translation is Needed

Semantic conventions are standardized attribute names and values that ensure consistent tracing across different LLM providers, models, and frameworks. Different instrumentation standards use different semantic conventions to describe LLM operations. Phoenix uses OpenInference semantic conventions as its standard format. To ensure all traces are displayed consistently in Phoenix, traces from other libraries must be translated to the OpenInference format using span processors.

How Translation Works - Span Processors

Span processors are components that process spans before they are exported, allowing them to be modified, filtered, or transformed. These processors:

Map attribute names from source conventions to OpenInference conventions
Transform attribute values to match expected formats
Preserve all data while normalizing the structure

View OpenLIT Traces in Phoenix

Convert OpenLIT traces to OpenInference format using the OpenInferenceSpanProcessor from the openinference-instrumentation-openlit package.

OpenInference OpenLit Instrumentation

View on PyPI

Install Required Packages

Install the necessary packages:

pip install arize-phoenix opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-openlit openlit semantic-kernel

Start Phoenix

Start Phoenix in the background as a collector. By default, it listens on http://localhost:6006. You can visit the app via a browser at the same address.

phoenix serve

Set Up Tracer Provider and Span Processors

Configure the tracer provider and add the span processors. The OpenInferenceSpanProcessor converts OpenLIT traces to OpenInference format, and the BatchSpanProcessor exports them to Phoenix via the OTLP gRPC endpoint:

import os
import grpc
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from phoenix.otel import register
from openinference.instrumentation.openlit import OpenInferenceSpanProcessor

# Set your OpenAI API key
os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY"

# Set up the tracer provider
tracer_provider = register(
    project_name="default"  # Phoenix project name
)

# Add the OpenInference span processor first to convert OpenLIT traces
tracer_provider.add_span_processor(OpenInferenceSpanProcessor())
    
# Add the batch span processor to export traces to Phoenix (OTLP gRPC endpoint)
tracer_provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="http://localhost:4317",  # Phoenix OTLP gRPC endpoint (if using phoenix cloud, change to phoenix cloud endpoint from settings)
            headers={},
            compression=grpc.Compression.Gzip,
        )
    )
)

Initialize OpenLIT and Semantic Kernel

Initialize OpenLIT with the tracer and set up Semantic Kernel:

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
import openlit

# Initialize OpenLit tracer
tracer = tracer_provider.get_tracer(__name__)
openlit.init(tracer=tracer)

# Set up Semantic Kernel with OpenLIT
kernel = Kernel()
kernel.add_service(
    OpenAIChatCompletion(
        service_id="default",
        ai_model_id="gpt-4o-mini",
    ),
)

Run Query and View Traces

Invoke your model and view the converted traces in Phoenix:

# Define and invoke your model
result = await kernel.invoke_prompt(
    prompt="What is the national food of Yemen?",
    arguments={},
)

# Now view your converted OpenLIT traces in Phoenix!

The traces will be visible in the Phoenix UI at http://localhost:6006.

View OpenLLMetry Traces in Phoenix

Convert OpenLLMetry traces to OpenInference format using the OpenInferenceSpanProcessor from the openinference-instrumentation-openllmetry package.

OpenInference OpenLLMetry Instrumentation

View on PyPI

Install Required Packages

Install the necessary packages:

pip install arize-phoenix opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-openai openinference-instrumentation-openllmetry

Start Phoenix

Start Phoenix in the background as a collector. By default, it listens on http://localhost:6006. You can visit the app via a browser at the same address. (Phoenix does not send data over the internet. It only operates locally on your machine.)

phoenix serve

Set Up Tracer Provider and Span Processors

Configure the tracer provider and add the span processors. The OpenInferenceSpanProcessor converts OpenLLMetry traces to OpenInference format, and the BatchSpanProcessor exports them to Phoenix via the OTLP gRPC endpoint:

import os
import grpc
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from phoenix.otel import register
from openinference.instrumentation.openllmetry import OpenInferenceSpanProcessor

# Set your OpenAI API key
os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY"

# Set up the tracer provider
tracer_provider = register(
    project_name="default"  # Phoenix project name
)

# Add the OpenInference span processor first to convert OpenLLMetry traces
tracer_provider.add_span_processor(OpenInferenceSpanProcessor())
    
tracer_provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="http://localhost:4317",  # Phoenix OTLP gRPC endpoint (if using phoenix cloud, change to phoenix cloud endpoint from settings)
            headers={},
            compression=grpc.Compression.Gzip,
        )
    )
)

Initialize OpenAI Instrumentor for OpenLLMetry

Initialize the OpenAI instrumentor with the tracer provider to generate OpenLLMetry traces:

from opentelemetry.instrumentation.openai import OpenAIInstrumentor

OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

Run Query and View Traces

Invoke your model and view the converted traces in Phoenix:

import openai

# Define and invoke your OpenAI model
client = openai.OpenAI()

messages = [
    {"role": "user", "content": "What is the national food of Yemen?"}
]

response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
)

# Now view your converted OpenLLMetry traces in Phoenix!

The traces will be visible in the Phoenix UI at http://localhost:6006.

View OpenTelemetry GenAI Traces in Phoenix

Convert OpenTelemetry GenAI span attributes to OpenInference format using the @arizeai/openinference-genai package for TypeScript/JavaScript applications. This example:

Creates a custom TraceExporter that converts OpenTelemetry GenAI spans to OpenInference spans
Uses the custom exporter in a SpanProcessor
Exports traces to Phoenix

OpenInference GenAI Package

View on npm

Install Required Packages

Install the necessary packages:

pnpm add @opentelemetry/api @opentelemetry/core @opentelemetry/exporter-trace-otlp-proto @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/semantic-conventions @opentelemetry/resources @arizeai/openinference-genai

Start Phoenix

Start Phoenix in the background as a collector. By default, it listens on http://localhost:6006. You can visit the app via a browser at the same address.

phoenix serve

Create Custom TraceExporter

Create a custom TraceExporter file (e.g., openinferenceOTLPTraceExporter.ts) that converts the OpenTelemetry GenAI attributes to OpenInference attributes:

// openinferenceOTLPTraceExporter.ts
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
import type { ExportResult } from "@opentelemetry/core";

import { convertGenAISpanAttributesToOpenInferenceSpanAttributes } from "@arizeai/openinference-genai";
import type { Mutable } from "@arizeai/openinference-genai/types";

class OpenInferenceOTLPTraceExporter extends OTLPTraceExporter {
  export(
    spans: ReadableSpan[],
    resultCallback: (result: ExportResult) => void,
  ) {
    const processedSpans = spans.map((span) => {
      const processedAttributes =
        convertGenAISpanAttributesToOpenInferenceSpanAttributes(
          span.attributes,
        );
      // optionally you can replace the entire attributes object with the
      // processed attributes if you want _only_ the OpenInference attributes
      (span as Mutable<ReadableSpan>).attributes = {
        ...span.attributes,
        ...processedAttributes,
      };
      return span;
    });

    super.export(processedSpans, resultCallback);
  }
}

Set Up Tracer Provider with Span Processor

Use the custom exporter in a SpanProcessor and configure the tracer provider. Set the COLLECTOR_ENDPOINT environment variable to your Phoenix endpoint (e.g., http://localhost:6006 for local Phoenix):

// instrumentation.ts
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  NodeTracerProvider,
  BatchSpanProcessor,
} from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

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

import { OpenInferenceOTLPTraceExporter } from "./openinferenceOTLPTraceExporter";

const COLLECTOR_ENDPOINT = process.env.COLLECTOR_ENDPOINT;
const SERVICE_NAME = "openinference-genai-app";

export const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: SERVICE_NAME,
    [SEMRESATTRS_PROJECT_NAME]: SERVICE_NAME,
  }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OpenInferenceOTLPTraceExporter({
        url: `${COLLECTOR_ENDPOINT}/v1/traces`,
      }),
    ),
  ],
});

provider.register();

View Traces in Phoenix

Once your application is running and generating traces, the converted OpenTelemetry GenAI traces will be visible in the Phoenix UI. The custom exporter automatically converts GenAI span attributes to OpenInference format before exporting to Phoenix.

View OpenTelemetry GenAI Traces from Go in Phoenix

There is no Go equivalent of @arizeai/openinference-genai today, so the Go flow does not convert GenAI attributes to OpenInference in-process. Instead, emit GenAI-convention spans directly with the standard OpenTelemetry Go SDK; Phoenix ingests them as-is.

Spans emitted this way do not carry openinference.span.kind or structured llm.input_messages.* / llm.output_messages.* indexing. They appear in Phoenix and remain queryable by gen_ai.* attributes, but Phoenix UI features that key off OpenInference attributes will be reduced. For Go SDKs with dedicated OpenInference instrumentation (OpenAI, Anthropic), prefer those instead.

Install Required Packages

go get go.opentelemetry.io/otel
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp
go get go.opentelemetry.io/otel/sdk
go get go.opentelemetry.io/otel/semconv/v1.32.0

Configure the Tracer Provider

Point an OTLP/HTTP exporter at Phoenix. For Phoenix Cloud, set PHOENIX_COLLECTOR_ENDPOINT and PHOENIX_API_KEY.

import (
    "context"
    "os"
    "strings"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.32.0"
)

func phoenixTraceEndpoint(endpoint string) string {
    endpoint = strings.TrimRight(endpoint, "/")
    if strings.HasSuffix(endpoint, "/v1/traces") {
        return endpoint
    }
    return endpoint + "/v1/traces"
}

opts := []otlptracehttp.Option{
    otlptracehttp.WithEndpoint("localhost:6006"),
    otlptracehttp.WithURLPath("/v1/traces"),
    otlptracehttp.WithInsecure(),
}
if endpoint := os.Getenv("PHOENIX_COLLECTOR_ENDPOINT"); endpoint != "" {
    opts = []otlptracehttp.Option{
        otlptracehttp.WithEndpointURL(phoenixTraceEndpoint(endpoint)),
        otlptracehttp.WithHeaders(map[string]string{
            "Authorization": "Bearer " + os.Getenv("PHOENIX_API_KEY"),
        }),
    }
}

exporter, _ := otlptracehttp.New(ctx, opts...)
res, _ := resource.New(ctx, resource.WithAttributes(
    semconv.ServiceName("my-go-app"),
))
tp := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exporter),
    sdktrace.WithResource(res),
)
otel.SetTracerProvider(tp)

Emit a GenAI-Convention Span

Wrap each LLM call in a span and set the canonical gen_ai.* attributes using OpenTelemetry semantic-convention helpers where available.

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    semconv "go.opentelemetry.io/otel/semconv/v1.32.0"
    "go.opentelemetry.io/otel/trace"
)

tracer := otel.Tracer("my-go-app")
ctx, span := tracer.Start(ctx, "llm.generate",
    trace.WithAttributes(
        attribute.String("gen_ai.system", "gemini"),
        attribute.String("gen_ai.operation.name", "chat"),
        semconv.GenAIRequestModel("gemini-2.0-flash"),
    ),
)
defer span.End()

// ... make the LLM call ...

span.SetAttributes(
    semconv.GenAIResponseModel("gemini-2.0-flash"),
    semconv.GenAIUsageInputTokens(promptTokens),
    semconv.GenAIUsageOutputTokens(completionTokens),
)

For a worked end-to-end example using google.golang.org/genai, see Gemini Go SDK.

​Why Translation is Needed

​How Translation Works - Span Processors

​View OpenLIT Traces in Phoenix

OpenInference OpenLit Instrumentation

​View OpenLLMetry Traces in Phoenix

OpenInference OpenLLMetry Instrumentation

​View OpenTelemetry GenAI Traces in Phoenix

OpenInference GenAI Package

​View OpenTelemetry GenAI Traces from Go in Phoenix

​Learn More

Why Translation is Needed

How Translation Works - Span Processors

View OpenLIT Traces in Phoenix

View OpenLLMetry Traces in Phoenix

View OpenTelemetry GenAI Traces in Phoenix

View OpenTelemetry GenAI Traces from Go in Phoenix

Learn More