tracingapi

type Backend struct {
	// Schema is the backend's API schema name, e.g. "OpenAI" or "AWSBedrock".
	Schema string
	// Name is the configured backend name, used when Schema has no well-known
	// mapping.
	Name string
}

type BackendRecorder interface {
	// RecordBackend records backend attributes to the span.
	RecordBackend(span trace.Span, backend Backend)
}

type BackendSpan interface {
	// RecordBackend records the resolved upstream backend on the span.
	RecordBackend(backend Backend)
}

type ChatCompletionRecorder = SpanRecorder[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]

type ChatCompletionSpan = Span[openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]

type ChatCompletionTracer = RequestTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]

type CompletionRecorder = SpanRecorder[openai.CompletionRequest, openai.CompletionResponse, openai.CompletionResponse]

type CompletionSpan = Span[openai.CompletionResponse, openai.CompletionResponse]

type CompletionTracer = RequestTracer[openai.CompletionRequest, openai.CompletionResponse, openai.CompletionResponse]

type CountTokensRecorder = SpanRecorder[anthropicschema.CountTokensRequest, anthropicschema.CountTokensResponse, struct{}]

type CountTokensSpan = Span[anthropicschema.CountTokensResponse, struct{}]

type CountTokensTracer = RequestTracer[anthropicschema.CountTokensRequest, anthropicschema.CountTokensResponse, struct{}]

type EmbeddingsRecorder = SpanRecorder[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]

type EmbeddingsSpan = Span[openai.EmbeddingResponse, struct{}]

type EmbeddingsTracer = RequestTracer[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]

type ImageGenerationRecorder = SpanRecorder[openai.ImageGenerationRequest, openai.ImageGenerationResponse, struct{}]

type ImageGenerationSpan = Span[openai.ImageGenerationResponse, struct{}]

type ImageGenerationTracer = RequestTracer[openai.ImageGenerationRequest, openai.ImageGenerationResponse, struct{}]

type MCPSpan interface {
	// RecordRouteToBackend records the backend that was routed to. It is called
	// once per backend, so for the methods that broadcast (initialize, the
	// list aggregations) it is called several times on the same span.
	RecordRouteToBackend(backend string, session string, isNew bool)
	// RecordClientSession records the client-facing MCP session, i.e. the
	// session between the MCP client and this gateway. Unlike the per-backend
	// session passed to RecordRouteToBackend, there is exactly one per request,
	// which is what the conventions mean by mcp.session.id.
	RecordClientSession(sessionID string)
	// AddEvent records a timestamped event (OTel annotation) on the span, giving
	// list operations a "begin"/"end" timeline alongside their attributes.
	AddEvent(name string)
	// RecordListResult records the size of an aggregated list result
	// (tools/list, resources/list, prompts/list, resources/templates/list) as a
	// count attribute. Content is never recorded; only the count is.
	RecordListResult(result any)
	// RecordToolCallResult records the tools/call result payload as the
	// gen_ai.tool.call.result attribute. The raw result JSON is recorded only
	// when message-content capture is enabled; otherwise the call is a no-op.
	RecordToolCallResult(resultJSON []byte)
	// EndSpan finalizes and ends the span.
	EndSpan()
	// EndSpanOnError finalizes and ends the span with an error status.
	EndSpanOnError(errType string, err error)
}

type MCPTracer interface {
	// StartSpanAndInjectMeta starts a span and injects trace context into
	// the _meta mutation.
	//
	// The parent trace context is taken from the HTTP headers first, then the JSON-RPC _meta on
	// top, so _meta wins when a client propagates in both. Either source alone works.
	//
	// Parameters:
	//   - ctx: might include a parent span context.
	//   - req: Incoming MCP request message.
	//   - param: Incoming MCP parameter used to extract parent trace context.
	//   - headers: Request HTTP request headers, also used to extract parent trace context.
	//
	// Returns nil unless the span is sampled.
	StartSpanAndInjectMeta(ctx context.Context, req *jsonrpc.Request, param mcp.Params, headers http.Header) MCPSpan
}

type MessageRecorder = SpanRecorder[anthropicschema.MessagesRequest, anthropicschema.MessagesResponse, anthropicschema.MessagesStreamChunk]

