Documentation
¶
Overview ¶
Package otel provides OpenTelemetry integration for Phoenix.
This package is the Go equivalent of the Python phoenix-otel package, providing easy setup of OpenTelemetry tracing with Phoenix-aware defaults.
Quick Start ¶
import "github.com/agentplexus/go-phoenix/otel"
func main() {
// Register with Phoenix (sends traces to localhost:6006)
tp, err := otel.Register()
if err != nil {
log.Fatal(err)
}
defer tp.Shutdown(context.Background())
// Use the tracer
tracer := tp.Tracer("my-service")
ctx, span := tracer.Start(context.Background(), "my-operation")
defer span.End()
}
Production Configuration ¶
tp, err := otel.Register(
otel.WithEndpoint("https://app.phoenix.arize.com"),
otel.WithAPIKey("your-api-key"),
otel.WithProjectName("my-project"),
otel.WithBatch(true),
)
Environment Variables ¶
The following environment variables are supported:
- PHOENIX_COLLECTOR_ENDPOINT: Phoenix collector endpoint
- PHOENIX_PROJECT_NAME: Project name for traces
- PHOENIX_API_KEY: API key for authentication
- PHOENIX_CLIENT_HEADERS: Additional headers (W3C Baggage format)
- OTEL_EXPORTER_OTLP_ENDPOINT: Fallback OTLP endpoint
Index ¶
- Constants
- func AgentSpanAttributes() []attribute.KeyValue
- func ChainSpanAttributes() []attribute.KeyValue
- func LLMSpanAttributes(model, provider string, promptTokens, completionTokens int) []attribute.KeyValue
- func RetrieverSpanAttributes() []attribute.KeyValue
- func ToolSpanAttributes(name, description string) []attribute.KeyValue
- func WithInput(input string) attribute.KeyValue
- func WithLLMProvider(provider string) attribute.KeyValue
- func WithMetadata(metadata string) attribute.KeyValue
- func WithModelName(model string) attribute.KeyValue
- func WithOutput(output string) attribute.KeyValue
- func WithSessionID(id string) attribute.KeyValue
- func WithSpanKind(kind string) attribute.KeyValue
- func WithTokenCounts(prompt, completion, total int) []attribute.KeyValue
- func WithToolName(name string) attribute.KeyValue
- func WithUserID(id string) attribute.KeyValue
- type Config
- type Option
- func WithAPIKey(key string) Option
- func WithBatch(batch bool) Option
- func WithBatchSize(size int) Option
- func WithBatchTimeout(timeout time.Duration) Option
- func WithEndpoint(endpoint string) Option
- func WithGlobalProvider(global bool) Option
- func WithHeaders(headers map[string]string) Option
- func WithInsecure(insecure bool) Option
- func WithProjectName(name string) Option
- func WithProtocol(protocol Protocol) Option
- func WithServiceName(name string) Option
- func WithServiceVersion(version string) Option
- func WithSpaceID(spaceID string) Option
- type Protocol
- type TracerProvider
Constants ¶
const ( // SpanKindLLM indicates an LLM call span. SpanKindLLM = "LLM" // SpanKindChain indicates a chain/workflow span. SpanKindChain = "CHAIN" // SpanKindTool indicates a tool call span. SpanKindTool = "TOOL" // SpanKindAgent indicates an agent span. SpanKindAgent = "AGENT" // SpanKindRetriever indicates a retrieval span. SpanKindRetriever = "RETRIEVER" // SpanKindEmbedding indicates an embedding span. SpanKindEmbedding = "EMBEDDING" // SpanKindReranker indicates a reranker span. SpanKindReranker = "RERANKER" // SpanKindGuardrail indicates a guardrail span. SpanKindGuardrail = "GUARDRAIL" )
Span kind attributes for LLM operations.
const ( // OpenInferenceSpanKind is the span kind attribute key. OpenInferenceSpanKind = "openinference.span.kind" // Input/Output attributes InputValue = "input.value" InputMime = "input.mime_type" OutputValue = "output.value" OutputMime = "output.mime_type" // LLM attributes LLMModelName = "llm.model_name" LLMProvider = "llm.provider" LLMInvocationParams = "llm.invocation_parameters" LLMTokenCountPrompt = "llm.token_count.prompt" //nolint:gosec // Not a credential LLMTokenCountCompletion = "llm.token_count.completion" //nolint:gosec // Not a credential LLMTokenCountTotal = "llm.token_count.total" //nolint:gosec // Not a credential // Message attributes LLMInputMessages = "llm.input_messages" LLMOutputMessages = "llm.output_messages" // Tool attributes ToolName = "tool.name" ToolDescription = "tool.description" ToolParameters = "tool.parameters" // Retrieval attributes RetrievalDocuments = "retrieval.documents" // Embedding attributes EmbeddingModelName = "embedding.model_name" EmbeddingEmbeddings = "embedding.embeddings" EmbeddingText = "embedding.text" // Metadata attributes MetadataKey = "metadata" TagsKey = "tag.tags" // Session/Thread attributes SessionID = "session.id" UserID = "user.id" )
OpenInference attribute keys.
const ( EnvCollectorEndpoint = "PHOENIX_COLLECTOR_ENDPOINT" EnvProjectName = "PHOENIX_PROJECT_NAME" EnvAPIKey = "PHOENIX_API_KEY" EnvSpaceID = "PHOENIX_SPACE_ID" EnvClientHeaders = "PHOENIX_CLIENT_HEADERS" EnvGRPCPort = "PHOENIX_GRPC_PORT" // Standard OTEL fallback EnvOTELEndpoint = "OTEL_EXPORTER_OTLP_ENDPOINT" )
Environment variable names matching Phoenix Python SDK.
const ( DefaultEndpoint = "http://localhost:6006" DefaultProjectName = "default" DefaultGRPCPort = 4317 DefaultHTTPPath = "/v1/traces" )
Default values.
Variables ¶
This section is empty.
Functions ¶
func AgentSpanAttributes ¶
AgentSpanAttributes returns common attributes for an agent span.
func ChainSpanAttributes ¶
ChainSpanAttributes returns common attributes for a chain span.
func LLMSpanAttributes ¶
func LLMSpanAttributes(model, provider string, promptTokens, completionTokens int) []attribute.KeyValue
LLMSpanAttributes returns common attributes for an LLM span.
func RetrieverSpanAttributes ¶
RetrieverSpanAttributes returns common attributes for a retriever span.
func ToolSpanAttributes ¶
ToolSpanAttributes returns common attributes for a tool span.
func WithLLMProvider ¶
WithLLMProvider sets the LLM provider name.
func WithMetadata ¶
WithMetadata sets a metadata attribute as JSON string.
func WithModelName ¶
WithModelName sets the LLM model name.
func WithOutput ¶
WithOutput sets the output value attribute.
func WithSessionID ¶
WithSessionID sets the session ID attribute.
func WithSpanKind ¶
WithSpanKind sets the OpenInference span kind.
func WithTokenCounts ¶
WithTokenCounts sets the token count attributes.
func WithToolName ¶
WithToolName sets the tool name attribute.
func WithUserID ¶
WithUserID sets the user ID attribute.
Types ¶
type Config ¶
type Config struct {
// Endpoint is the Phoenix collector endpoint.
// For Phoenix Cloud, use https://app.phoenix.arize.com
Endpoint string
// SpaceID is the space identifier for Phoenix Cloud.
// When set, the endpoint is constructed as {Endpoint}/s/{SpaceID}.
SpaceID string
// ProjectName is the project name for traces.
ProjectName string
// APIKey is the API key for authentication.
APIKey string
// Headers are additional headers to send with requests.
Headers map[string]string
// Protocol specifies the transport protocol (http or grpc).
Protocol Protocol
// Batch enables batch span processing (recommended for production).
Batch bool
// BatchTimeout is the maximum time to wait before exporting a batch.
BatchTimeout time.Duration
// BatchSize is the maximum number of spans to batch.
BatchSize int
// SetGlobalProvider sets the tracer provider as global.
SetGlobalProvider bool
// ServiceName is the service name for the resource.
ServiceName string
// ServiceVersion is the service version for the resource.
ServiceVersion string
// Insecure disables TLS for gRPC connections.
Insecure bool
}
Config holds the configuration for Phoenix OTEL integration.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns a Config with default values and environment overrides.
func (*Config) EffectiveEndpoint ¶
EffectiveEndpoint returns the full endpoint with space ID if configured.
type Option ¶
type Option func(*Config)
Option configures the Phoenix OTEL integration.
func WithAPIKey ¶
WithAPIKey sets the API key for authentication. This is required for Arize cloud.
func WithBatchSize ¶
WithBatchSize sets the maximum number of spans to batch.
func WithBatchTimeout ¶
WithBatchTimeout sets the maximum time to wait before exporting a batch.
func WithEndpoint ¶
WithEndpoint sets the Phoenix collector endpoint.
Example endpoints:
- http://localhost:6006 (local Phoenix)
- https://app.phoenix.arize.com (Phoenix Cloud - requires SpaceID)
func WithGlobalProvider ¶
WithGlobalProvider sets whether to register as the global tracer provider. Defaults to true.
func WithHeaders ¶
WithHeaders sets additional headers to send with requests.
func WithInsecure ¶
WithInsecure disables TLS for gRPC connections.
func WithProjectName ¶
WithProjectName sets the project name for traces.
func WithProtocol ¶
WithProtocol sets the transport protocol. Use ProtocolHTTP, ProtocolGRPC, or ProtocolInfer.
func WithServiceName ¶
WithServiceName sets the service name for the resource.
func WithServiceVersion ¶
WithServiceVersion sets the service version for the resource.
func WithSpaceID ¶
WithSpaceID sets the space identifier for Phoenix Cloud. When using Phoenix Cloud (app.phoenix.arize.com), set this to your space ID. The endpoint will be constructed as {Endpoint}/s/{SpaceID}.
type TracerProvider ¶
type TracerProvider struct {
*sdktrace.TracerProvider
// contains filtered or unexported fields
}
TracerProvider wraps the OpenTelemetry TracerProvider with Phoenix-specific functionality.
func Register ¶
func Register(opts ...Option) (*TracerProvider, error)
Register creates and configures an OpenTelemetry TracerProvider for Phoenix.
This is the main entry point for Phoenix OTEL integration. It:
- Creates an OTLP HTTP exporter configured for Phoenix
- Sets up a TracerProvider with Phoenix resource attributes
- Optionally registers as the global tracer provider
Example:
tp, err := otel.Register(
otel.WithProjectName("my-app"),
otel.WithBatch(true),
)
if err != nil {
log.Fatal(err)
}
defer tp.Shutdown(context.Background())
func (*TracerProvider) Config ¶
func (tp *TracerProvider) Config() *Config
Config returns the configuration used by this tracer provider.
Source Files