feat(llmobs/export): offline LLM Obs span & evaluation export

Add a public llmobs/export package: an offline client for exporting
already-built LLM Observability spans and evaluations to Datadog intake
(direct) or through the Agent EVP proxy. This is an export/transport API,
not live instrumentation — it never starts the tracer, depends on the live
LLM Obs lifecycle, or replays payloads through StartSpan/Finish.

Implements the "Raw LLM Observability Export" part of the RFC. It lets
offline reconstruction tools (e.g. Trajectory) depend on the SDK for the
export mechanics — endpoint derivation, auth, HTTP, retry classification,
size handling, and structured per-request results — while keeping
reconstruction, projection, privacy, dedup and durable retry above the SDK.

- Client.ExportSpans / ExportEvaluations over caller-built SpanEvent /
  EvaluationMetric payloads, lowered to the LLM Obs wire shape.
- Caller-assigned trace/span/parent IDs preserved verbatim as opaque
  string payload fields; never routed into APM span IDs or sampling.
- Chunking (50 spans, 1000 evals per request), best-effort 5MB size guard
  (truncates input/output), and per-request ExportResult with validation
  attribution.
- Datadog route (DD-API-KEY) and Agent EVP route; reuses the internal LLM
  Obs transport for auth/routing/retry via a new transport.Post primitive.

Multi-destination is modeled as one isolated Client per destination. A
sibling otlp/export package is a stacked follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: khanayan123

CONTRIBUTING.md

@@ -296,6 +296,10 @@ Sample PR: <https://github.com/DataDog/dd-trace-go/pull/3365>
 
 Please view our contrib [README.md](contrib/README.md) for information on integrations. If you need support for a new integration, please file an issue to discuss before opening a PR.
 
+### Offline export clients
+
+The [`llmobs/export`](./llmobs/export) package provides an offline client for exporting already-built LLM Observability spans and evaluations directly to Datadog intake or through the Agent EVP proxy. It is an export/transport API — not live instrumentation — for tools that reconstruct telemetry offline and need the SDK to own endpoint derivation, auth, retry, size handling, and structured results. Caller-assigned IDs are preserved as opaque payload fields and are never routed into APM span IDs or sampling. A sibling `otlp/export` package for offline OTLP trace/metric/log export is planned as a follow-up.
+
 ### Working with environment variables
 
 When working with environment variables, direct use of `os.Getenv` and `os.LookupEnv` is not permitted. Instead, all environment variables must be validated against an [allowed list](./internal/env/supported_configurations.gen.go) using `env.Get` and `env.Lookup` from the [`internal/env`](./internal/env.go) package (or [`instrumentation/env`](./instrumentation/env/env.go) when working on contrib packages). This validation system helps us automatically detect newly introduced variables and ensures they are properly documented and tracked.

internal/llmobs/transport/transport.go

@@ -46,6 +46,15 @@ const (
 	subdomainDNE        = "api"
 )
 
