diff --git a/scripts/genkit-go-page.test.mjs b/scripts/genkit-go-page.test.mjs new file mode 100644 index 000000000..87e46b3d1 --- /dev/null +++ b/scripts/genkit-go-page.test.mjs @@ -0,0 +1,41 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; + +const read = file => fs.readFileSync(new URL(`../${file}`, import.meta.url), 'utf8'); +const guide = read('src/pages/docs/integrations/traceai/genkit-go.mdx'); +const reference = read('src/pages/docs/sdk/tracing/environment-variables.mdx'); + +test('Genkit Go and the shared reference scope privacy to supported coarse switches', () => { + assert.doesNotMatch(reference, /All languages read from the same set/); + assert.match(reference, /Support varies by language and integration/); + assert.match(reference, /## Genkit Go privacy/); + assert.match(guide, /environment-variables#genkit-go-privacy/); + for (const page of [guide, reference]) { + for (const flag of ['FI_HIDE_INPUTS', 'FI_HIDE_OUTPUTS', 'FI_HIDE_ERROR_DETAILS', 'FI_HIDE_INPUT_MESSAGES', 'FI_HIDE_OUTPUT_MESSAGES']) { + assert.ok(page.includes(flag), flag); + } + assert.match(page, /[Gg]ranular privacy flags[\s\S]*?have no effect in this adapter/); + assert.match(page, /system instructions/); + assert.match(page, /[Kk]eep `FI_HIDE_ERROR_DETAILS=true`/); + assert.match(page, /[Gg]ranular flags do not enable this default|They also do not enable the default error redaction/); + assert.match(page, /false`[\s\S]*?even (?:with|when) a coarse hide switch/); + assert.match(page, /console output/); + } + assert.match(guide, /error details are hidden only if `FI_HIDE_INPUTS` or `FI_HIDE_OUTPUTS` is true/); + assert.match(reference, /True when either coarse hide switch is true; otherwise False/); + assert.match(reference, /`ConfigFromEnv\(\)` reads only these three privacy switches/); + assert.match(reference, /`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, not `FI_BASE_URL`/); +}); + +test('Genkit Go pins its maintained adapter and uses the current Gemini replacement', () => { + assert.match(guide, /github\.com\/future-agi\/traceAI\/go\/genkit@v0\.1\.0/); + assert.doesNotMatch(guide, /genkit@(?:dev|main|latest)/); + assert.match(guide, /ai\.WithModelName\("googleai\/gemini-3\.5-flash-lite"\)/); + assert.doesNotMatch(guide, /gemini-2\.5-flash/); + assert.match(guide, /ContentCapturingMode: otelgenai\.NoContent/); + assert.match(guide, /CaptureActionIO:\s+false/); + for (const flag of ['FI_HIDE_INPUTS', 'FI_HIDE_OUTPUTS', 'FI_HIDE_ERROR_DETAILS']) { + assert.ok(guide.includes(`export ${flag}=true`), flag); + } +}); diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index af4de1ed2..9d69c0769 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -3,6 +3,7 @@ import './azure-openai-java.test.mjs'; import './langsmith-page.test.mjs'; import './vercel-platform-page.test.mjs'; import './scalekit-page.test.mjs'; +import './genkit-go-page.test.mjs'; import test from 'node:test'; import assert from 'node:assert/strict'; import fs from 'node:fs'; @@ -335,6 +336,30 @@ test('public prose and catalog labels contain no internal QA label or Alpha rele assert.equal(publicProse('Beta. `pkg==1.0.0-alpha`\n```python\nmodel="alpha"\n```\n'),'Beta. \n\n'); }); +test('Genkit Go uses native spans with an export-time privacy boundary', () => { + const guide = read('src/pages/docs/integrations/traceai/genkit-go.mdx'); + const entry = integrations.find(item => item.id === 'genkit-go'); + assert.equal(entry?.method, 'OpenTelemetry'); + for (const contract of [ + 'github.com/firebase/genkit/go@v1.14.0', + 'github.com/future-agi/traceAI/go/genkit@v0.1.0', + 'FI_HIDE_INPUTS=true', 'FI_HIDE_OUTPUTS=true', 'FI_HIDE_ERROR_DETAILS=true', + 'traceaigenkit.NewExporter(exporter, traceaigenkit.ConfigFromEnv())', + 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.futureagi.com/tracer/v1/traces"', + '"X-Api-Key"', '"X-Secret-Key"', + 'attribute.String("project_name", os.Getenv("FI_PROJECT_NAME"))', + 'attribute.String("project_type", "observe")', + 'ContentCapturingMode: otelgenai.NoContent', 'CaptureActionIO: false', + 'DisableMetrics: true', 'tracing.SetInstrumentation(otelgenai.New(', + 'genkit.Init(ctx', 'errors.Join(err, tp.Shutdown(shutdownCtx))', + ]) assert.ok(guide.includes(contract), contract); + assert.match(guide, /strips input, output, and error details/); + assert.match(guide, /unwrapped exporter bypasses privacy controls/); + assert.match(guide, /raw action data, including inline media/); + assert.match(guide, /Do not combine `otelgenai`/); + assert.doesNotMatch(guide, /traceAI-genkit-go|copy.*instrumentation helper/i); +}); + test('Temporal Go uses the official extension and authenticated traces-only OTLP export', () => { const page = read('src/pages/docs/integrations/frameworks/temporal-go.mdx'); const catalog = integrations.find(i => i.id === 'temporal-go'); diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index c89079b3d..fb90092ab 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -71,6 +71,7 @@ export const integrations = [ { id: 'novita-ai', name: 'Novita AI', href: '/docs/integrations/providers/novita-ai', category: 'providers', summary: 'Trace Novita chat completions from your Python app.', method: 'OpenAI client', logo: 'novita' }, { id: 'litellm-sdk', name: 'LiteLLM SDK', href: '/docs/integrations/traceai/litellm', category: 'frameworks', summary: 'Instrument LiteLLM calls in your Python application.', method: 'traceAI SDK', logo: 'litellm', aliases: ['traceAI-litellm', 'client'] }, + { id: 'genkit-go', name: 'Genkit Go', href: '/docs/integrations/traceai/genkit-go', category: 'frameworks', summary: 'Export native Go model, tool, and flow traces.', method: 'OpenTelemetry', logo: 'generic-framework', aliases: ['Firebase Genkit', 'Golang', 'GenAI'] }, { id: 'langchain', name: 'LangChain', href: '/docs/integrations/traceai/langchain', category: 'frameworks', summary: 'Trace chains, retrievers, tools and model calls.', method: 'traceAI SDK', logo: 'langchain' }, { id: 'langgraph', name: 'LangGraph', href: '/docs/integrations/traceai/langgraph', category: 'frameworks', summary: 'Follow agent graph execution and tool calls.', method: 'traceAI SDK', logo: 'langgraph' }, { id: 'llamaindex', name: 'LlamaIndex', href: '/docs/integrations/traceai/llamaindex', category: 'frameworks', summary: 'Trace retrieval and generation in RAG applications.', method: 'traceAI SDK', logo: 'llamaindex', aliases: ['RAG'] }, diff --git a/src/pages/docs/integrations/traceai/genkit-go.mdx b/src/pages/docs/integrations/traceai/genkit-go.mdx new file mode 100644 index 000000000..2a8ffb78f --- /dev/null +++ b/src/pages/docs/integrations/traceai/genkit-go.mdx @@ -0,0 +1,186 @@ +--- +title: "Genkit Go" +description: "Send Genkit Go model calls, tool executions, and flow spans to Future AGI with native OpenTelemetry and the standard OTLP HTTP trace exporter." +--- + +Send your Genkit Go application's native spans to Future AGI without adding model wrappers. A maintained exporter adapter applies the three coarse privacy switches described below before export. + +## Prerequisites + +- Go 1.25 or later and Genkit Go 1.14.0. +- Your Future AGI API key and secret key from [API keys](/docs/admin-settings/api-keys). +- A Gemini API key with access to `gemini-3.5-flash-lite` for the example. You can keep your existing Genkit model plugin instead. + +## Install the packages + +In a new application directory, initialize a Go module and install Genkit and the OpenTelemetry trace exporter: + +```bash +go mod init example.com/genkit-menu +go get github.com/firebase/genkit/go@v1.14.0 \ + go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp@v1.46.0 \ + github.com/future-agi/traceAI/go/genkit@v0.1.0 +``` + +For an existing application, skip `go mod init` and use your existing module. Use the released adapter version and commit the resulting `go.mod` and `go.sum` to pin it. + +## Configure authentication + +```bash +export FI_API_KEY="your-futureagi-api-key" +export FI_SECRET_KEY="your-futureagi-secret-key" +export FI_PROJECT_NAME="genkit-go-app" +export FI_HIDE_INPUTS=true +export FI_HIDE_OUTPUTS=true +export FI_HIDE_ERROR_DETAILS=true +export GEMINI_API_KEY="your-gemini-api-key" +export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.futureagi.com/tracer/v1/traces" +``` + +Use the **trace-specific** endpoint variable. The generic `OTEL_EXPORTER_OTLP_ENDPOINT` appends `/v1/traces`, so putting the full trace URL there produces the wrong path. Future AGI accepts OTLP traces, not OpenTelemetry logs or metrics. + +The example maps your Future AGI variables to `X-Api-Key`, `X-Secret-Key`, and the `project_name` resource attribute. The stock exporter does not read `FI_*` variables automatically. + +## Trace a Genkit flow + +Save the following as `main.go`. It configures an application-owned trace provider before `genkit.Init`, then runs a flow that suggests a vegetarian menu. + + + Native Genkit alone ignores `FI_HIDE_*`. Keep the exporter adapter below in place: it strips input, output, and error details from exported spans using only `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, and `FI_HIDE_ERROR_DETAILS`. Granular privacy flags such as `FI_HIDE_INPUT_MESSAGES` and `FI_HIDE_OUTPUT_MESSAGES` have no effect in this adapter; use the coarse switches instead. See the [Genkit Go privacy reference](/docs/sdk/tracing/environment-variables#genkit-go-privacy) for their defaults. Avoid putting sensitive data in custom attributes, span names, resource attributes, or telemetry logs; these are not covered by the switches. Do not configure another unwrapped exporter or Genkit telemetry plugin to send the same spans. + + +```go +package main + +import ( + "context" + "errors" + "fmt" + "os" + "time" + + "github.com/firebase/genkit/go/ai" + "github.com/firebase/genkit/go/core/tracing" + "github.com/firebase/genkit/go/genkit" + "github.com/firebase/genkit/go/plugins/googlegenai" + "github.com/firebase/genkit/go/plugins/otelgenai" + traceaigenkit "github.com/future-agi/traceAI/go/genkit" + "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" +) + +func main() { + if err := run(); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func run() (err error) { + for _, name := range []string{"FI_API_KEY", "FI_SECRET_KEY", "FI_PROJECT_NAME", "GEMINI_API_KEY", "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"} { + if os.Getenv(name) == "" { + return fmt.Errorf("set %s before starting the application", name) + } + } + ctx := context.Background() + exporter, err := otlptracehttp.New(ctx, + 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 { + return err + } + tp := sdktrace.NewTracerProvider( + sdktrace.WithBatcher(traceaigenkit.NewExporter(exporter, traceaigenkit.ConfigFromEnv())), + sdktrace.WithResource(resource.NewSchemaless( + attribute.String("service.name", "genkit-go-app"), + attribute.String("project_name", os.Getenv("FI_PROJECT_NAME")), + attribute.String("project_type", "observe"), + )), + ) + defer func() { + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = errors.Join(err, tp.Shutdown(shutdownCtx)) + }() + + tracing.SetInstrumentation(otelgenai.New(&otelgenai.Options{ + TracerProvider: tp, + ContentCapturingMode: otelgenai.NoContent, + CaptureActionIO: false, + EmitToolSpans: true, + DisableMetrics: true, + })) + g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{})) + flow := genkit.DefineFlow(g, "suggestMenu", func(ctx context.Context, cuisine string) (string, error) { + return genkit.GenerateText(ctx, g, + ai.WithModelName("googleai/gemini-3.5-flash-lite"), + ai.WithPrompt("Suggest three vegetarian dishes for a %s dinner.", cuisine), + ) + }) + requestCtx, cancel := context.WithTimeout(ctx, 60*time.Second) + defer cancel() + menu, err := flow.Run(requestCtx, "Mediterranean") + if err != nil { + return err + } + fmt.Println(menu) + return nil +} +``` + +```bash +go mod tidy +go run . +``` + +Shutdown uses a fresh, bounded context so the final spans can flush even when a request fails or is cancelled. + +If your application already owns an OpenTelemetry provider, wrap its trace exporter with `traceaigenkit.NewExporter` and pass that provider through `otelgenai.Options.TracerProvider`. Wrap only once; exporting the same spans through an unwrapped exporter bypasses privacy controls and creates duplicates. Keep one provider lifecycle rather than creating and shutting down a provider for every request. + + + Do not combine `otelgenai` with Genkit's Firebase or Google Cloud telemetry plugins, legacy `OTelInstrumentation`, or an additional wrapper around the same model calls. The telemetry plugins use a different attribute encoding; stacking instrumentors can produce duplicate spans. Genkit's Developer UI has a separate telemetry feed and its own content handling. + + +## Open your traces + +Open your project in [Future AGI](https://app.futureagi.com). Find the `suggestMenu` trace and expand its model call to inspect the model name, token counts, timing, and status. + +With `EmitToolSpans: true`, tools defined through Genkit emit `execute_tool` spans. Flows, generation orchestration, retrievers, and embedders remain generic action spans. They do not provide dedicated retrieval-document or embedding-vector views through this configuration. + +## Capture model messages + +To include model messages as trace attributes, change the content option before initializing Genkit: + +```go +ContentCapturingMode: otelgenai.SpanOnly, +``` + +This adds JSON `gen_ai.input.messages`, `gen_ai.output.messages`, and `gen_ai.system_instructions` attributes to model spans. The exporter adapter removes input messages and system instructions while `FI_HIDE_INPUTS=true`, and output messages while `FI_HIDE_OUTPUTS=true`. Unset only the coarse switch for content you intend to send; `FI_HIDE_INPUT_MESSAGES` and `FI_HIDE_OUTPUT_MESSAGES` are not supported substitutes. + +Keep `FI_HIDE_ERROR_DETAILS=true` even when opting into messages: provider errors can quote prompts or responses. When this variable is unset, error details are hidden only if `FI_HIDE_INPUTS` or `FI_HIDE_OUTPUTS` is true; granular flags do not enable this default. Setting `FI_HIDE_ERROR_DETAILS=false` explicitly allows error text through, even with a coarse hide switch enabled. The switches filter exported spans, not your application's console output or logs. + +`EventOnly` sends content through OpenTelemetry logs, which this trace exporter does not filter and Future AGI does not ingest. + +Keep `CaptureActionIO: false`. It is independent of the model content setting and can export raw action data, including inline media and requests embedded in responses. `SpanOnly` does not enable raw tool arguments or results. + +## Troubleshooting + +### No traces arrive + +Check the trace-specific endpoint, both Future AGI credentials, and the `project_name` and `project_type: observe` resources. Install the instrumentation before `genkit.Init`, and let provider shutdown finish before the process exits. + +### Messages are absent + +The example explicitly uses `NoContent`. Set `SpanOnly` and unset the relevant `FI_HIDE_INPUTS` or `FI_HIDE_OUTPUTS` switch if you want model message attributes. Setting `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` alone does not override the explicit option in this example. + +### Token totals differ from your provider's invoice + +Native spans report the usage supplied by each model turn. Cache-write and provider-total usage are not exported by this Genkit version. Do not use these spans as a billing ledger. + +For native instrumentation options, see [Genkit's OpenTelemetry GenAI guide](https://genkit.dev/docs/go/observability/otel-genai-semantic-conventions/). diff --git a/src/pages/docs/sdk/tracing/environment-variables.mdx b/src/pages/docs/sdk/tracing/environment-variables.mdx index 76cdb75a9..9b26674f7 100644 --- a/src/pages/docs/sdk/tracing/environment-variables.mdx +++ b/src/pages/docs/sdk/tracing/environment-variables.mdx @@ -3,8 +3,7 @@ title: "Environment variables" description: "Environment variables that configure traceAI tracing." --- - -All languages read from the same set of environment variables: +The traceAI SDKs use `FI_*` environment variables for authentication and tracing configuration. Support varies by language and integration; native OpenTelemetry exporters do not read these variables automatically. In particular, the [Genkit Go adapter supports only three privacy switches](#genkit-go-privacy), not the granular controls in this reference. | Variable | Purpose | Default | |----------|---------|---------| @@ -25,4 +24,21 @@ All languages read from the same set of environment variables: | `FI_HIDE_LLM_INVOCATION_PARAMETERS` | Redact model parameters | False | | `FI_BASE64_IMAGE_MAX_LENGTH` | Max base64 image chars | 32000 | | `FI_PII_REDACTION` | Auto-mask PII (Python) | False | +| `FI_HIDE_ERROR_DETAILS` | Remove error text from exported spans | Integration-specific; see below for Genkit Go | + +## Genkit Go privacy + +The [Genkit Go integration](/docs/integrations/traceai/genkit-go) uses `github.com/future-agi/traceAI/go/genkit` to filter native `otelgenai` spans. Its `ConfigFromEnv()` reads only these three privacy switches, once when the exporter is constructed: + +| Variable | Effect when true | Default | +|----------|------------------|---------| +| `FI_HIDE_INPUTS` | Remove input messages, system instructions, stop sequences, and action inputs | False | +| `FI_HIDE_OUTPUTS` | Remove output messages and action outputs | False | +| `FI_HIDE_ERROR_DETAILS` | Remove span status descriptions and error/exception text | True when either coarse hide switch is true; otherwise False | + +Granular privacy flags, including `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_IMAGES`, `FI_HIDE_INPUT_TEXT`, `FI_HIDE_OUTPUT_TEXT`, `FI_HIDE_EMBEDDING_VECTORS`, and `FI_HIDE_LLM_INVOCATION_PARAMETERS`, have no effect in this adapter. They also do not enable the default error redaction. Use `FI_HIDE_INPUTS` and `FI_HIDE_OUTPUTS` to hide messages, including system instructions on the input side. + +Keep `FI_HIDE_ERROR_DETAILS=true` when enabling message capture. Explicitly setting it to `false` overrides the default even when a coarse hide switch is true, so error text can expose prompts or responses. These switches filter exported spans, not application console output, logs, custom attributes, span names, or resource attributes. Keep Genkit's `CaptureActionIO: false` and avoid additional unwrapped exporters. + +The guide maps `FI_API_KEY`, `FI_SECRET_KEY`, and `FI_PROJECT_NAME` in application code. Configure its OTLP HTTP endpoint with `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, not `FI_BASE_URL`.