Documentation
¶
Overview ¶
Package export submits completed LLM Observability spans and evaluations directly to Datadog or through an Agent without starting a tracer.
Its public span types intentionally alias the canonical payload types used by the live tracer. This prevents the live and offline representations from drifting, but intake-driven field changes may therefore affect this API.
EXPERIMENTAL: This package may change or be removed without notice.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client submits completed LLM Obs spans and evaluations without starting a tracer.
func NewClient ¶
func NewClient(mlApp string, opts ...ClientOption) (*Client, error)
NewClient creates a client using global service, environment, and version defaults. Exactly one routing option is required.
func (*Client) SubmitEvaluations ¶
func (c *Client) SubmitEvaluations(ctx context.Context, evals []EvaluationMetric, opts ...SubmitEvaluationsOption) (*Result, error)
SubmitEvaluations submits LLM Obs evaluation metrics.
Example ¶
package main
import (
"context"
"fmt"
"log"
"github.com/DataDog/dd-trace-go/v2/llmobs/export"
)
func main() {
client, err := export.NewClient("my-ml-app",
export.WithAgentURL("http://localhost:8126"),
)
if err != nil {
log.Fatal(err)
}
score := 0.87
res, err := client.SubmitEvaluations(context.Background(), []export.EvaluationMetric{{
SpanID: "2345678901",
TraceID: "1234567890",
Label: "answer_quality",
ScoreValue: &score,
Assessment: "mostly correct",
Reasoning: "cited two of three sources",
}})
if err != nil {
log.Printf("submit evaluations: %v", err)
}
fmt.Println(res.Sent, res.Dropped, res.Failed)
}
Output:
func (*Client) SubmitSpans ¶
func (c *Client) SubmitSpans(ctx context.Context, events []SpanEvent, opts ...SubmitSpansOption) (*Result, error)
SubmitSpans submits completed LLM Obs spans.
Example ¶
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/DataDog/dd-trace-go/v2/llmobs/export"
)
func main() {
client, err := export.NewClient("my-ml-app",
export.WithDatadogIntake("datadoghq.com", "testtesttesttesttesttesttesttest"),
export.WithService("my-service"),
export.WithEnv("prod"),
)
if err != nil {
log.Fatal(err)
}
event := export.NewSpanEvent(
"1234567890",
"2345678901",
export.KindLLM,
export.WithTiming(time.Now().Add(-2*time.Second), 1500*time.Millisecond),
export.WithModel("gpt-4o", "openai"),
export.WithTextIO("hello", "hi there"),
)
event.Name = "chat"
event.Metrics = map[string]float64{"input_tokens": 12, "output_tokens": 8}
res, err := client.SubmitSpans(context.Background(), []export.SpanEvent{event})
if err != nil {
log.Printf("submit spans: %v", err)
}
fmt.Println(res.Sent, res.Dropped, res.Failed)
for _, ve := range res.ValidationErrors {
fmt.Println(ve.Index, ve.Code, ve.Reason)
}
}
Output:
type ClientOption ¶
type ClientOption func(*clientConfig) error
ClientOption configures a Client built by NewClient.
func WithAgentURL ¶
func WithAgentURL(agentURL string) ClientOption
WithAgentURL selects Agent EVP proxy routing.
func WithDatadogIntake ¶
func WithDatadogIntake(site, apiKey string) ClientOption
WithDatadogIntake selects direct intake routing. Empty values use the global site and API key configuration.
func WithEnv ¶
func WithEnv(env string) ClientOption
WithEnv overrides the global default environment.
func WithHTTPClient ¶
func WithHTTPClient(hc *http.Client) ClientOption
WithHTTPClient overrides the default HTTP client.
func WithService ¶
func WithService(service string) ClientOption
WithService sets the default service for spans without an explicit Service.
func WithVersion ¶
func WithVersion(version string) ClientOption
WithVersion overrides the global default version.
type DDAttributes ¶
type DDAttributes = transport.DDAttributes
DDAttributes contains Datadog correlation attributes for a span.
type ErrorCode ¶
type ErrorCode = illmobs.ExportValidationCode
ErrorCode classifies why a row was rejected.
const ( CodeMissingID ErrorCode = illmobs.ExportCodeMissingID CodeMissingKind ErrorCode = illmobs.ExportCodeMissingKind CodeInvalidKind ErrorCode = illmobs.ExportCodeInvalidKind CodeInvalidStatus ErrorCode = illmobs.ExportCodeInvalidStatus CodeInvalidTiming ErrorCode = illmobs.ExportCodeInvalidTiming CodeInvalidLink ErrorCode = illmobs.ExportCodeInvalidLink CodeMissingLabel ErrorCode = illmobs.ExportCodeMissingLabel CodeInvalidJoin ErrorCode = illmobs.ExportCodeInvalidJoin CodeInvalidValue ErrorCode = illmobs.ExportCodeInvalidValue CodeTypeMismatch ErrorCode = illmobs.ExportCodeTypeMismatch CodeNotEncodable ErrorCode = illmobs.ExportCodeNotEncodable CodeTooLarge ErrorCode = illmobs.ExportCodeTooLarge )
type ErrorMessage ¶
type ErrorMessage = transport.ErrorMessage
ErrorMessage contains error details for a span.
type EvaluationMetric ¶
type EvaluationMetric = illmobs.EvaluationConfig
EvaluationMetric is a caller-built LLM Obs evaluation metric.
When both TimestampMS and Timestamp are set, TimestampMS wins; when neither is set, the submission time is used. A non-empty MLApp takes precedence over WithCallMLApp and the client's ML app for that row.
type Kind ¶
Kind is the LLM Obs span kind.
const ( KindLLM Kind = transport.SpanKindLLM KindAgent Kind = transport.SpanKindAgent KindWorkflow Kind = transport.SpanKindWorkflow KindTask Kind = transport.SpanKindTask KindStep Kind = transport.SpanKindStep KindTool Kind = transport.SpanKindTool KindEmbedding Kind = transport.SpanKindEmbedding KindRetrieval Kind = transport.SpanKindRetrieval )
type MetricType ¶
type MetricType = transport.EvalMetricType
MetricType is the type of an evaluation metric value.
const ( MetricTypeCategorical MetricType = transport.EvalMetricTypeCategorical MetricTypeScore MetricType = transport.EvalMetricTypeScore MetricTypeBoolean MetricType = transport.EvalMetricTypeBoolean MetricTypeJSON MetricType = transport.EvalMetricTypeJSON )
type RequestResult ¶
type RequestResult struct {
// InputIndices identifies the input rows represented by this result.
InputIndices []int
StatusCode int
Attempts int
Retriable bool
ResponseSnippet string
Err error
}
RequestResult reports one sent or abandoned batch.
type Result ¶
type Result struct {
// Requests contains one result per sent or abandoned batch.
Requests []RequestResult
// ValidationErrors contains rows rejected before sending.
ValidationErrors []ValidationError
// Sent, Dropped, and Failed partition the input rows.
Sent int
Dropped int
Failed int
// contains filtered or unexported fields
}
Result reports a submission outcome.
type SpanEvent ¶
type SpanEvent = transport.LLMObsSpanEvent
SpanEvent is a completed LLM Obs span.
func NewSpanEvent ¶
func NewSpanEvent(traceID, spanID string, kind Kind, opts ...SpanEventOption) SpanEvent
NewSpanEvent constructs a completed span.
type SpanEventOption ¶
type SpanEventOption func(*SpanEvent)
SpanEventOption configures a span built by NewSpanEvent.
func WithMetadata ¶
func WithMetadata(metadata map[string]any) SpanEventOption
WithMetadata sets span metadata.
func WithModel ¶
func WithModel(name, provider string) SpanEventOption
WithModel sets model details for an LLM or embedding span.
func WithSpanError ¶
func WithSpanError(details ErrorMessage) SpanEventOption
WithSpanError marks the span as failed and sets its error details.
func WithTextIO ¶
func WithTextIO(input, output string) SpanEventOption
WithTextIO sets text input and output.
func WithTiming ¶
func WithTiming(start time.Time, duration time.Duration) SpanEventOption
WithTiming sets the span start time and duration. The start must resolve to a positive Unix timestamp. A zero duration is valid and omitted from the payload; negative durations are rejected during submission.
type Status ¶
type Status = transport.SpanStatus
Status is the terminal status of a span.
const ( StatusOK Status = transport.SpanStatusOK StatusError Status = transport.SpanStatusError )
type SubmitEvaluationsOption ¶
type SubmitEvaluationsOption func(*submitEvaluationsConfig)
SubmitEvaluationsOption customizes one evaluation submission.
func WithCallMLApp ¶
func WithCallMLApp(mlApp string) SubmitEvaluationsOption
WithCallMLApp sets a non-empty ML app override for one submission.
type SubmitSpansOption ¶
type SubmitSpansOption func(*submitSpansConfig)
SubmitSpansOption customizes a single Client.SubmitSpans call.
func WithCallService ¶
func WithCallService(service string) SubmitSpansOption
WithCallService sets the default service for spans in one submission.
type ValidationError ¶
type ValidationError = illmobs.ExportValidationError
ValidationError describes an input row that was not sent.
Source Files