+// Exported endpoint paths and EVP subdomains for offline export clients
+// (see llmobs/export). They identify the LLM Obs span and evaluation intakes.
+const (
+	PathLLMSpans      = endpointLLMSpan
+	SubdomainLLMSpans = subdomainLLMSpan
+	PathEvalMetrics   = endpointEvalMetric
+	SubdomainEval     = subdomainEvalMetric
+)
+
 const (
 	defaultSite            = "datadoghq.com"
 	defaultMaxRetries uint = 3
@@ -268,6 +277,86 @@ func (c *Transport) request(ctx context.Context, method, path, subdomain string,
 	return backoff.Retry(ctx, doRequest, backoff.WithBackOff(backoffStrat), backoff.WithMaxTries(defaultMaxRetries))
 }
 
+// Result reports the outcome of a single Post performed by an offline export
+// client. It surfaces the final HTTP status, the number of attempts made, the
+// (bounded) response body, and whether the failure class was retriable.
+type Result struct {
+	StatusCode int
+	Attempts   int
+	Body       []byte
+	Retriable  bool
+}
+
+// Post sends an already-encoded body to path under the given EVP subdomain using
+// the transport's routing (agentless direct intake vs. Agent EVP proxy), auth
+// headers, and bounded retry policy, and reports a structured Result.
+//
+// It is intended for offline export clients (llmobs/export) that build their own
+// payloads and need per-request outcomes. Retry classification matches the rest
+// of the transport (5xx/408/425/429 retriable, other 4xx permanent); callers
+// must not layer additional retry on top of it.
+func (c *Transport) Post(ctx context.Context, path, subdomain, contentType string, body []byte) (Result, error) {
+	urlStr := c.baseURL(subdomain) + path
+	backoffStrat := defaultBackoffStrategy()
+
+	var attempts int
+	var last Result
+
+	op := func() (Result, error) {
+		attempts++
+		req, err := http.NewRequestWithContext(ctx, http.MethodPost, urlStr, bytes.NewReader(body))
+		if err != nil {
+			return Result{}, backoff.Permanent(err)
+		}
+		req.Header.Set("Content-Type", contentType)
+		for key, val := range c.defaultHeaders {
+			req.Header.Set(key, val)
+		}
+		if !c.agentless {
+			req.Header.Set(headerEVPSubdomain, subdomain)
+		}
+
+		timeoutCtx, cancel := context.WithTimeout(ctx, defaultTimeout)
+		defer cancel()
+		req = req.WithContext(timeoutCtx)
+
+		resp, err := c.httpClient.Do(req)
+		if err != nil {
+			// Network/transport error is retriable, but a caller-cancelled or
+			// expired parent context is not a transient server condition.
+			last = Result{Retriable: ctx.Err() == nil}
+			return Result{}, err
+		}
+		defer resp.Body.Close()
+
+		code := resp.StatusCode
+		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		if code >= 200 && code <= 299 {
+			last = Result{StatusCode: code, Body: respBody}
+			return last, nil
+		}
+		if isRetriableStatus(code) {
+			last = Result{StatusCode: code, Body: respBody, Retriable: true}
+			return Result{}, fmt.Errorf("request failed with transient http status code: %d", code)
+		}
+		if code == http.StatusTooManyRequests {
+			last = Result{StatusCode: code, Body: respBody, Retriable: true}
+			wait := parseRetryAfter(resp.Header)
+			return Result{}, backoff.RetryAfter(int(wait.Seconds()))
+		}
+		last = Result{StatusCode: code, Body: respBody}
+		return Result{}, backoff.Permanent(fmt.Errorf("request failed with http status code: %d", code))
+	}
+
+	res, err := backoff.Retry(ctx, op, backoff.WithBackOff(backoffStrat), backoff.WithMaxTries(defaultMaxRetries))
+	if err != nil {
+		last.Attempts = attempts
+		return last, err
+	}
+	res.Attempts = attempts
+	return res, nil
+}
+
 func readErrorBody(resp *http.Response) string {
 	if resp == nil || resp.Body == nil {
 		return ""

llmobs/export/client.go

@@ -0,0 +1,142 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2026 Datadog, Inc.
+
+package export
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/DataDog/dd-trace-go/v2/internal/llmobs/config"
+	"github.com/DataDog/dd-trace-go/v2/internal/llmobs/transport"
+	"github.com/DataDog/dd-trace-go/v2/internal/version"
+)
+
+const (
+	defaultSite          = "datadoghq.com"
+	defaultSpanBatchSize = 50
+	defaultEvalBatchSize = 1000
+	defaultMaxSpanBytes  = 5 << 20 // 5 MiB
+)
+
+// Config configures a [Client]. A client targets exactly one destination; build
+// several clients for multi-destination export.
+//
+// Routing:
+//   - Datadog route (default): leave AgentURL empty and set Site + APIKey. The
+//     client posts directly to the LLM Obs intake derived from Site with the
+//     DD-API-KEY header.
+//   - Agent route: set AgentURL to a Datadog Agent base URL. The client posts
+//     through the Agent's EVP proxy and does not inject Datadog auth.
+type Config struct {
+	// Site is the Datadog site (e.g. "datadoghq.com"). Defaults to datadoghq.com.
+	Site string
+	// APIKey is the Datadog API key, required for the Datadog route.
+	APIKey string
+	// AgentURL, if set, routes export through the Agent EVP proxy instead of the
+	// direct Datadog intake (e.g. "http://localhost:8126").
+	AgentURL string
+
+	// Service, Env and Version are stamped onto spans when absent (Service as the
+	// top-level service field; Env and Version as env:/version: tags).
+	Service string
+	Env     string
+	Version string
+	// MLApp is the default ml_app for evaluations when a metric omits it.
+	MLApp string
+
+	// HTTPClient overrides the default HTTP client.
+	HTTPClient *http.Client
+
+	// SpanBatchSize is the max spans per request (default 50).
+	SpanBatchSize int
+	// EvalBatchSize is the max evaluations per request (default 1000).
+	EvalBatchSize int
+	// MaxSpanPayloadBytes is the max encoded span-request size before input/output
+	// values are truncated (default 5 MiB). Truncation is best-effort: only
+	// input/output are shrunk, so payloads dominated by other fields may still
+	// exceed the limit.
+	MaxSpanPayloadBytes int
+}
+
+// Client is an offline exporter for LLM Obs spans and evaluations. It is safe
+// for concurrent use.
+type Client struct {
+	transport *transport.Transport
+
+	service string
+	env     string
+	version string
+	mlApp   string
+
+	spanBatch    int
+	evalBatch    int
+	maxSpanBytes int
+}
+
+// New builds a Client from cfg.
+func New(cfg Config) (*Client, error) {
+	site := cfg.Site
+	if site == "" {
+		site = defaultSite
+	}
+	agentless := cfg.AgentURL == ""
+	if agentless && cfg.APIKey == "" {
+		return nil, errors.New("llmobs/export: APIKey is required for direct Datadog export; set AgentURL to route via the Agent")
+	}
+
+	var agentURL *url.URL
+	if cfg.AgentURL != "" {
+		// Trim a trailing slash so the EVP proxy path is not doubled.
+		u, err := url.Parse(strings.TrimRight(cfg.AgentURL, "/"))
+		if err != nil {
+			return nil, fmt.Errorf("llmobs/export: invalid AgentURL: %w", err)
+		}
+		agentURL = u
+	}
+
+	icfg := &config.Config{
+		ResolvedAgentlessEnabled: agentless,
+		TracerConfig: config.TracerConfig{
+			Site:       site,
+			APIKey:     cfg.APIKey,
+			AgentURL:   agentURL,
+			HTTPClient: cfg.HTTPClient,
+			Service:    cfg.Service,
+			Env:        cfg.Env,
+			Version:    cfg.Version,
+		},
+	}
+	if icfg.TracerConfig.HTTPClient == nil {
+		icfg.TracerConfig.HTTPClient = icfg.DefaultHTTPClient()
+	}
+
+	c := &Client{
+		transport:    transport.New(icfg),
+		service:      cfg.Service,
+		env:          cfg.Env,
+		version:      cfg.Version,
+		mlApp:        cfg.MLApp,
+		spanBatch:    orDefault(cfg.SpanBatchSize, defaultSpanBatchSize),
+		evalBatch:    orDefault(cfg.EvalBatchSize, defaultEvalBatchSize),
+		maxSpanBytes: orDefault(cfg.MaxSpanPayloadBytes, defaultMaxSpanBytes),
+	}
+	return c, nil
+}
+
+func orDefault(v, def int) int {
+	if v <= 0 {
+		return def
+	}
+	return v
+}
+
+// tracerVersion is the value stamped into _dd.tracer_version.
+func tracerVersion() string {
+	return version.Tag
+}

llmobs/export/doc.go

@@ -0,0 +1,26 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2026 Datadog, Inc.
+
+// Package export provides an offline client for exporting already-built LLM
+// Observability spans and evaluations to Datadog.
+//
+// It is an offline export API, not a live instrumentation API: it does not start
+// the tracer, does not depend on the live LLM Obs lifecycle, and never replays
+// payloads through StartSpan/Finish. It is intended for tools that reconstruct
+// telemetry offline (for example, rebuilding finished agent sessions from logs)
+// and need the SDK to own the export mechanics — endpoint derivation, auth,
+// HTTP transport, retry classification, size handling, and structured results.
+//
+// Caller-assigned IDs (trace_id, span_id, parent_id) are preserved verbatim as
+// LLM Obs payload fields. They are opaque strings (decimal uint64 strings are
+// valid; 128-bit hex is not required) and are never routed into APM span IDs,
+// APM trace IDs, or sampling.
+//
+// Multi-destination routing is modeled as one isolated [Client] per destination:
+// construct N clients, each with its own site, API key, service and defaults.
+// The client does not deduplicate, spool, or durably retry — callers retain
+// ownership of reconstruction, projection, privacy filtering, deterministic ID
+// generation, dedup, and outbox/backfill behavior.
+package export