type MessageSpan = Span[anthropicschema.MessagesResponse, anthropicschema.MessagesStreamChunk]

type MessageTracer = RequestTracer[anthropicschema.MessagesRequest, anthropicschema.MessagesResponse, anthropicschema.MessagesStreamChunk]

type NoopChatCompletionTracer = NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]

type NoopChunkRecorder[ChunkT any] struct{}

type NoopCompletionTracer = NoopTracer[openai.CompletionRequest, openai.CompletionResponse, openai.CompletionResponse]

type NoopCountTokensTracer = NoopTracer[anthropicschema.CountTokensRequest, anthropicschema.CountTokensResponse, struct{}]

type NoopEmbeddingsTracer = NoopTracer[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]

type NoopImageGenerationTracer = NoopTracer[openai.ImageGenerationRequest, openai.ImageGenerationResponse, struct{}]

type NoopMCPTracer struct{}

type NoopMessageTracer = NoopTracer[anthropicschema.MessagesRequest, anthropicschema.MessagesResponse, anthropicschema.MessagesStreamChunk]

type NoopRerankTracer = NoopTracer[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]

type NoopResponsesInputTokensTracer = NoopTracer[openai.ResponseRequest, openai.ResponsesInputTokensResponse, struct{}]

type NoopResponsesTracer = NoopTracer[openai.ResponseRequest, openai.Response, openai.ResponseStreamEventUnion]

type NoopSpeechTracer = NoopTracer[openai.SpeechRequest, []byte, openai.SpeechStreamChunk]

type NoopTokenizeTracer = NoopTracer[tokenize.RequestUnion, tokenize.Response, struct{}]

type NoopTracer[ReqT any, RespT any, RespChunkT any] struct{}

type NoopTracing struct{}

type NoopTranscriptionTracer = NoopTracer[openai.TranscriptionRequest, openai.TranscriptionResponse, openai.TranscriptionStreamEvent]

type NoopTranslationTracer = NoopTracer[openai.TranslationRequest, openai.TranslationResponse, struct{}]

type RequestTracer[ReqT any, RespT any, RespChunkT any] interface {
	// StartSpanAndInjectHeaders starts a span and injects trace context into the header mutation.
	//
	// Parameters:
	//   - ctx: might include a parent span context.
	//   - headers: Incoming HTTP headers used to extract parent trace context.
	//   - headerMutation: The new span will have its context written to these headers unless NoopTracing is used.
	//   - req: The typed request used to detect streaming and record request attributes.
	//   - body: contains the original raw request body as a byte slice.
	//
	// Returns nil unless the span is sampled.
	StartSpanAndInjectHeaders(ctx context.Context, headers map[string]string, carrier propagation.TextMapCarrier, req *ReqT, body []byte) Span[RespT, RespChunkT]
}

type RerankRecorder = SpanRecorder[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]

type RerankSpan = Span[cohere.RerankV2Response, struct{}]

type RerankTracer = RequestTracer[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]

type ResponsesInputTokensRecorder = SpanRecorder[openai.ResponseRequest, openai.ResponsesInputTokensResponse, struct{}]

type ResponsesInputTokensSpan = Span[openai.ResponsesInputTokensResponse, struct{}]

type ResponsesInputTokensTracer = RequestTracer[openai.ResponseRequest, openai.ResponsesInputTokensResponse, struct{}]

type ResponsesRecorder = SpanRecorder[openai.ResponseRequest, openai.Response, openai.ResponseStreamEventUnion]

type ResponsesSpan = Span[openai.Response, openai.ResponseStreamEventUnion]

type ResponsesTracer = RequestTracer[openai.ResponseRequest, openai.Response, openai.ResponseStreamEventUnion]

type Span[RespT any, RespChunkT any] interface {
	// RecordResponseChunk records streaming response chunks. Implementations that do not support streaming should provide a no-op implementation.
	RecordResponseChunk(resp *RespChunkT)
	// RecordResponse records the response attributes to the span.
	RecordResponse(resp *RespT)
	// EndSpanOnError finalizes and ends the span with an error status.
	EndSpanOnError(statusCode int, body []byte)
	// EndSpan finalizes and ends the span.
	EndSpan()
}

