From e6309fc57eadbe12d472391e88b597609d3c893e Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 2 Nov 2026 07:34:27 -0800 Subject: [PATCH 1/2] docs(openinference): add native Go tracing setup Exercise the exact guide with published floor/latest dependencies, real OTLP/HTTP exports, and the production ingestion converter. Keep manual-span privacy and single-provider ownership explicit. Co-Authored-By: Claude Code --- .github/workflows/openinference-go-docs.yml | 67 ++++ examples/import/openinference-go/go.mod | 32 ++ examples/import/openinference-go/go.sum | 65 ++++ .../import/openinference-go/guide_test.go | 304 ++++++++++++++++++ .../import/openinference-go/ingestion_test.go | 84 +++++ examples/import/openinference-go/latest.mod | 33 ++ examples/import/openinference-go/latest.sum | 63 ++++ src/lib/integrations.mjs | 2 +- .../integrations/import/openinference.mdx | 128 +++++++- 9 files changed, 770 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/openinference-go-docs.yml create mode 100644 examples/import/openinference-go/go.mod create mode 100644 examples/import/openinference-go/go.sum create mode 100644 examples/import/openinference-go/guide_test.go create mode 100644 examples/import/openinference-go/ingestion_test.go create mode 100644 examples/import/openinference-go/latest.mod create mode 100644 examples/import/openinference-go/latest.sum diff --git a/.github/workflows/openinference-go-docs.yml b/.github/workflows/openinference-go-docs.yml new file mode 100644 index 000000000..a1315fbcf --- /dev/null +++ b/.github/workflows/openinference-go-docs.yml @@ -0,0 +1,67 @@ +name: OpenInference Go documentation + +on: + pull_request: + branches: [main] + paths: + - src/pages/docs/integrations/import/openinference.mdx + - examples/import/openinference-go/** + - scripts/crewai-ingestion-check/** + - .github/workflows/openinference-go-docs.yml + +permissions: + contents: read + +jobs: + native-tracing: + name: Native Go tracing (${{ matrix.dependencies }}) + runs-on: ubuntu-latest + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + include: + - dependencies: floor + go: '1.25.0' + modfile: go.mod + - dependencies: latest + go: '1.26.0' + modfile: latest.mod + steps: + - uses: actions/checkout@v4 + - name: Check out the production ingestion contract + uses: actions/checkout@v4 + with: + repository: future-agi/future-agi + ref: 814b6c4e745e754dc2eeb43a4d238d318adc4daa + path: .test-deps/future-agi + sparse-checkout: fi-collector + persist-credentials: false + - uses: actions/setup-go@v5 + with: + go-version: ${{ matrix.go }} + cache-dependency-path: | + examples/import/openinference-go/*.sum + .test-deps/future-agi/fi-collector/go.sum + - name: Resolve released dependencies before denying outbound networking + run: | + (cd .test-deps/future-agi/fi-collector && go mod download) + (cd examples/import/openinference-go && go mod download -modfile=${{ matrix.modfile }}) + - name: Run exact guide, wire and production conversion tests on loopback only + env: + MODFILE: ${{ matrix.modfile }} + GOTOOLCHAIN: local + GOPROXY: 'off' + GOSUMDB: 'off' + GOWORK: 'off' + run: | + export INGESTION_CHECK="$RUNNER_TEMP/openinference-ingestion-check" + sudo --preserve-env=MODFILE,INGESTION_CHECK,GOTOOLCHAIN,GOPROXY,GOSUMDB,GOWORK env PATH="$PATH" HOME="$HOME" \ + unshare --net sh -ec ' + ip link set lo up + ROOT="$PWD" + (cd .test-deps/future-agi/fi-collector && go build -o "$INGESTION_CHECK" "$ROOT/scripts/crewai-ingestion-check/main.go") + cd examples/import/openinference-go + export GOFLAGS="-modfile=$MODFILE -mod=readonly" + go test -race -count=1 -v ./... + ' diff --git a/examples/import/openinference-go/go.mod b/examples/import/openinference-go/go.mod new file mode 100644 index 000000000..3b6271e39 --- /dev/null +++ b/examples/import/openinference-go/go.mod @@ -0,0 +1,32 @@ +module example.com/futureagi/openinference-go-docs + +go 1.25.0 + +require ( + github.com/Arize-ai/openinference/go/openinference-instrumentation v0.1.0 + go.opentelemetry.io/otel v1.43.0 + go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 + go.opentelemetry.io/otel/sdk v1.43.0 + go.opentelemetry.io/otel/trace v1.43.0 + go.opentelemetry.io/proto/otlp v1.10.0 + google.golang.org/protobuf v1.36.11 +) + +require ( + github.com/Arize-ai/openinference/go/openinference-semantic-conventions v0.1.0 // indirect + github.com/cenkalti/backoff/v5 v5.0.3 // indirect + github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/go-logr/logr v1.4.3 // indirect + github.com/go-logr/stdr v1.2.2 // indirect + github.com/google/uuid v1.6.0 // indirect + github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect + go.opentelemetry.io/auto/sdk v1.2.1 // indirect + go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0 // indirect + go.opentelemetry.io/otel/metric v1.43.0 // indirect + golang.org/x/net v0.52.0 // indirect + golang.org/x/sys v0.42.0 // indirect + golang.org/x/text v0.35.0 // indirect + google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9 // indirect + google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect + google.golang.org/grpc v1.80.0 // indirect +) diff --git a/examples/import/openinference-go/go.sum b/examples/import/openinference-go/go.sum new file mode 100644 index 000000000..49f44d2c4 --- /dev/null +++ b/examples/import/openinference-go/go.sum @@ -0,0 +1,65 @@ +github.com/Arize-ai/openinference/go/openinference-instrumentation v0.1.0 h1:4H11RI0TuG//y3V0gQZGWA+NZtqL75/UqwQG0r5GHjQ= +github.com/Arize-ai/openinference/go/openinference-instrumentation v0.1.0/go.mod h1:QZS8u/8HepkqrS3+CorX3vpuLuAVK+MJfLFUed5VHDo= +github.com/Arize-ai/openinference/go/openinference-semantic-conventions v0.1.0 h1:SpglqmI1af0vbVmULAR0WdZxxJ4czmQ6UStm5/TaJt0= +github.com/Arize-ai/openinference/go/openinference-semantic-conventions v0.1.0/go.mod h1:C5hLjt/dUbEb3pSkhNbLYu/xpu6HB0XHK6fZOiXXeR0= +github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM= +github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw= +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= +github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI= +github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= +github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= +github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs= +github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= +go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= +go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I= +go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0= +go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0 h1:88Y4s2C8oTui1LGM6bTWkw0ICGcOLCAI5l6zsD1j20k= +go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0/go.mod h1:Vl1/iaggsuRlrHf/hfPJPvVag77kKyvrLeD10kpMl+A= +go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 h1:3iZJKlCZufyRzPzlQhUIWVmfltrXuGyfjREgGP3UUjc= +go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0/go.mod h1:/G+nUPfhq2e+qiXMGxMwumDrP5jtzU+mWN7/sjT2rak= +go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM= +go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY= +go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg= +go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg= +go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw= +go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A= +go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A= +go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0= +go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g= +go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk= +go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= +go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= +golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0= +golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw= +golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo= +golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8= +golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA= +gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= +gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= +google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9 h1:VPWxll4HlMw1Vs/qXtN7BvhZqsS9cdAittCNvVENElA= +google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:7QBABkRtR8z+TEnmXTqIqwJLlzrZKVfAUm7tY3yGv0M= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 h1:m8qni9SQFH0tJc1X0vmnpw/0t+AImlSvp30sEupozUg= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8= +google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM= +google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4= +google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE= +google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/examples/import/openinference-go/guide_test.go b/examples/import/openinference-go/guide_test.go new file mode 100644 index 000000000..e332bcc58 --- /dev/null +++ b/examples/import/openinference-go/guide_test.go @@ -0,0 +1,304 @@ +package openinference_test + +import ( + "bytes" + "compress/gzip" + "context" + "io" + "net/http" + "net/http/httptest" + "os" + "os/exec" + "path/filepath" + "regexp" + "strings" + "testing" + "time" + + instrumentation "github.com/Arize-ai/openinference/go/openinference-instrumentation" + "go.opentelemetry.io/otel/attribute" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" + "go.opentelemetry.io/otel/propagation" + "go.opentelemetry.io/otel/sdk/resource" + sdktrace "go.opentelemetry.io/otel/sdk/trace" + "go.opentelemetry.io/otel/trace" + collector "go.opentelemetry.io/proto/otlp/collector/trace/v1" + common "go.opentelemetry.io/proto/otlp/common/v1" + tracepb "go.opentelemetry.io/proto/otlp/trace/v1" + "google.golang.org/protobuf/proto" +) + +const guidePath = "../../../src/pages/docs/integrations/import/openinference.mdx" + +type exportBatch struct { + spans []*tracepb.Span + wire []byte +} + +type receiver struct { + server *httptest.Server + spans chan exportBatch +} + +// Decode the real exporter's wire payload, not an in-memory SDK substitute. +func newReceiver(t *testing.T, encoding string) *receiver { + t.Helper() + r := &receiver{spans: make(chan exportBatch, 10)} + r.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.Method != http.MethodPost || req.URL.Path != "/tracer/v1/traces" { + t.Errorf("unexpected request: %s %s", req.Method, req.URL.Path) + } + for k, want := range map[string]string{ + "X-Api-Key": "synthetic-api-key", "X-Secret-Key": "synthetic-secret-key", + "Content-Type": "application/x-protobuf", "Content-Encoding": encoding, + } { + if got := req.Header.Get(k); got != want { + t.Errorf("header %s: got %q, want %q", k, got, want) + } + } + var body io.Reader = req.Body + if encoding == "gzip" { + z, err := gzip.NewReader(body) + if err != nil { + t.Error(err) + w.WriteHeader(http.StatusBadRequest) + return + } + defer z.Close() + body = z + } + data, err := io.ReadAll(body) + var export collector.ExportTraceServiceRequest + if err != nil { + t.Error(err) + w.WriteHeader(http.StatusBadRequest) + return + } + if err := proto.Unmarshal(data, &export); err != nil { + t.Error(err) + w.WriteHeader(http.StatusBadRequest) + return + } + var spans []*tracepb.Span + for _, rs := range export.ResourceSpans { + attrs := attributes(rs.Resource.Attributes) + for k, want := range map[string]string{ + "project_name": "my-openinference-project", "project_type": "observe", "service.name": "go-shop", + } { + if got := attrs[k].GetStringValue(); got != want { + t.Errorf("resource %s: got %q, want %q", k, got, want) + } + } + for _, scope := range rs.ScopeSpans { + spans = append(spans, scope.Spans...) + } + } + r.spans <- exportBatch{spans: spans, wire: data} + w.Header().Set("Content-Type", "application/x-protobuf") + w.WriteHeader(http.StatusOK) // Empty protobuf ExportTraceServiceResponse. + })) + t.Cleanup(r.server.Close) + return r +} + +func attributes(kvs []*common.KeyValue) map[string]*common.AnyValue { + result := make(map[string]*common.AnyValue, len(kvs)) + for _, kv := range kvs { + result[kv.Key] = kv.Value + } + return result +} + +func (r *receiver) collect(t *testing.T, want int) map[string]*tracepb.Span { + t.Helper() + result := make(map[string]*tracepb.Span) + count := 0 + timer := time.NewTimer(10 * time.Second) + defer timer.Stop() + for count < want { + select { + case batch := <-r.spans: + checkProductionConversion(t, batch) + for _, span := range batch.spans { + count++ + if _, exists := result[span.Name]; exists { + t.Fatalf("duplicate span %q", span.Name) + } + result[span.Name] = span + } + case <-timer.C: + t.Fatalf("received %d spans, want %d", count, want) + } + } + if count != want { + t.Fatalf("received %d spans, want %d", count, want) + } + select { + case extra := <-r.spans: + t.Fatalf("unexpected additional export: %d spans", len(extra.spans)) + default: + } + return result +} + +func checkTree(t *testing.T, spans map[string]*tracepb.Span, kinds map[string]string) { + t.Helper() + root := spans["quote_order"] + if root == nil || len(root.ParentSpanId) != 0 || len(root.TraceId) != 16 || len(root.SpanId) != 8 { + t.Fatal("missing or invalid root") + } + for name, kind := range kinds { + span := spans[name] + if span == nil { + t.Fatalf("missing span %q", name) + } + attrs := attributes(span.Attributes) + for k, want := range map[string]string{ + "openinference.span.kind": kind, "session.id": "order-123", "user.id": "shopper-42", + } { + if got := attrs[k].GetStringValue(); got != want { + t.Errorf("%s %s: got %q, want %q", name, k, got, want) + } + } + if name != "quote_order" && (!bytes.Equal(span.TraceId, root.TraceId) || !bytes.Equal(span.ParentSpanId, root.SpanId)) { + t.Errorf("%s is not a child in the root trace", name) + } + } +} + +func TestGuideInstallContract(t *testing.T) { + page, err := os.ReadFile(guidePath) + if err != nil { + t.Fatal(err) + } + latest, err := os.ReadFile("latest.mod") + if err != nil { + t.Fatal(err) + } + for _, module := range []string{ + "github.com/Arize-ai/openinference/go/openinference-instrumentation", + "go.opentelemetry.io/otel", + "go.opentelemetry.io/otel/sdk", + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp", + } { + version := regexp.MustCompile(`(?m)^\s*` + regexp.QuoteMeta(module) + `\s+(v\S+)`).FindSubmatch(latest) + if len(version) != 2 || !bytes.Contains(page, []byte(module+"@"+string(version[1]))) { + t.Errorf("guide install must match the latest fixture for %s", module) + } + } + if !bytes.Contains(page, []byte(`export FI_OTLP_ENDPOINT="https://api.futureagi.com/tracer/v1/traces"`)) { + t.Error("guide must configure the full Cloud trace endpoint") + } +} + +func TestGuideExample(t *testing.T) { + page, err := os.ReadFile(guidePath) + if err != nil { + t.Fatal(err) + } + blocks := regexp.MustCompile("(?s)```go\\n(.*?)\\n```").FindAllSubmatch(page, -1) + if len(blocks) != 1 { + t.Fatalf("guide must provide one runnable Go setup; found %d Go snippets", len(blocks)) + } + r := newReceiver(t, "") + file := filepath.Join(t.TempDir(), "main.go") + if err := os.WriteFile(file, blocks[0][1], 0600); err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + cmd := exec.CommandContext(ctx, "go", "run", file) + for _, key := range []string{"PATH", "HOME", "GOCACHE", "GOMODCACHE", "GOTOOLCHAIN", "TMPDIR", "GOTMPDIR", "GOFLAGS"} { + if value, ok := os.LookupEnv(key); ok { + cmd.Env = append(cmd.Env, key+"="+value) + } + } + cmd.Env = append(cmd.Env, + "GOPROXY=off", "GOSUMDB=off", "GOWORK=off", + "FI_OTLP_ENDPOINT="+r.server.URL+"/tracer/v1/traces", + "FI_API_KEY=synthetic-api-key", "FI_SECRET_KEY=synthetic-secret-key", + // Manual spans must not claim automatic redaction from these flags. + "OPENINFERENCE_HIDE_INPUTS=true", "OPENINFERENCE_HIDE_OUTPUTS=true", + ) + output, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("guide example failed: %v\n%s", err, output) + } + if strings.TrimSpace(string(output)) != "Order total: 30 USD" { + t.Fatalf("unexpected example output %q", output) + } + spans := r.collect(t, 2) + checkTree(t, spans, map[string]string{"quote_order": "AGENT", "calculate_total": "TOOL"}) + for _, span := range spans { + for _, kv := range span.Attributes { + if strings.HasPrefix(kv.Key, "input.") || strings.HasPrefix(kv.Key, "output.") || strings.HasPrefix(kv.Key, "llm.") { + t.Errorf("metadata-only guide unexpectedly records content: %s", kv.Key) + } + } + } +} + +func TestNativeContextAndLLMConformance(t *testing.T) { + for _, encoding := range []string{"", "gzip"} { + t.Run("protobuf/"+map[string]string{"": "plain", "gzip": "gzip"}[encoding], func(t *testing.T) { + r := newReceiver(t, encoding) + compression := otlptracehttp.NoCompression + if encoding == "gzip" { + compression = otlptracehttp.GzipCompression + } + exporter, err := otlptracehttp.New(context.Background(), + otlptracehttp.WithEndpointURL(r.server.URL+"/tracer/v1/traces"), + otlptracehttp.WithCompression(compression), + otlptracehttp.WithHeaders(map[string]string{"X-Api-Key": "synthetic-api-key", "X-Secret-Key": "synthetic-secret-key"}), + ) + if err != nil { + t.Fatal(err) + } + provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter), sdktrace.WithResource(resource.NewSchemaless( + attribute.String("project_name", "my-openinference-project"), + attribute.String("project_type", "observe"), attribute.String("service.name", "go-shop"), + ))) + ctx := instrumentation.WithSession(context.Background(), "order-123") + ctx = instrumentation.WithUser(ctx, "shopper-42") + ctx = instrumentation.WithMetadata(ctx, `{"team":"example"}`) + ctx = instrumentation.WithTags(ctx, "docs", "go") + tracer := provider.Tracer("guide-conformance") + ctx, root := tracer.Start(ctx, "quote_order", trace.WithAttributes(attribute.String("openinference.span.kind", "AGENT"))) + instrumentation.ApplyContextAttributes(ctx, root) + _, tool := tracer.Start(ctx, "calculate_total", trace.WithAttributes(attribute.String("openinference.span.kind", "TOOL"))) + instrumentation.ApplyContextAttributes(ctx, tool) + tool.End() + // Synthetic manual LLM attributes exercise the wire contract, not a model call. + _, llm := tracer.Start(ctx, "synthetic_completion", trace.WithAttributes( + attribute.String("openinference.span.kind", "LLM"), attribute.String("llm.model_name", "synthetic-model"), + attribute.Int("llm.token_count.prompt", 11), attribute.Int("llm.token_count.completion", 7), + attribute.Int("llm.token_count.total", 18), + )) + instrumentation.ApplyContextAttributes(ctx, llm) + llm.End() + root.End() + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := provider.Shutdown(shutdownCtx); err != nil { + t.Fatal(err) + } + spans := r.collect(t, 3) + checkTree(t, spans, map[string]string{"quote_order": "AGENT", "calculate_total": "TOOL", "synthetic_completion": "LLM"}) + attrs := attributes(spans["synthetic_completion"].Attributes) + if attrs["llm.model_name"].GetStringValue() != "synthetic-model" || attrs["llm.token_count.prompt"].GetIntValue() != 11 || attrs["llm.token_count.completion"].GetIntValue() != 7 || attrs["llm.token_count.total"].GetIntValue() != 18 { + t.Error("model/token attributes did not survive export") + } + for name, span := range spans { + attrs := attributes(span.Attributes) + if attrs["metadata"].GetStringValue() != `{"team":"example"}` || len(attrs["tag.tags"].GetArrayValue().GetValues()) != 2 { + t.Errorf("context metadata/tags missing on %s", name) + } + } + carrier := propagation.MapCarrier{} + propagation.Baggage{}.Inject(ctx, carrier) + if len(carrier) != 0 { + t.Errorf("OpenInference context leaked into baggage: %v", carrier) + } + }) + } +} diff --git a/examples/import/openinference-go/ingestion_test.go b/examples/import/openinference-go/ingestion_test.go new file mode 100644 index 000000000..419924e94 --- /dev/null +++ b/examples/import/openinference-go/ingestion_test.go @@ -0,0 +1,84 @@ +package openinference_test + +import ( + "bytes" + "context" + "encoding/hex" + "encoding/json" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + "time" +) + +// INGESTION_CHECK is built from the production collector, not a copied mapper. +// The workflow sets it for both dependency versions. A local wire-only test may +// omit it; that skip is explicit. Authentication/project resolution need a real +// deployment and are deliberately outside this synthetic conversion contract. +func checkProductionConversion(t *testing.T, batch exportBatch) { + t.Helper() + t.Run("production-conversion", func(t *testing.T) { + binary := os.Getenv("INGESTION_CHECK") + if binary == "" { + t.Skip("set INGESTION_CHECK to the compiled scripts/crewai-ingestion-check adapter") + } + filename := filepath.Join(t.TempDir(), "export.pb") + if err := os.WriteFile(filename, batch.wire, 0600); err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + output, err := exec.CommandContext(ctx, binary, filename).CombinedOutput() + if err != nil { + t.Fatalf("production conversion failed: %v\n%s", err, output) + } + lines := bytes.Split(bytes.TrimSpace(output), []byte("\n")) + if len(lines) != len(batch.spans) { + t.Fatalf("converted %d rows from %d spans", len(lines), len(batch.spans)) + } + for i, line := range lines { + var row map[string]any + if err := json.Unmarshal(line, &row); err != nil { + t.Fatal(err) + } + span := batch.spans[i] + attrs := attributes(span.Attributes) + for key, want := range map[string]any{ + "name": span.Name, + "id": hex.EncodeToString(span.SpanId), + "parent_span_id": hex.EncodeToString(span.ParentSpanId), + "service_name": "go-shop", + "observation_type": strings.ToLower(attrs["openinference.span.kind"].GetStringValue()), + "model": attrs["llm.model_name"].GetStringValue(), + "prompt_tokens": float64(attrs["llm.token_count.prompt"].GetIntValue()), + "completion_tokens": float64(attrs["llm.token_count.completion"].GetIntValue()), + "total_tokens": float64(attrs["llm.token_count.total"].GetIntValue()), + "input": "", "output": "", + } { + if got := row[key]; got != want { + t.Errorf("%s %s: got %v, want %v", span.Name, key, got, want) + } + } + traceID, ok := row["trace_id"].(string) + if !ok || strings.ReplaceAll(traceID, "-", "") != hex.EncodeToString(span.TraceId) { + t.Errorf("%s lost trace ID: %v", span.Name, row["trace_id"]) + } + for group, expected := range map[string]map[string]string{ + "resource_attrs": {"project_name": "my-openinference-project", "project_type": "observe"}, + "attrs_string": {"session.id": "order-123", "user.id": "shopper-42"}, + } { + values, ok := row[group].(map[string]any) + if !ok { + t.Fatalf("missing converted %s", group) + } + for key, want := range expected { + if got := values[key]; got != want { + t.Errorf("%s %s.%s: got %v, want %v", span.Name, group, key, got, want) + } + } + } + } + }) +} diff --git a/examples/import/openinference-go/latest.mod b/examples/import/openinference-go/latest.mod new file mode 100644 index 000000000..c77cc7ba1 --- /dev/null +++ b/examples/import/openinference-go/latest.mod @@ -0,0 +1,33 @@ +module example.com/futureagi/openinference-go-docs + +go 1.26.0 + +require ( + github.com/Arize-ai/openinference/go/openinference-instrumentation v0.1.2 + go.opentelemetry.io/otel v1.47.0 + go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.47.0 + go.opentelemetry.io/otel/sdk v1.47.0 + go.opentelemetry.io/otel/trace v1.47.0 + go.opentelemetry.io/proto/otlp v1.11.0 + google.golang.org/protobuf v1.36.12 +) + +require ( + github.com/Arize-ai/openinference/go/openinference-semantic-conventions v0.1.0 // indirect + github.com/cenkalti/backoff/v5 v5.0.3 // indirect + github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/go-logr/logr v1.4.4 // indirect + github.com/go-logr/stdr v1.2.2 // indirect + github.com/google/uuid v1.6.0 // indirect + github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 // indirect + go.opentelemetry.io/auto/sdk v1.2.1 // indirect + go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.47.0 // indirect + go.opentelemetry.io/otel/log v1.47.0 // indirect + go.opentelemetry.io/otel/metric v1.47.0 // indirect + golang.org/x/net v0.59.0 // indirect + golang.org/x/sys v0.48.0 // indirect + golang.org/x/text v0.42.0 // indirect + google.golang.org/genproto/googleapis/api v0.0.0-20260928230214-8a89bd6388cc // indirect + google.golang.org/genproto/googleapis/rpc v0.0.0-20260928230214-8a89bd6388cc // indirect + google.golang.org/grpc v1.83.2 // indirect +) diff --git a/examples/import/openinference-go/latest.sum b/examples/import/openinference-go/latest.sum new file mode 100644 index 000000000..248a13c93 --- /dev/null +++ b/examples/import/openinference-go/latest.sum @@ -0,0 +1,63 @@ +github.com/Arize-ai/openinference/go/openinference-instrumentation v0.1.2 h1:lz44nsgF9t6YE91Tdnb3YymMTfxIyN/K/rG9C+OmyQA= +github.com/Arize-ai/openinference/go/openinference-instrumentation v0.1.2/go.mod h1:QZS8u/8HepkqrS3+CorX3vpuLuAVK+MJfLFUed5VHDo= +github.com/Arize-ai/openinference/go/openinference-semantic-conventions v0.1.0 h1:SpglqmI1af0vbVmULAR0WdZxxJ4czmQ6UStm5/TaJt0= +github.com/Arize-ai/openinference/go/openinference-semantic-conventions v0.1.0/go.mod h1:C5hLjt/dUbEb3pSkhNbLYu/xpu6HB0XHK6fZOiXXeR0= +github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM= +github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw= +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= +github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8= +github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= +github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= +github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 h1:/Tnpcb2E0Pz/tN9s3bfEY2Q8ePCEX9iuS+cneUwncnw= +github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0/go.mod h1:zOBXOsUaBSjKgmH4OGzV1esUpR3oUSCPYVd2cUBjKYY= +github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE= +github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg= +go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= +go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= +go.opentelemetry.io/otel v1.47.0 h1:j7ALJ/zgkS7Z6aeJW09p8VC9804bC+PpeTfCD4XPnOM= +go.opentelemetry.io/otel v1.47.0/go.mod h1:8wS9O2qfXrYrzp6hIF/HOYJJf/wIhFPhR2xLuP+iXQU= +go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.47.0 h1:julhjPeUH/q/7hinbSdDdqt5h7Zw9YWmRlWRhI0jd54= +go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.47.0/go.mod h1:Ao2mz688LH/tFf0yMAenidq6k2YNSx6SIY2q6jDACck= +go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.47.0 h1:aXZXsZ012wOgVkqaiQv+Z/d8V0xKjmg70F6m4CE94lc= +go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.47.0/go.mod h1:ziu1gUIJhAaxM3EV1e3Ralk5AAyL1UOYz3lJJ4VSI38= +go.opentelemetry.io/otel/log v1.47.0 h1:cOTS1CcLbSQeZKanGJ+0JpF/+t4PELi3O3bbl2lqCcI= +go.opentelemetry.io/otel/log v1.47.0/go.mod h1:9byitSQ5pLC6PpqwGXjqdMKya6ZTswHRZh2vvXT33nw= +go.opentelemetry.io/otel/metric v1.47.0 h1:4PptaldXx3Eat1XjMZ68pPJEs5wrhlemctZE9a3UdWY= +go.opentelemetry.io/otel/metric v1.47.0/go.mod h1:ADGSXxRrXM6bjbvLo535EstVFlPpPYZm4LBKixjDHwU= +go.opentelemetry.io/otel/sdk v1.47.0 h1:zWXEr4j2lFefG87TU6Yg8a7ngfohIKFZHKp0Hf5hC6I= +go.opentelemetry.io/otel/sdk v1.47.0/go.mod h1:VUc24kiOeoGsxG8G9ULx3fWKvB7jMhnGE8Oi607lgR0= +go.opentelemetry.io/otel/sdk/metric v1.47.0 h1:lfISg2j93VT6yqdk9OfUaZmw/GfcZqCCV3jdXtsPnKw= +go.opentelemetry.io/otel/sdk/metric v1.47.0/go.mod h1:ypLp+mW1Nt2x+Szt3b5/i1syodyts49lMOwxpDI3VGw= +go.opentelemetry.io/otel/trace v1.47.0 h1:JOjX/Oci8K94QHddo+bbfya/Ai/nf6/dt9ZfrFNWSrM= +go.opentelemetry.io/otel/trace v1.47.0/go.mod h1:jNaSLa2PZEYFG6fRjJABAu+bw4FS08uDmPg28lTghu0= +go.opentelemetry.io/proto/otlp v1.11.0 h1:5rrYs0Ykyj50sdU/JU0x8etU+LubXWb+gED6TbEdMIk= +go.opentelemetry.io/proto/otlp v1.11.0/go.mod h1:SmVizdCOAm3XBtG1g1NnOdhW6jtddT72hLMhv8VwA8E= +go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= +go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= +go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= +go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= +golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues= +golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg= +golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo= +golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og= +golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI= +golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E= +gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= +gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= +google.golang.org/genproto/googleapis/api v0.0.0-20260928230214-8a89bd6388cc h1:rZHRz0ogq4Pid1IKtA/ivHi8XONVF5tqUQXA2TtgpkE= +google.golang.org/genproto/googleapis/api v0.0.0-20260928230214-8a89bd6388cc/go.mod h1:K/n0XLazCJHjD73YuMyNJsN38BPPy1kfFnKxUXaThFU= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260928230214-8a89bd6388cc h1:4bNTbnb44EqGVy9HaQxSY2jnafSUdgV3qHtedvNpDKg= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260928230214-8a89bd6388cc/go.mod h1:OaIUM3+LpYcK2GXM4FTmhWoIq371Owdr+Cc7/BsYHHc= +google.golang.org/grpc v1.83.2 h1:EManeRomTObA0BU7I8vXgg/78uE5MJ9M8B39EX2WscU= +google.golang.org/grpc v1.83.2/go.mod h1:YPI1hK3kDked6iHvgX3tR0y+nX/qpMFKhPgFsokw1S8= +google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc= +google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index ae406302f..54ea590c3 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -41,7 +41,7 @@ export const integrations = [ { id: 'cloudflare-think', name: 'Cloudflare Think', href: '/docs/integrations/frameworks/cloudflare-think', category: 'frameworks', summary: 'Forward native Worker agent spans through a privacy-filtering collector.', method: 'Native OTLP', logo: 'generic-framework' }, { id: 'openrouter-broadcast', name: 'OpenRouter Broadcast', href: '/docs/integrations/gateways/openrouter-broadcast', category: 'gateways', summary: 'Forward native Broadcast traces through a privacy-filtering collector.', method: 'Native OTLP', logo: 'generic-framework' }, { id: 'everos', name: 'EverOS', href: '/docs/integrations/traceai/everos', category: 'frameworks', summary: 'Export version-scoped memory-server spans to self-hosted Future AGI.', method: 'Native OTLP', logo: 'generic-framework' }, - { id: 'openinference', name: 'OpenInference', href: '/docs/integrations/import/openinference', category: 'frameworks', summary: 'Send the qualified Python OpenAI instrumentor spans over OTLP.', method: 'OpenInference SDK', logo: 'generic-framework' }, + { id: 'openinference', name: 'OpenInference', href: '/docs/integrations/import/openinference', category: 'frameworks', summary: 'Export Python OpenAI traces or manual Go application spans over OTLP.', method: 'OpenInference SDK', logo: 'generic-framework' }, { id: 'oh-my-pi', name: 'Oh My Pi', href: '/docs/integrations/coding-agents/oh-my-pi', category: 'coding', summary: 'Trace omp sessions with the version-scoped local hook.', method: 'omp hook', logo: 'generic-framework' }, { id: 'claude-code', name: 'Claude Code', href: '/docs/integrations/coding-agents/claude-code', category: 'coding', summary: 'Forward native CLI telemetry through a privacy-filtering collector.', method: 'Native OTLP', logo: 'generic-framework' }, { id: 'pi', name: 'Pi', href: '/docs/integrations/coding-agents/pi', category: 'coding', summary: 'Trace upstream Pi sessions through a local extension.', method: 'Pi extension', logo: 'generic-framework' }, diff --git a/src/pages/docs/integrations/import/openinference.mdx b/src/pages/docs/integrations/import/openinference.mdx index b2b548f20..8f0f62c59 100644 --- a/src/pages/docs/integrations/import/openinference.mdx +++ b/src/pages/docs/integrations/import/openinference.mdx @@ -1,11 +1,11 @@ --- title: "Send OpenInference spans to Future AGI" -description: "Export traces from the Python OpenInference OpenAI instrumentor to Future AGI over OTLP/HTTP." +description: "Export Python OpenAI traces or Go OpenInference spans to Future AGI with standard OpenTelemetry." --- -Send Python OpenAI traces from [OpenInference](https://github.com/Arize-ai/openinference) to **Observe** using a standard OTLP/HTTP exporter. Future AGI reads OpenInference's span kinds, model names, token counts and input/output attributes; no Future AGI instrumentation package is needed. +Send [OpenInference](https://github.com/Arize-ai/openinference) spans to **Observe** using a standard OTLP/HTTP exporter. Future AGI reads OpenInference's span kinds, model names, token counts and input/output attributes; no Future AGI instrumentation package is needed. -This guide covers OpenAI text calls. It does not configure sessions, users, embeddings, images, cost reporting or evaluations. Other OpenInference instrumentors may emit different attributes. +Choose the Python OpenAI setup below or the [Go setup](#go). The Python example traces OpenAI text calls; the Go example creates application spans with session and user context. Neither example configures embeddings, images, cost reporting or evaluations. The old Django OTLP route (`/api/public/otel/...`) is retired. A response from that path is not evidence that spans are ingested. Use the collector endpoint below. @@ -78,6 +78,120 @@ finally: `shutdown()` sends pending spans before this short-lived process exits. Open **Observe** in Future AGI and select `my-openinference-project` to inspect the trace. +## Go + +Use Go 1.26 or later for the dependency versions below. The [OpenInference Go helpers](https://github.com/Arize-ai/openinference/tree/main/go/openinference-instrumentation) carry session and user context; importing them does **not** instrument your application or configure an exporter. Use the standard OpenTelemetry SDK to create manual spans, or keep your existing OpenInference provider instrumentor. Do not wrap an already-instrumented model call in another LLM span. + +### Install Go dependencies + +In a new example directory, initialize a module and install the published dependencies. Skip `go mod init` in an existing Go module. + +```bash +mkdir openinference-example +cd openinference-example +go mod init example.com/openinference-example +go get github.com/Arize-ai/openinference/go/openinference-instrumentation@v0.1.2 \ + go.opentelemetry.io/otel@v1.47.0 \ + go.opentelemetry.io/otel/sdk@v1.47.0 \ + go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp@v1.47.0 +``` + +### Configure and run Go + +Set the **full trace endpoint**, including `/tracer/v1/traces` for Cloud. For self-hosted Future AGI, use the trace endpoint on your collector. This example does not call a model and needs no model-provider key. + +```bash +export FI_OTLP_ENDPOINT="https://api.futureagi.com/tracer/v1/traces" +export FI_API_KEY="your-futureagi-api-key" +export FI_SECRET_KEY="your-futureagi-secret-key" +``` + +Save this as `main.go`. It records an order calculation as an agent span with a tool child. It deliberately omits input and output content; use your own non-sensitive session and user identifiers in place of the example IDs. + +```go +package main + +import ( + "context" + "fmt" + "log" + "os" + "time" + + instrumentation "github.com/Arize-ai/openinference/go/openinference-instrumentation" + "go.opentelemetry.io/otel/attribute" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" + "go.opentelemetry.io/otel/sdk/resource" + sdktrace "go.opentelemetry.io/otel/sdk/trace" + "go.opentelemetry.io/otel/trace" +) + +func main() { + for _, name := range []string{"FI_OTLP_ENDPOINT", "FI_API_KEY", "FI_SECRET_KEY"} { + if os.Getenv(name) == "" { + log.Fatalf("set %s before starting the application", name) + } + } + exporter, err := otlptracehttp.New(context.Background(), + otlptracehttp.WithEndpointURL(os.Getenv("FI_OTLP_ENDPOINT")), + otlptracehttp.WithHeaders(map[string]string{ + "X-Api-Key": os.Getenv("FI_API_KEY"), + "X-Secret-Key": os.Getenv("FI_SECRET_KEY"), + }), + otlptracehttp.WithCompression(otlptracehttp.NoCompression), + ) + if err != nil { + log.Fatal(err) + } + provider := sdktrace.NewTracerProvider( + sdktrace.WithResource(resource.NewSchemaless( + attribute.String("service.name", "go-shop"), + attribute.String("project_name", "my-openinference-project"), + attribute.String("project_type", "observe"), + )), + sdktrace.WithBatcher(exporter), + ) + tracer := provider.Tracer("go-shop") + ctx := instrumentation.WithSession(context.Background(), "order-123") + ctx = instrumentation.WithUser(ctx, "shopper-42") + + ctx, agent := tracer.Start(ctx, "quote_order", trace.WithAttributes( + attribute.String("openinference.span.kind", "AGENT"), + )) + instrumentation.ApplyContextAttributes(ctx, agent) + _, tool := tracer.Start(ctx, "calculate_total", trace.WithAttributes( + attribute.String("openinference.span.kind", "TOOL"), + )) + instrumentation.ApplyContextAttributes(ctx, tool) + quantity, unitPrice := 3, 10 + total := quantity * unitPrice + tool.End() + agent.End() + fmt.Printf("Order total: %d USD\n", total) + + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := provider.Shutdown(shutdownCtx); err != nil { + log.Fatal(err) + } +} +``` + +```bash +go run . +``` + +Open **Observe**, select `my-openinference-project`, and open the `quote_order` trace to inspect its `calculate_total` child. Both spans carry `session.id=order-123` and `user.id=shopper-42`. + +### Use Go context in your application + +- Pass the context returned by `tracer.Start` to child operations to preserve parent links. Span attributes do not automatically inherit: call `ApplyContextAttributes(ctx, span)` for each manual span. OpenInference provider instrumentors apply these context attributes to their own spans. +- `WithSession`, `WithUser`, `WithMetadata` and `WithTags` store values in the local Go context, not in HTTP baggage. They do not automatically propagate session or user data to another service. +- If you already configure a tracer provider, add the exporter, batch processor and resource attributes to that provider's setup rather than creating a second tracing pipeline. Keep the same provider for your application and provider instrumentors. +- For manual LLM spans, use `openinference.span.kind=LLM`, `llm.model_name`, and numeric `llm.token_count.prompt` / `llm.token_count.completion` from the actual response. Do not invent usage for a failed call. Prefer the attributes emitted by your provider instrumentor when it already creates these spans. + +**Manual Go spans are not automatically redacted.** `ApplyContextAttributes` only copies context attributes; it does not apply `OPENINFERENCE_HIDE_*` settings to arbitrary `span.SetAttributes` calls, status messages or exceptions. Omit sensitive content from manual spans. OpenInference provider instrumentors have their own `TraceConfig` masking; configure that on the instrumentor before capturing content. + ## What is captured Future AGI maps OpenInference span attributes as follows: @@ -86,15 +200,15 @@ Future AGI maps OpenInference span attributes as follows: | --- | --- | --- | | `openinference.span.kind=AGENT` | agent | Parent of the others; shown in the trace tree and Agent Graph | | `RETRIEVER` | retriever | `input.value` is the query. `retrieval.documents.*` attributes are kept in the span's extra attributes, not in the output column | -| `LLM` (OpenAI instrumentor) | llm | `llm.model_name` becomes the model; `llm.token_count.prompt` / `completion` become prompt and completion tokens; total is their sum | -| `TOOL` (`tracer.tool` decorator) | tool | Inputs and outputs from `input.value` / `output.value` | +| `LLM` | llm | `llm.model_name` becomes the model; `llm.token_count.prompt` / `completion` become prompt and completion tokens; total is their sum | +| `TOOL` | tool | Inputs and outputs from `input.value` / `output.value`, when recorded | | Exception in a span | status ERROR | Message appears in the status message | An unrecognised `openinference.span.kind` value never makes the export fail; the span is stored with type `unknown`. `PROMPT` and `DECISION` are two such values in current OpenInference semantic conventions. ## Privacy -OpenInference captures content by default (prompts, completions, tool arguments and results, retrieval text). Turn it off with the OpenInference settings, not Future AGI's `FI_HIDE_*`: +The Python OpenInference OpenAI instrumentor captures content by default. Turn it off with the OpenInference settings, not Future AGI's `FI_HIDE_*`. These settings apply to instrumentor-generated attributes, not arbitrary manual Go spans: ```bash export OPENINFERENCE_HIDE_INPUTS=true @@ -119,4 +233,4 @@ These settings replace `input.value` and `output.value` with `__REDACTED__` and - Display of types follows Future AGI's own mapping of `openinference.span.kind`; there is no OpenInference-specific UI. - Retriever documents are not shown in the output column. -- This recipe supports the Python OpenAI instrumentor only. Other OpenInference instrumentors are outside its supported scope, even when they use the same attribute keys. +- The examples cover the Python OpenAI instrumentor and manual Go application spans. Other instrumentors may emit different attributes; importing the Go context helpers alone does not create LLM spans. From d238dbd301606a18192e8a5f5ee0d91367a19249 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 2 Nov 2026 08:11:18 -0800 Subject: [PATCH 2/2] fix(openinference): document explicit Go error status Qualify automatic error mapping and execute the documented manual error pattern on both dependency sets. Assert exported exception events and production-converted status, including nil-error and RecordError-only controls. Co-Authored-By: Claude Code --- .../import/openinference-go/errors_test.go | 79 +++++++++++++++++++ .../import/openinference-go/guide_test.go | 27 ++++--- .../import/openinference-go/ingestion_test.go | 2 + .../integrations/import/openinference.mdx | 15 +++- 4 files changed, 111 insertions(+), 12 deletions(-) create mode 100644 examples/import/openinference-go/errors_test.go diff --git a/examples/import/openinference-go/errors_test.go b/examples/import/openinference-go/errors_test.go new file mode 100644 index 000000000..230ccfddb --- /dev/null +++ b/examples/import/openinference-go/errors_test.go @@ -0,0 +1,79 @@ +package openinference_test + +import ( + "os" + "regexp" + "strings" + "testing" + + tracepb "go.opentelemetry.io/proto/otlp/trace/v1" +) + +func TestManualGoErrorGuidance(t *testing.T) { + page, err := os.ReadFile(guidePath) + if err != nil { + t.Fatal(err) + } + mainBlock := regexp.MustCompile("(?s)```go\\n(package main\\n.*?)\\n```").FindSubmatch(page) + errorBlock := regexp.MustCompile("(?s)### Record failed Go operations\\n.*?```go\\n(.*?)\\n```").FindSubmatch(page) + if len(mainBlock) != 2 || len(errorBlock) != 2 { + t.Fatal("guide must provide a runnable Go setup and explicit manual-error guidance") + } + for _, tc := range []struct { + name string + nilError bool + recordOnly bool + status tracepb.Status_StatusCode + message string + events int + }{ + {"record-error-and-status", false, false, tracepb.Status_STATUS_CODE_ERROR, "Order calculation failed", 1}, + {"no-error", true, false, tracepb.Status_STATUS_CODE_UNSET, "", 0}, + {"record-error-only", false, true, tracepb.Status_STATUS_CODE_UNSET, "", 1}, + } { + t.Run(tc.name, func(t *testing.T) { + snippet := string(errorBlock[1]) + imports := "\"context\"\n\"errors\"" + if tc.recordOnly { + // Negative control: RecordError alone must not imply ERROR status. + statusCall := regexp.MustCompile(`(?m)^\s*span\.SetStatus\(codes\.Error, "Order calculation failed"\)\s*$`) + if len(statusCall.FindAllString(snippet, -1)) != 1 { + t.Fatal("manual-error example must set a non-sensitive ERROR status") + } + snippet = statusCall.ReplaceAllString(snippet, "") + } else { + imports += "\n\"go.opentelemetry.io/otel/codes\"" + } + // Execute the exact documented error block inside the documented setup. + source := strings.Replace(string(mainBlock[1]), `"context"`, imports, 1) + operation := "err = errors.New(\"Synthetic operation failure\")\n" + if tc.nilError { + operation += "err = nil\n" + } + operation += "span := tool\n" + snippet + "\n tool.End()" + if strings.Count(source, " tool.End()") != 1 { + t.Fatal("expected one tool span end in guide setup") + } + source = strings.Replace(source, " tool.End()", operation, 1) + spans := runGuide(t, source) + checkTree(t, spans, map[string]string{"quote_order": "AGENT", "calculate_total": "TOOL"}) + if spans["quote_order"].GetStatus().GetCode() != tracepb.Status_STATUS_CODE_UNSET { + t.Fatal("child error must not automatically change the parent status") + } + span := spans["calculate_total"] + if span.GetStatus().GetCode() != tc.status || span.GetStatus().GetMessage() != tc.message { + t.Fatalf("got status=%s message=%q; want %s %q", span.GetStatus().GetCode(), span.GetStatus().GetMessage(), tc.status, tc.message) + } + if len(span.Events) != tc.events { + t.Fatalf("got %d events, want %d", len(span.Events), tc.events) + } + if tc.events > 0 { + event := span.Events[0] + if event.Name != "exception" || attributes(event.Attributes)["exception.message"].GetStringValue() != "Synthetic operation failure" { + t.Fatalf("missing recorded exception: %v", event) + } + } + t.Logf("status=%s status_message=%q exception_events=%d", span.GetStatus().GetCode(), span.GetStatus().GetMessage(), len(span.Events)) + }) + } +} diff --git a/examples/import/openinference-go/guide_test.go b/examples/import/openinference-go/guide_test.go index e332bcc58..809647ec9 100644 --- a/examples/import/openinference-go/guide_test.go +++ b/examples/import/openinference-go/guide_test.go @@ -196,13 +196,26 @@ func TestGuideExample(t *testing.T) { if err != nil { t.Fatal(err) } - blocks := regexp.MustCompile("(?s)```go\\n(.*?)\\n```").FindAllSubmatch(page, -1) + blocks := regexp.MustCompile("(?s)```go\\n(package main\\n.*?)\\n```").FindAllSubmatch(page, -1) if len(blocks) != 1 { t.Fatalf("guide must provide one runnable Go setup; found %d Go snippets", len(blocks)) } + spans := runGuide(t, string(blocks[0][1])) + checkTree(t, spans, map[string]string{"quote_order": "AGENT", "calculate_total": "TOOL"}) + for _, span := range spans { + for _, kv := range span.Attributes { + if strings.HasPrefix(kv.Key, "input.") || strings.HasPrefix(kv.Key, "output.") || strings.HasPrefix(kv.Key, "llm.") { + t.Errorf("metadata-only guide unexpectedly records content: %s", kv.Key) + } + } + } +} + +func runGuide(t *testing.T, source string) map[string]*tracepb.Span { + t.Helper() r := newReceiver(t, "") file := filepath.Join(t.TempDir(), "main.go") - if err := os.WriteFile(file, blocks[0][1], 0600); err != nil { + if err := os.WriteFile(file, []byte(source), 0600); err != nil { t.Fatal(err) } ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) @@ -227,15 +240,7 @@ func TestGuideExample(t *testing.T) { if strings.TrimSpace(string(output)) != "Order total: 30 USD" { t.Fatalf("unexpected example output %q", output) } - spans := r.collect(t, 2) - checkTree(t, spans, map[string]string{"quote_order": "AGENT", "calculate_total": "TOOL"}) - for _, span := range spans { - for _, kv := range span.Attributes { - if strings.HasPrefix(kv.Key, "input.") || strings.HasPrefix(kv.Key, "output.") || strings.HasPrefix(kv.Key, "llm.") { - t.Errorf("metadata-only guide unexpectedly records content: %s", kv.Key) - } - } - } + return r.collect(t, 2) } func TestNativeContextAndLLMConformance(t *testing.T) { diff --git a/examples/import/openinference-go/ingestion_test.go b/examples/import/openinference-go/ingestion_test.go index 419924e94..374d0e24e 100644 --- a/examples/import/openinference-go/ingestion_test.go +++ b/examples/import/openinference-go/ingestion_test.go @@ -55,6 +55,8 @@ func checkProductionConversion(t *testing.T, batch exportBatch) { "prompt_tokens": float64(attrs["llm.token_count.prompt"].GetIntValue()), "completion_tokens": float64(attrs["llm.token_count.completion"].GetIntValue()), "total_tokens": float64(attrs["llm.token_count.total"].GetIntValue()), + "status": strings.TrimPrefix(span.GetStatus().GetCode().String(), "STATUS_CODE_"), + "status_message": span.GetStatus().GetMessage(), "input": "", "output": "", } { if got := row[key]; got != want { diff --git a/src/pages/docs/integrations/import/openinference.mdx b/src/pages/docs/integrations/import/openinference.mdx index 8f0f62c59..cc462db80 100644 --- a/src/pages/docs/integrations/import/openinference.mdx +++ b/src/pages/docs/integrations/import/openinference.mdx @@ -192,6 +192,19 @@ Open **Observe**, select `my-openinference-project`, and open the `quote_order` **Manual Go spans are not automatically redacted.** `ApplyContextAttributes` only copies context attributes; it does not apply `OPENINFERENCE_HIDE_*` settings to arbitrary `span.SetAttributes` calls, status messages or exceptions. Omit sensitive content from manual spans. OpenInference provider instrumentors have their own `TraceConfig` masking; configure that on the instrumentor before capturing content. +### Record failed Go operations + +For a failed manual span, call both `RecordError` and `SetStatus` **before `span.End()`**. `RecordError` only adds an exception event; it does not set the span status to `ERROR`. Import `"go.opentelemetry.io/otel/codes"`, then use this pattern with your operation's `err` and active `span`: + +```go +if err != nil { + span.RecordError(err) + span.SetStatus(codes.Error, "Order calculation failed") +} +``` + +Use a non-sensitive status message. `RecordError` also exports the error's message in the exception event: sanitize `err` before recording it, or omit `RecordError` if it could contain secrets or personal data and set only the safe error status. A failed child does not automatically mark its parent as failed; set the parent's status too if the overall operation failed. + ## What is captured Future AGI maps OpenInference span attributes as follows: @@ -202,7 +215,7 @@ Future AGI maps OpenInference span attributes as follows: | `RETRIEVER` | retriever | `input.value` is the query. `retrieval.documents.*` attributes are kept in the span's extra attributes, not in the output column | | `LLM` | llm | `llm.model_name` becomes the model; `llm.token_count.prompt` / `completion` become prompt and completion tokens; total is their sum | | `TOOL` | tool | Inputs and outputs from `input.value` / `output.value`, when recorded | -| Exception in a span | status ERROR | Message appears in the status message | +| Span status set to `ERROR` | status ERROR | The supplied status description becomes the status message. The Python OpenAI instrumentor sets this on exceptions; for manual Go spans, [set the status explicitly](#record-failed-go-operations). An exception event alone does not set it | An unrecognised `openinference.span.kind` value never makes the export fail; the span is stored with type `unknown`. `PROMPT` and `DECISION` are two such values in current OpenInference semantic conventions.