Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions scripts/genkit-go-page.test.mjs
Original file line number Diff line number Diff line change
@@ -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);
}
});
25 changes: 25 additions & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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');
Expand Down
1 change: 1 addition & 0 deletions src/lib/integrations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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'] },
Expand Down
186 changes: 186 additions & 0 deletions src/pages/docs/integrations/traceai/genkit-go.mdx
Original file line number Diff line number Diff line change
@@ -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.

<Warning>
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.
</Warning>

```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.

<Note>
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.
</Note>

## 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/).
20 changes: 18 additions & 2 deletions src/pages/docs/sdk/tracing/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|----------|---------|---------|
Expand All @@ -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`.

Loading