type SpanRecorder[ReqT any, RespT any, RespChunkT any] interface {
	SpanResponseRecorder[RespT, RespChunkT]
	// StartParams returns the name and options to start the span with.
	//
	// Parameters:
	//   - req: contains the typed request.
	//   - body: contains the complete request body.
	//
	// Note: Avoid expensive data conversions since the span might not be sampled.
	StartParams(req *ReqT, body []byte) (spanName string, opts []trace.SpanStartOption)
	// RecordRequest records request attributes to the span.
	RecordRequest(span trace.Span, req *ReqT, body []byte)
}

type SpanResponseRecorder[RespT, RespChunkT any] interface {
	// RecordResponse records response attributes to the span.
	RecordResponse(span trace.Span, resp *RespT)
	// RecordResponseOnError ends recording the span with an error status.
	RecordResponseOnError(span trace.Span, statusCode int, body []byte)
	// RecordResponseChunks records response chunk attributes to the span for streaming response.
	RecordResponseChunks(span trace.Span, chunks []*RespChunkT)
}

type SpeechRecorder = SpanRecorder[openai.SpeechRequest, []byte, openai.SpeechStreamChunk]

type SpeechSpan = Span[[]byte, openai.SpeechStreamChunk]

type SpeechTracer = RequestTracer[openai.SpeechRequest, []byte, openai.SpeechStreamChunk]

type TokenizeRecorder = SpanRecorder[tokenize.RequestUnion, tokenize.Response, struct{}]

type TokenizeSpan = Span[tokenize.Response, struct{}]

type TokenizeTracer = RequestTracer[tokenize.RequestUnion, tokenize.Response, struct{}]

type Tracing interface {
	// ChatCompletionTracer creates spans for OpenAI chat completion requests on /chat/completions endpoint.
	ChatCompletionTracer() ChatCompletionTracer
	// ImageGenerationTracer creates spans for OpenAI image generation requests.
	ImageGenerationTracer() ImageGenerationTracer
	// CompletionTracer creates spans for OpenAI completion requests on /completions endpoint.
	CompletionTracer() CompletionTracer
	// EmbeddingsTracer creates spans for OpenAI embeddings requests on /embeddings endpoint.
	EmbeddingsTracer() EmbeddingsTracer
	// ResponsesTracer creates spans for OpenAI responses requests on /v1/responses endpoint.
	ResponsesTracer() ResponsesTracer
	// SpeechTracer creates spans for OpenAI speech synthesis requests on /v1/audio/speech endpoint.
	SpeechTracer() SpeechTracer
	// TranscriptionTracer creates spans for OpenAI audio transcription requests on /v1/audio/transcriptions endpoint.
	TranscriptionTracer() TranscriptionTracer
	// TranslationTracer creates spans for OpenAI audio translation requests on /v1/audio/translations endpoint.
	TranslationTracer() TranslationTracer
	// RerankTracer creates spans for rerank requests.
	RerankTracer() RerankTracer
	// MessageTracer creates spans for Anthropic messages requests.
	MessageTracer() MessageTracer
	// TokenizeTracer creates spans for tokenize requests.
	TokenizeTracer() TokenizeTracer
	// ResponsesInputTokensTracer creates spans for OpenAI /v1/responses/input_tokens requests.
	ResponsesInputTokensTracer() ResponsesInputTokensTracer
	// CountTokensTracer creates spans for Anthropic count tokens requests.
	CountTokensTracer() CountTokensTracer
	// MCPTracer creates spans for MCP requests.
	MCPTracer() MCPTracer
	// Shutdown shuts down the tracer, flushing any buffered spans.
	Shutdown(context.Context) error
}

type TranscriptionRecorder = SpanRecorder[openai.TranscriptionRequest, openai.TranscriptionResponse, openai.TranscriptionStreamEvent]

type TranscriptionSpan = Span[openai.TranscriptionResponse, openai.TranscriptionStreamEvent]

type TranscriptionTracer = RequestTracer[openai.TranscriptionRequest, openai.TranscriptionResponse, openai.TranscriptionStreamEvent]

type TranslationRecorder = SpanRecorder[openai.TranslationRequest, openai.TranslationResponse, struct{}]

type TranslationSpan = Span[openai.TranslationResponse, struct{}]

type TranslationTracer = RequestTracer[openai.TranslationRequest, openai.TranslationResponse, struct{}]