From ed76b9e8a0e43fffe40f469ed2b6c316416eedec Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Fri, 16 Oct 2026 05:03:03 -0700 Subject: [PATCH 1/5] docs(integrations): Anthropic Go SDK tracing (TH-8272) New page for the traceAI Go middleware for anthropic-sdk-go (traceAI PR #259): install, OTLP/HTTP export to Future AGI, the span and its attributes, the SDK's own span, FI_HIDE_* privacy settings, limitations and troubleshooting. Alpha, verified through a stand-in endpoint (local proxy with real Claude responses). Co-Authored-By: Claude Opus 5.5 --- .../integrations/traceai/anthropic-go.mdx | 225 ++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 src/pages/docs/integrations/traceai/anthropic-go.mdx diff --git a/src/pages/docs/integrations/traceai/anthropic-go.mdx b/src/pages/docs/integrations/traceai/anthropic-go.mdx new file mode 100644 index 000000000..8c4ee6b00 --- /dev/null +++ b/src/pages/docs/integrations/traceai/anthropic-go.mdx @@ -0,0 +1,225 @@ +--- +title: "Anthropic Go SDK tracing with Future AGI" +description: "Trace anthropic-sdk-go Messages calls with the traceAI Go middleware: one LLM span per call, streaming included, with model, tokens, tool calls and session. Content is captured by default and turned off with the FI_HIDE_* variables." +--- + +## About + +[anthropic-sdk-go](https://github.com/anthropics/anthropic-sdk-go) is Anthropic's official Go SDK. The traceAI module `github.com/future-agi/traceAI/go/anthropic` is a client middleware for it. You add it once, with `option.WithMiddleware`, when you create the client, and every `Messages.New` and `Messages.NewStreaming` call made with that client becomes one LLM span in Future AGI: + +``` +weather-agent AGENT your code (optional) +├── anthropic.messages.create LLM model, tokens, request and response, tool call +├── execute_tool get_weather TOOL your code (optional) +└── anthropic.messages.create LLM streamed answer: still one span +``` + +The module only uses the OpenTelemetry API. You export the spans with the standard OpenTelemetry OTLP/HTTP exporter, which sends them to Future AGI with your keys. + + +**Alpha, verified through a stand-in endpoint.** The module was tested end to end with anthropic-sdk-go v1.82.0 against a Future AGI collector, with the Anthropic API **stood in** by a local proxy: the SDK talked to the proxy, which answered with real Claude model responses (`claude-haiku-4-5-20251001`) and, in one run, with a non-Anthropic model through its Messages translation. It has not yet been run against `api.anthropic.com` with an Anthropic API key. The middleware does not read or change the base URL or the API key, so only the endpoint differs. + + +This page is not the same as: + +- **[Anthropic (Python and TypeScript)](/docs/integrations/traceai/anthropic)** and **[Anthropic (Java)](/docs/integrations/traceai/java/anthropic)**. Those instrument the other official SDKs. This module is for Go only and does not change them. +- **Claude Agent SDK, Claude Code and Claude Managed Agents**. Those are agent products with their own telemetry. This page covers plain Messages API calls from a Go program. + +| | | +| --- | --- | +| Tested with | anthropic-sdk-go **v1.82.0** (latest on 2026-10-16), Go 1.24.3 and 1.27.2, OpenTelemetry Go v1.33.0 and v1.47.0 | +| Requires | anthropic-sdk-go v1.82.0 or later (`go get` raises an older version), Go 1.24 or later | +| Status | Alpha. Not yet run against `api.anthropic.com` (see the warning) | +| Source | [go/anthropic](https://github.com/future-agi/traceAI/tree/dev/go/anthropic) in traceAI | + +## 1. Install + +```bash +go get github.com/future-agi/traceAI/go/anthropic@dev +go get github.com/anthropics/anthropic-sdk-go@latest +go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp +``` + + +The module ships with [traceAI PR #259](https://github.com/future-agi/traceAI/pull/259) and has no release tag yet, so install it from a branch. Until the PR is merged into `dev`, use `@feat/th-8272-anthropic-go` instead of `@dev`. After the first `go/anthropic/v0.x` tag you can use `@latest`. + + +## 2. Set environment variables + +```bash +export ANTHROPIC_API_KEY="your-anthropic-api-key" +export FI_API_KEY="your-futureagi-api-key" +export FI_SECRET_KEY="your-futureagi-secret-key" +``` + +anthropic-sdk-go reads `ANTHROPIC_API_KEY` (and `ANTHROPIC_BASE_URL`, if you use a gateway) itself. The Future AGI keys go only to the trace exporter, never on a request to Anthropic. + +## 3. Export to Future AGI and add the middleware + +```go +package main + +import ( + "context" + "fmt" + "log" + "os" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" + "go.opentelemetry.io/otel" + "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" + + traceaianthropic "github.com/future-agi/traceAI/go/anthropic" +) + +func main() { + ctx := context.Background() + + // Future AGI needs both keys as headers and project_name as a resource attribute. + exporter, err := otlptracehttp.New(ctx, + otlptracehttp.WithEndpointURL("https://api.futureagi.com/tracer/v1/traces"), + 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) + } + tp := sdktrace.NewTracerProvider( + sdktrace.WithBatcher(exporter), + sdktrace.WithResource(resource.NewSchemaless( + attribute.String("project_name", "my-chatbot"), + attribute.String("project_type", "observe"), + attribute.String("service.name", "my-chatbot"), + )), + ) + // Flush the last batch before the process exits. + defer tp.Shutdown(context.Background()) + otel.SetTracerProvider(tp) + + // Add the middleware once, on the client. + client := anthropic.NewClient(option.WithMiddleware(traceaianthropic.Middleware())) + + // Optional: group calls into a session and tag your end user. + ctx = traceaianthropic.ContextWithSessionID(ctx, "session-123") + ctx = traceaianthropic.ContextWithUserID(ctx, "user-42") + + msg, err := client.Messages.New(ctx, anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet5_5, + MaxTokens: 256, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(msg.Content[0].Text) +} +``` + +For a self-hosted Future AGI, replace `https://api.futureagi.com` with your instance's base URL. Keep the path `/tracer/v1/traces`. + +`defer tp.Shutdown(...)` matters: the batch processor exports in the background, and a short program that exits without shutting the provider down sends nothing. If your program calls `log.Fatal` or `os.Exit`, deferred calls do not run, so return from a function that holds the `defer` first. + +## 4. Run a complete example + +[`go/anthropic/example`](https://github.com/future-agi/traceAI/tree/dev/go/anthropic/example) is a weather agent with one tool. It makes a call that asks for the tool, runs the tool in a TOOL span of its own, and makes a second call (streamed with `-stream`). `-fail` adds one call the API rejects, so you see an error span. + +```bash +git clone --branch dev https://github.com/future-agi/traceAI.git +cd traceAI/go/anthropic +export FI_PROJECT_NAME="my-chatbot" +go run ./example -stream -fail -session demo-1 +``` + +Until the PR is merged, clone with `--branch feat/th-8272-anthropic-go`. The example reads the same environment variables as step 2, plus `FI_PROJECT_NAME` and, for a self-hosted Future AGI, `FI_BASE_URL`. Its default model is `claude-sonnet-5-5`; pass `-model` to use another. + +Open the project in **Observe > Tracing**. The run is one trace with the agent span, two LLM spans and the tool span. The rejected call is a separate trace with status ERROR. + +## What is captured + +Each Messages call is one span named `anthropic.messages.create`, type LLM. + +| Attribute | Value | +| --- | --- | +| `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.response.id` | from the request and the response | +| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` | token counts from the response, or from a stream's final event | +| `gen_ai.usage.cache_read.input_tokens`, `gen_ai.usage.cache_write.input_tokens` | prompt-cache counts, when the response has them | +| `gen_ai.response.finish_reasons` | the stop reason, such as `end_turn` or `tool_use` | +| `input.value`, `output.value` | the request body and the response message, as JSON. A stream's message is assembled from its events. These fill the span's Input and Output in Observe | +| `gen_ai.input.messages`, `gen_ai.system_instructions`, `gen_ai.output.messages` | the conversation, including `tool_call` parts (tool name, call id, arguments) and `tool_call_response` parts | +| `gen_ai.tool.definitions`, `gen_ai.request.parameters` | the tools you offered, and settings such as `max_tokens`, `temperature`, `stream` and `tool_choice` | +| `session.id`, `user.id` | only when you set them with `ContextWithSessionID` and `ContextWithUserID`. Future AGI groups traces by [session](/docs/observe/features/session) and [user](/docs/observe/features/users) | +| `error.type`, status ERROR | on an API error (the error type, such as `rate_limit_error`), a stream error event, a stream that ends early or a canceled context | + +`gen_ai.usage.input_tokens` counts every input token, cached or not: Anthropic's `input_tokens` plus its cache read and cache write tokens, as the [OpenTelemetry GenAI conventions for Anthropic](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/anthropic.md) define it. The uncached count is `input_tokens` minus the two cache counts. In a test with a 17,102-token cached system prompt, the span recorded 17,115 input tokens with `cache_write.input_tokens` 17,102 on the first call and `cache_read.input_tokens` 17,102 on the second. + +A stream is one span: no span is opened per event, and the span ends when the stream ends, fails, is closed or its context is canceled. The model's tool calls are recorded on the LLM span. The middleware does not trace your tool code, because it runs in your program and not in the API call; open a span around it yourself, as the example does. + +### The SDK's own span + +From v1.81.0, anthropic-sdk-go opens a span for each API call itself, through the tracer provider you register. When that span is recording, the middleware adds the attributes above to it, so a call is still one span. When you turn the SDK's spans off (`option.WithoutOpenTelemetry()` or `ANTHROPIC_OPEN_TELEMETRY=false`), the middleware opens the span itself, with the same name and attributes. + +| | SDK span on (default) | SDK span off | +| --- | --- | --- | +| Spans per call | 1 (the SDK's, enriched) | 1 per HTTP attempt (a retry is a second span) | +| Error status message | empty, `error.type` set | the error type | +| Request URL | recorded by the SDK (`url.full`, `server.address`) | not recorded | +| Tracer provider | the one registered with `otel.SetTracerProvider`, or the SDK's `option.WithTracerProvider` | the registered one, or `traceaianthropic.WithTracerProvider` | + +## Privacy + +Content is captured by default, as in every traceAI instrumentor. Turn it off with the same variables traceAI uses in Python and TypeScript ([TraceConfig](/docs/sdk/tracing/trace-config)): + +| Variable | Effect | +| --- | --- | +| `FI_HIDE_INPUTS=true` | `input.value` becomes `__REDACTED__`. No input messages, system instructions, tool definitions or stop sequences | +| `FI_HIDE_OUTPUTS=true` | `output.value` becomes `__REDACTED__`. No output messages | +| `FI_HIDE_INPUT_MESSAGES=true`, `FI_HIDE_OUTPUT_MESSAGES=true` | no `gen_ai.input.messages` and `gen_ai.system_instructions`, or no `gen_ai.output.messages` | +| `FI_HIDE_INPUT_TEXT=true`, `FI_HIDE_OUTPUT_TEXT=true` | the text of each message part becomes `__REDACTED__` | +| `FI_HIDE_INPUT_IMAGES=true` | image data and image parts are left out | +| `FI_BASE64_IMAGE_MAX_LENGTH` | the longest base64 image kept (default 32000) | +| `FI_HIDE_LLM_INVOCATION_PARAMETERS=true` | no `gen_ai.request.parameters` | + +The variables are read when you call `Middleware()`. To set them in code, pass `traceaianthropic.WithTraceConfig(traceaianthropic.TraceConfig{HideInputs: true, HideOutputs: true})`. Model, token counts, finish reason and error type stay in every mode. With `FI_HIDE_INPUTS` and `FI_HIDE_OUTPUTS` set, a unique marker sent in prompts, tool arguments and answers was absent from every stored column of the test project, while the same marker was present in runs with the default setting. + +Never exported, in any mode: the Anthropic API key and other request headers, the Future AGI keys, the `authorization_token` of an MCP server in a request, error message text in the span status, and stack traces. + + +The `FI_HIDE_*` variables control what traceAI adds. If you also set `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content` (or `option.WithOpenTelemetryTracesContentMode`), anthropic-sdk-go puts request and response content on its own span, and `FI_HIDE_*` does not remove it. Leave that setting unset. The middleware logs a warning when both are set. + + +The SDK's own span records the API endpoint (`url.full`, `server.address`). For `api.anthropic.com` that is a public host name. If `ANTHROPIC_BASE_URL` points at an internal gateway, its host name is exported; turn the SDK's span off to avoid that. + +## Limitations + +- Not yet run against `api.anthropic.com` with an Anthropic API key (see the warning at the top). +- Amazon Bedrock and Google Vertex clients use the same middleware but are not tested. A Bedrock streaming response (binary event stream) is passed through without LLM attributes. +- `count_tokens`, message batches, files and models calls get no LLM attributes. +- Cost in Observe is computed from `gen_ai.usage.input_tokens`, which includes cached tokens, so prompt-cache discounts are not reflected. +- The module needs anthropic-sdk-go v1.82.0 or later. Older SDK versions are not supported. + +## Troubleshooting + +| Symptom | Cause and fix | +| --- | --- | +| No traces | The program exited before the exporter flushed. Make sure `tp.Shutdown` runs (it does not after `log.Fatal` or `os.Exit`). Check that both `X-Api-Key` and `X-Secret-Key` are set and that `project_name` is a resource attribute, not a span attribute. | +| Spans arrive with empty Input and Output | The middleware is not on the client: these are anthropic-sdk-go's own spans. Pass `option.WithMiddleware(traceaianthropic.Middleware())` to `anthropic.NewClient`. | +| Two spans per call | The SDK's span is created by a tracer provider that is not the OpenTelemetry Go SDK, so the middleware cannot recognize it and opens its own. Use the OpenTelemetry Go SDK provider, or turn the SDK's spans off with `option.WithoutOpenTelemetry()`. | +| A streamed call never shows up | The span ends when the stream is read to the end or closed. Read the stream to the end, or `defer stream.Close()`. | +| `go get ...@latest` fails with "module github.com/future-agi/traceAI@latest found (v1.0.0), but does not contain package github.com/future-agi/traceAI/go/anthropic" | The Go module has no release tag yet. Use `@dev` (or the PR branch, see Install). | +| Content still visible with `FI_HIDE_*` set | Check `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE` (see Privacy), and that the variables are set before `Middleware()` is called. Values must be `true` or `false`. | +| Exporter errors or traces are dropped | Send uncompressed OTLP/HTTP protobuf: keep `WithCompression(otlptracehttp.NoCompression)` and the full `/tracer/v1/traces` path. | + +## Next Steps + +- [TraceConfig and the FI_HIDE_* variables](/docs/sdk/tracing/trace-config) +- [Sessions](/docs/observe/features/session) +- [Anthropic (Python and TypeScript)](/docs/integrations/traceai/anthropic) From c8e7bff51bb8bc84564df8bd17e90be91951ae3f Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Fri, 16 Oct 2026 14:57:42 -0700 Subject: [PATCH 2/5] docs(traceai): move Anthropic Go page under traceai/go/ (TH-8272) Matches the other Go pages (traceai/go/openai, go/gemini, go/a2a, go/eino). New URL: /docs/integrations/traceai/go/anthropic. Not yet published, so no redirect is needed. Co-Authored-By: Claude Opus 5.5 --- .../integrations/traceai/{anthropic-go.mdx => go/anthropic.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/pages/docs/integrations/traceai/{anthropic-go.mdx => go/anthropic.mdx} (100%) diff --git a/src/pages/docs/integrations/traceai/anthropic-go.mdx b/src/pages/docs/integrations/traceai/go/anthropic.mdx similarity index 100% rename from src/pages/docs/integrations/traceai/anthropic-go.mdx rename to src/pages/docs/integrations/traceai/go/anthropic.mdx From 85fa6b54a90a7e5a30339f11f08cd094dfdf6c2b Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 19 Oct 2026 13:28:48 -0700 Subject: [PATCH 3/5] docs(traceai): Anthropic Go live verification and base URL note (TH-8272) Co-Authored-By: Claude Opus 5.5 --- src/pages/docs/integrations/traceai/go/anthropic.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/integrations/traceai/go/anthropic.mdx b/src/pages/docs/integrations/traceai/go/anthropic.mdx index 8c4ee6b00..94dc3d868 100644 --- a/src/pages/docs/integrations/traceai/go/anthropic.mdx +++ b/src/pages/docs/integrations/traceai/go/anthropic.mdx @@ -52,7 +52,7 @@ export FI_API_KEY="your-futureagi-api-key" export FI_SECRET_KEY="your-futureagi-secret-key" ``` -anthropic-sdk-go reads `ANTHROPIC_API_KEY` (and `ANTHROPIC_BASE_URL`, if you use a gateway) itself. The Future AGI keys go only to the trace exporter, never on a request to Anthropic. +anthropic-sdk-go reads `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` itself. To send calls to a gateway or an Anthropic-compatible proxy, set `ANTHROPIC_BASE_URL` (for example `export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"`), or pass `option.WithBaseURL(...)` to `anthropic.NewClient`. The Future AGI keys go only to the trace exporter, never on a request to Anthropic. ## 3. Export to Future AGI and add the middleware @@ -198,6 +198,16 @@ The `FI_HIDE_*` variables control what traceAI adds. If you also set `ANTHROPIC_ The SDK's own span records the API endpoint (`url.full`, `server.address`). For `api.anthropic.com` that is a public host name. If `ANTHROPIC_BASE_URL` points at an internal gateway, its host name is exported; turn the SDK's span off to avoid that. +## Live verification (2026-10-19, real Claude via an Anthropic-compatible proxy) + +These calls went through a local Anthropic-compatible proxy (CLIProxy), not directly to `api.anthropic.com`. The proxy serves the Anthropic Messages API backed by real Claude models, so the model answers are real, but the endpoint is the proxy's, and it has not been run against `api.anthropic.com` with an Anthropic API key. The SDK was pointed at the proxy exactly as in step 2: `ANTHROPIC_BASE_URL` set to the proxy and `ANTHROPIC_API_KEY` set to the proxy's key. The middleware does not read either. + +- Setup: anthropic-sdk-go v1.82.0, Go 1.24.3, OpenTelemetry Go v1.33.0, model `claude-haiku-5-5`, local Future AGI collector, `go run ./example -stream -fail`. +- Tool use: a trace is the agent span, an LLM span that asks for `get_weather`, the TOOL span and an LLM span with the answer. The streamed answer is one span with its token counts (483 input, 26 output). +- Failure: a call with a model id that does not exist is an LLM span with status ERROR and no content beyond the request. +- Stored spans: type `llm`, `provider` anthropic, the model, input and output tokens (403/50 for the tool-asking call), and Input and Output filled. `fi_verify` passed. +- Privacy: with `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true`, a unique marker (also sent as an email address and a file path) was absent from every stored column of the project, including resource attributes and span events. With the defaults, the marker was present in the Input and Output columns. The Future AGI keys, the proxy key, host name, user name and home directory were never stored. The SDK's own span still stored the proxy's address (`server.address`, `url.full`), as described under Privacy. + ## Limitations - Not yet run against `api.anthropic.com` with an Anthropic API key (see the warning at the top). From 772eec3fe96660044856f204719bdc70253624fa Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 21 Oct 2026 15:06:19 -0700 Subject: [PATCH 4/5] docs(traceai): Anthropic Go page installs the tagged module (TH-8272) The page goes live only after traceAI#259 is merged to main and go/anthropic is tagged, so install with @latest instead of @dev or the PR branch, link the source on main, and drop the troubleshooting row for the untagged module. The warning now says what was run (real Claude models through an Anthropic-compatible proxy) instead of "stand-in endpoint"; it still says api.anthropic.com was not called. Co-Authored-By: Claude Opus 5.5 --- .../docs/integrations/traceai/go/anthropic.mdx | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/src/pages/docs/integrations/traceai/go/anthropic.mdx b/src/pages/docs/integrations/traceai/go/anthropic.mdx index 94dc3d868..1df11312a 100644 --- a/src/pages/docs/integrations/traceai/go/anthropic.mdx +++ b/src/pages/docs/integrations/traceai/go/anthropic.mdx @@ -17,7 +17,7 @@ weather-agent AGENT your code (optional) The module only uses the OpenTelemetry API. You export the spans with the standard OpenTelemetry OTLP/HTTP exporter, which sends them to Future AGI with your keys. -**Alpha, verified through a stand-in endpoint.** The module was tested end to end with anthropic-sdk-go v1.82.0 against a Future AGI collector, with the Anthropic API **stood in** by a local proxy: the SDK talked to the proxy, which answered with real Claude model responses (`claude-haiku-4-5-20251001`) and, in one run, with a non-Anthropic model through its Messages translation. It has not yet been run against `api.anthropic.com` with an Anthropic API key. The middleware does not read or change the base URL or the API key, so only the endpoint differs. +**Alpha, verified with real Claude models through an Anthropic-compatible proxy.** The module was tested end to end with anthropic-sdk-go v1.82.0 against a Future AGI collector. The SDK talked to a local Anthropic-compatible proxy (CLIProxy) that answered with real Claude model responses (`claude-haiku-4-5-20251001`, and `claude-haiku-5-5` in the [2026-10-19 run](#live-verification-2026-10-19-real-claude-via-an-anthropic-compatible-proxy)) and, in one run, with a non-Anthropic model through its Messages translation. It has not yet been run against `api.anthropic.com` with an Anthropic API key. The middleware does not read or change the base URL or the API key, so only the endpoint differs. This page is not the same as: @@ -30,20 +30,16 @@ This page is not the same as: | Tested with | anthropic-sdk-go **v1.82.0** (latest on 2026-10-16), Go 1.24.3 and 1.27.2, OpenTelemetry Go v1.33.0 and v1.47.0 | | Requires | anthropic-sdk-go v1.82.0 or later (`go get` raises an older version), Go 1.24 or later | | Status | Alpha. Not yet run against `api.anthropic.com` (see the warning) | -| Source | [go/anthropic](https://github.com/future-agi/traceAI/tree/dev/go/anthropic) in traceAI | +| Source | [go/anthropic](https://github.com/future-agi/traceAI/tree/main/go/anthropic) in traceAI | ## 1. Install ```bash -go get github.com/future-agi/traceAI/go/anthropic@dev +go get github.com/future-agi/traceAI/go/anthropic@latest go get github.com/anthropics/anthropic-sdk-go@latest go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp ``` - -The module ships with [traceAI PR #259](https://github.com/future-agi/traceAI/pull/259) and has no release tag yet, so install it from a branch. Until the PR is merged into `dev`, use `@feat/th-8272-anthropic-go` instead of `@dev`. After the first `go/anthropic/v0.x` tag you can use `@latest`. - - ## 2. Set environment variables ```bash @@ -130,16 +126,16 @@ For a self-hosted Future AGI, replace `https://api.futureagi.com` with your inst ## 4. Run a complete example -[`go/anthropic/example`](https://github.com/future-agi/traceAI/tree/dev/go/anthropic/example) is a weather agent with one tool. It makes a call that asks for the tool, runs the tool in a TOOL span of its own, and makes a second call (streamed with `-stream`). `-fail` adds one call the API rejects, so you see an error span. +[`go/anthropic/example`](https://github.com/future-agi/traceAI/tree/main/go/anthropic/example) is a weather agent with one tool. It makes a call that asks for the tool, runs the tool in a TOOL span of its own, and makes a second call (streamed with `-stream`). `-fail` adds one call the API rejects, so you see an error span. ```bash -git clone --branch dev https://github.com/future-agi/traceAI.git +git clone https://github.com/future-agi/traceAI.git cd traceAI/go/anthropic export FI_PROJECT_NAME="my-chatbot" go run ./example -stream -fail -session demo-1 ``` -Until the PR is merged, clone with `--branch feat/th-8272-anthropic-go`. The example reads the same environment variables as step 2, plus `FI_PROJECT_NAME` and, for a self-hosted Future AGI, `FI_BASE_URL`. Its default model is `claude-sonnet-5-5`; pass `-model` to use another. +The example reads the same environment variables as step 2, plus `FI_PROJECT_NAME` and, for a self-hosted Future AGI, `FI_BASE_URL`. Its default model is `claude-sonnet-5-5`; pass `-model` to use another. Open the project in **Observe > Tracing**. The run is one trace with the agent span, two LLM spans and the tool span. The rejected call is a separate trace with status ERROR. @@ -224,7 +220,6 @@ These calls went through a local Anthropic-compatible proxy (CLIProxy), not dire | Spans arrive with empty Input and Output | The middleware is not on the client: these are anthropic-sdk-go's own spans. Pass `option.WithMiddleware(traceaianthropic.Middleware())` to `anthropic.NewClient`. | | Two spans per call | The SDK's span is created by a tracer provider that is not the OpenTelemetry Go SDK, so the middleware cannot recognize it and opens its own. Use the OpenTelemetry Go SDK provider, or turn the SDK's spans off with `option.WithoutOpenTelemetry()`. | | A streamed call never shows up | The span ends when the stream is read to the end or closed. Read the stream to the end, or `defer stream.Close()`. | -| `go get ...@latest` fails with "module github.com/future-agi/traceAI@latest found (v1.0.0), but does not contain package github.com/future-agi/traceAI/go/anthropic" | The Go module has no release tag yet. Use `@dev` (or the PR branch, see Install). | | Content still visible with `FI_HIDE_*` set | Check `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE` (see Privacy), and that the variables are set before `Middleware()` is called. Values must be `true` or `false`. | | Exporter errors or traces are dropped | Send uncompressed OTLP/HTTP protobuf: keep `WithCompression(otlptracehttp.NoCompression)` and the full `/tracer/v1/traces` path. | From 9839d6fd648eac02ee97b185bd704470322dbbc3 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 17:24:07 -0800 Subject: [PATCH 5/5] docs: refresh Anthropic Go setup and guard published snippets Pin released packages and Go 1.26, remove internal qualification prose, flush telemetry on API errors, and register the Go guide in the integration catalog. Add contract and cloud-only Go checks. Direct success qualification remains blocked on Anthropic credits. Co-Authored-By: Claude Code --- .github/workflows/anthropic-go-docs.yml | 39 +++ scripts/anthropic-go-page.test.mjs | 43 ++++ scripts/anthropic-go-snippet.mjs | 12 + scripts/integrations.test.mjs | 1 + src/lib/integrations.mjs | 1 + .../integrations/traceai/go/anthropic.mdx | 235 ++++++++---------- 6 files changed, 201 insertions(+), 130 deletions(-) create mode 100644 .github/workflows/anthropic-go-docs.yml create mode 100644 scripts/anthropic-go-page.test.mjs create mode 100644 scripts/anthropic-go-snippet.mjs diff --git a/.github/workflows/anthropic-go-docs.yml b/.github/workflows/anthropic-go-docs.yml new file mode 100644 index 000000000..856c310cc --- /dev/null +++ b/.github/workflows/anthropic-go-docs.yml @@ -0,0 +1,39 @@ +name: Anthropic Go docs + +on: + pull_request: + paths: + - 'src/pages/docs/integrations/traceai/go/anthropic.mdx' + - 'scripts/anthropic-go-*.mjs' + - '.github/workflows/anthropic-go-docs.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + snippet: + name: Anthropic Go 1.26 snippet + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + - uses: actions/setup-go@v5 + with: + go-version: '1.26.0' + cache: false + - name: Check page contract + run: node --test scripts/anthropic-go-page.test.mjs + - name: Extract exact page commands and Go snippet + run: node scripts/anthropic-go-snippet.mjs "$RUNNER_TEMP/anthropic-go-snippet" + - name: Install and compile without provider credentials + working-directory: ${{ runner.temp }}/anthropic-go-snippet + env: + GOTOOLCHAIN: local + run: | + bash install.sh + go build -o example . + go vet ./... + go test -race github.com/future-agi/traceAI/go/anthropic diff --git a/scripts/anthropic-go-page.test.mjs b/scripts/anthropic-go-page.test.mjs new file mode 100644 index 000000000..2c332b57f --- /dev/null +++ b/scripts/anthropic-go-page.test.mjs @@ -0,0 +1,43 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { integrations } from '../src/lib/integrations.mjs'; + +const page = readFileSync(new URL('../src/pages/docs/integrations/traceai/go/anthropic.mdx', import.meta.url), 'utf8'); +const example = page.match(/```go\n([\s\S]*?)\n```/)?.[1]; + +test('Anthropic Go uses published packages and the module Go minimum', () => { + assert.match(page, /Go \*\*1\.26\.0 or later\*\*/); + assert.match(page, /go get github\.com\/future-agi\/traceAI\/go\/anthropic@v0\.1\.0/); + assert.match(page, /go get github\.com\/anthropics\/anthropic-sdk-go@v1\.82\.0/); + assert.match(page, /go run github\.com\/future-agi\/traceAI\/go\/anthropic\/example@v0\.1\.0 -model claude-haiku-5-5 -stream -fail -session demo-1/); + assert.doesNotMatch(page, /@latest|@dev|git clone/); + assert.ok(example); +}); + +test('Anthropic Go snippet flushes on API errors and uses stock OTLP', () => { + assert.match(example, /func main\(\) \{[\s\S]*?if err := run\(\); err != nil/); + const run = example.slice(example.indexOf('func run()')); + assert.match(run, /defer func\(\) \{\s*if err := tp\.Shutdown\(context\.Background\(\)\)/); + assert.doesNotMatch(run, /log\.Fatal|os\.Exit/); + for (const required of ['X-Api-Key', 'X-Secret-Key', 'project_name', 'project_type', 'otlptracehttp.NoCompression', '/tracer/v1/traces', 'FI_BASE_URL']) { + assert.ok(example.includes(required), required); + } + assert.match(example, /option\.WithMiddleware\(traceaianthropic\.Middleware\(\)\)/); +}); + +test('Anthropic Go keeps privacy controls and customer-facing wording', () => { + assert.match(page, /FI_HIDE_INPUTS=true/); + assert.match(page, /FI_HIDE_OUTPUTS=true/); + assert.match(page, /Leave `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE` unset/); + assert.match(page, /error bodies as application content/); + assert.match(page, /Consume the stream to completion or close it/); + assert.doesNotMatch(page, /live verification|STANDIN|CLIProxy|not yet been run|2026-10-19|17,102-token/i); +}); + +test('Anthropic Go is discoverable in the integration catalog', () => { + const item = integrations.find(i => i.id === 'anthropic-go'); + assert.equal(item?.href, '/docs/integrations/traceai/go/anthropic'); + assert.equal(item?.category, 'providers'); + assert.equal(item?.method, 'traceAI SDK'); +}); diff --git a/scripts/anthropic-go-snippet.mjs b/scripts/anthropic-go-snippet.mjs new file mode 100644 index 000000000..2eba1934c --- /dev/null +++ b/scripts/anthropic-go-snippet.mjs @@ -0,0 +1,12 @@ +import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import path from 'node:path'; + +const destination = process.argv[2]; +if (!destination) throw new Error('Usage: node scripts/anthropic-go-snippet.mjs '); +const page = readFileSync(new URL('../src/pages/docs/integrations/traceai/go/anthropic.mdx', import.meta.url), 'utf8'); +const source = page.match(/```go\n([\s\S]*?)\n```/)?.[1]; +const install = page.match(/```bash\n([\s\S]*?)\n```/)?.[1]; +if (!source || !install) throw new Error('Missing Go example or install commands'); +mkdirSync(destination, { recursive: true }); +writeFileSync(path.join(destination, 'main.go'), `${source}\n`); +writeFileSync(path.join(destination, 'install.sh'), `set -eu\n${install}\n`); diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index d099b0d36..2ee310396 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -31,6 +31,7 @@ import './kiro-cli-page.test.mjs'; import './google-genai-live-page.test.mjs'; import './elevenlabs-agents-page.test.mjs'; import './gemini-go-page.test.mjs'; +import './anthropic-go-page.test.mjs'; import './typesafe-page.test.mjs'; import './ag2-classic-page.test.mjs'; import './firecrawl-page.test.mjs'; diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index cf22a9b3d..5e0d37f9f 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -74,6 +74,7 @@ export const integrations = [ { id: 'openai', name: 'OpenAI', href: '/docs/integrations/traceai/openai', category: 'providers', summary: 'Instrument OpenAI client calls in your application.', method: 'traceAI SDK', logo: 'openai' }, { id: 'openai-go', name: 'OpenAI Go', href: '/docs/integrations/traceai/go/openai', category: 'providers', summary: 'Trace Chat Completions from the official Go SDK.', method: 'traceAI SDK', logo: 'openai' }, { id: 'anthropic', name: 'Anthropic', href: '/docs/integrations/traceai/anthropic', category: 'providers', summary: 'Capture Claude calls, token usage and latency.', method: 'OpenTelemetry', logo: 'anthropic', aliases: ['Claude'] }, + { id: 'anthropic-go', name: 'Anthropic Go', href: '/docs/integrations/traceai/go/anthropic', category: 'providers', summary: 'Trace Claude Messages, streaming responses and tool requests from Go.', method: 'traceAI SDK', logo: 'anthropic', aliases: ['Claude Go', 'golang'] }, { id: 'bedrock', name: 'AWS Bedrock', href: '/docs/integrations/traceai/bedrock', category: 'providers', summary: 'Trace model calls through Amazon Bedrock.', method: 'traceAI SDK', logo: 'bedrock', aliases: ['Amazon'] }, {"id": "aws-lambda-local", "name": "Lambda local lifecycle", "href": "/docs/integrations/runtimes/aws-lambda", "category": "frameworks", "summary": "Exercise handler reuse and bounded flush attempts locally.", "method": "Local OTLP example", "logo": "generic-framework"}, { id: 'vertexai', name: 'Vertex AI', href: '/docs/integrations/traceai/vertexai', category: 'providers', summary: 'Instrument Gemini calls through Google Cloud.', method: 'traceAI SDK', logo: 'vertexai', aliases: ['Google', 'Gemini'] }, diff --git a/src/pages/docs/integrations/traceai/go/anthropic.mdx b/src/pages/docs/integrations/traceai/go/anthropic.mdx index 1df11312a..9f0357b3d 100644 --- a/src/pages/docs/integrations/traceai/go/anthropic.mdx +++ b/src/pages/docs/integrations/traceai/go/anthropic.mdx @@ -1,56 +1,49 @@ --- -title: "Anthropic Go SDK tracing with Future AGI" -description: "Trace anthropic-sdk-go Messages calls with the traceAI Go middleware: one LLM span per call, streaming included, with model, tokens, tool calls and session. Content is captured by default and turned off with the FI_HIDE_* variables." +title: "Anthropic Go SDK" +description: "Trace Claude Messages calls, streaming responses, tool requests and errors from Go in Future AGI." --- -## About +Trace calls from the official Anthropic Go SDK in Future AGI with model names, token usage, prompts, responses and tool requests. The maintained traceAI middleware enriches the SDK's existing OpenTelemetry span rather than creating a duplicate. -[anthropic-sdk-go](https://github.com/anthropics/anthropic-sdk-go) is Anthropic's official Go SDK. The traceAI module `github.com/future-agi/traceAI/go/anthropic` is a client middleware for it. You add it once, with `option.WithMiddleware`, when you create the client, and every `Messages.New` and `Messages.NewStreaming` call made with that client becomes one LLM span in Future AGI: +## Prerequisites -``` -weather-agent AGENT your code (optional) -├── anthropic.messages.create LLM model, tokens, request and response, tool call -├── execute_tool get_weather TOOL your code (optional) -└── anthropic.messages.create LLM streamed answer: still one span -``` - -The module only uses the OpenTelemetry API. You export the spans with the standard OpenTelemetry OTLP/HTTP exporter, which sends them to Future AGI with your keys. +- Go **1.26.0 or later**. +- An Anthropic API key with access to the model you use. +- Your Future AGI API key and secret key. - -**Alpha, verified with real Claude models through an Anthropic-compatible proxy.** The module was tested end to end with anthropic-sdk-go v1.82.0 against a Future AGI collector. The SDK talked to a local Anthropic-compatible proxy (CLIProxy) that answered with real Claude model responses (`claude-haiku-4-5-20251001`, and `claude-haiku-5-5` in the [2026-10-19 run](#live-verification-2026-10-19-real-claude-via-an-anthropic-compatible-proxy)) and, in one run, with a non-Anthropic model through its Messages translation. It has not yet been run against `api.anthropic.com` with an Anthropic API key. The middleware does not read or change the base URL or the API key, so only the endpoint differs. - +This guide uses `anthropic-sdk-go` **v1.82.0** and traceAI **v0.1.0**. Keep the SDK's v1 import path shown below; the `/v2` SDK has a different middleware type and is not a drop-in replacement. -This page is not the same as: +## Install -- **[Anthropic (Python and TypeScript)](/docs/integrations/traceai/anthropic)** and **[Anthropic (Java)](/docs/integrations/traceai/java/anthropic)**. Those instrument the other official SDKs. This module is for Go only and does not change them. -- **Claude Agent SDK, Claude Code and Claude Managed Agents**. Those are agent products with their own telemetry. This page covers plain Messages API calls from a Go program. - -| | | -| --- | --- | -| Tested with | anthropic-sdk-go **v1.82.0** (latest on 2026-10-16), Go 1.24.3 and 1.27.2, OpenTelemetry Go v1.33.0 and v1.47.0 | -| Requires | anthropic-sdk-go v1.82.0 or later (`go get` raises an older version), Go 1.24 or later | -| Status | Alpha. Not yet run against `api.anthropic.com` (see the warning) | -| Source | [go/anthropic](https://github.com/future-agi/traceAI/tree/main/go/anthropic) in traceAI | - -## 1. Install +In a new directory, initialize a Go module and install the released packages: ```bash -go get github.com/future-agi/traceAI/go/anthropic@latest -go get github.com/anthropics/anthropic-sdk-go@latest -go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp +go mod init example.com/anthropic-tracing +go get github.com/future-agi/traceAI/go/anthropic@v0.1.0 +go get github.com/anthropics/anthropic-sdk-go@v1.82.0 +go get go.opentelemetry.io/otel/sdk@v1.33.0 go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp@v1.33.0 ``` -## 2. Set environment variables +Skip `go mod init` in an existing Go module. If your application already configures OpenTelemetry, reuse its tracer provider and add the exporter to that setup. + +## Configure credentials ```bash export ANTHROPIC_API_KEY="your-anthropic-api-key" export FI_API_KEY="your-futureagi-api-key" export FI_SECRET_KEY="your-futureagi-secret-key" +export FI_PROJECT_NAME="my-chatbot" ``` -anthropic-sdk-go reads `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` itself. To send calls to a gateway or an Anthropic-compatible proxy, set `ANTHROPIC_BASE_URL` (for example `export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"`), or pass `option.WithBaseURL(...)` to `anthropic.NewClient`. The Future AGI keys go only to the trace exporter, never on a request to Anthropic. +The Anthropic SDK reads `ANTHROPIC_API_KEY`; the Future AGI keys go only to the trace exporter. Leave `ANTHROPIC_BASE_URL` unset to call Anthropic directly. + + +Prompts, responses and tool arguments are captured by default. Use the [privacy settings](#privacy) before sending sensitive content. + + +## Trace a Messages call -## 3. Export to Future AGI and add the middleware +Save this as `main.go`: ```go package main @@ -60,24 +53,33 @@ import ( "fmt" "log" "os" + "strings" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/option" + traceaianthropic "github.com/future-agi/traceAI/go/anthropic" "go.opentelemetry.io/otel" "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" - - traceaianthropic "github.com/future-agi/traceAI/go/anthropic" ) func main() { - ctx := context.Background() + // run returns before log.Fatal, so the deferred exporter shutdown runs. + if err := run(); err != nil { + log.Fatal(err) + } +} - // Future AGI needs both keys as headers and project_name as a resource attribute. +func run() error { + ctx := context.Background() + base := strings.TrimRight(os.Getenv("FI_BASE_URL"), "/") + if base == "" { + base = "https://api.futureagi.com" + } exporter, err := otlptracehttp.New(ctx, - otlptracehttp.WithEndpointURL("https://api.futureagi.com/tracer/v1/traces"), + otlptracehttp.WithEndpointURL(base+"/tracer/v1/traces"), otlptracehttp.WithHeaders(map[string]string{ "X-Api-Key": os.Getenv("FI_API_KEY"), "X-Secret-Key": os.Getenv("FI_SECRET_KEY"), @@ -85,146 +87,119 @@ func main() { otlptracehttp.WithCompression(otlptracehttp.NoCompression), ) if err != nil { - log.Fatal(err) + return err } tp := sdktrace.NewTracerProvider( sdktrace.WithBatcher(exporter), sdktrace.WithResource(resource.NewSchemaless( - attribute.String("project_name", "my-chatbot"), + attribute.String("project_name", os.Getenv("FI_PROJECT_NAME")), attribute.String("project_type", "observe"), - attribute.String("service.name", "my-chatbot"), + attribute.String("service.name", "anthropic-go-chatbot"), )), ) - // Flush the last batch before the process exits. - defer tp.Shutdown(context.Background()) + defer func() { + if err := tp.Shutdown(context.Background()); err != nil { + log.Printf("trace export: %v", err) + } + }() otel.SetTracerProvider(tp) - // Add the middleware once, on the client. client := anthropic.NewClient(option.WithMiddleware(traceaianthropic.Middleware())) - - // Optional: group calls into a session and tag your end user. ctx = traceaianthropic.ContextWithSessionID(ctx, "session-123") ctx = traceaianthropic.ContextWithUserID(ctx, "user-42") msg, err := client.Messages.New(ctx, anthropic.MessageNewParams{ - Model: anthropic.ModelClaudeSonnet5_5, - MaxTokens: 256, + Model: "claude-haiku-5-5", + MaxTokens: 64, Messages: []anthropic.MessageParam{ - anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France? Answer in one sentence.")), }, }) if err != nil { - log.Fatal(err) + return err + } + for _, block := range msg.Content { + if block.Type == "text" { + fmt.Println(block.Text) + } } - fmt.Println(msg.Content[0].Text) + return nil } ``` -For a self-hosted Future AGI, replace `https://api.futureagi.com` with your instance's base URL. Keep the path `/tracer/v1/traces`. +Run the program: -`defer tp.Shutdown(...)` matters: the batch processor exports in the background, and a short program that exits without shutting the provider down sends nothing. If your program calls `log.Fatal` or `os.Exit`, deferred calls do not run, so return from a function that holds the `defer` first. +```bash +go run . +``` + +For self-hosted Future AGI, set `FI_BASE_URL` to your instance's base URL. Both this program and the example below append `/tracer/v1/traces`. + +Open **Observe > Tracing**, select your `my-chatbot` project, and open the `anthropic.messages.create` span. Its Input and Output contain the request and response; model and token fields describe the Claude call. The optional context helpers group calls by [session](/docs/observe/features/session) and [user](/docs/observe/features/users). -## 4. Run a complete example +## Streaming and tool calls -[`go/anthropic/example`](https://github.com/future-agi/traceAI/tree/main/go/anthropic/example) is a weather agent with one tool. It makes a call that asks for the tool, runs the tool in a TOOL span of its own, and makes a second call (streamed with `-stream`). `-fail` adds one call the API rejects, so you see an error span. +Run the [packaged weather example](https://github.com/future-agi/traceAI/tree/go/anthropic/v0.1.0/go/anthropic/example) with the same credentials: ```bash -git clone https://github.com/future-agi/traceAI.git -cd traceAI/go/anthropic -export FI_PROJECT_NAME="my-chatbot" -go run ./example -stream -fail -session demo-1 +go run github.com/future-agi/traceAI/go/anthropic/example@v0.1.0 -model claude-haiku-5-5 -stream -fail -session demo-1 ``` -The example reads the same environment variables as step 2, plus `FI_PROJECT_NAME` and, for a self-hosted Future AGI, `FI_BASE_URL`. Its default model is `claude-sonnet-5-5`; pass `-model` to use another. +The example asks Claude to call `get_weather`, returns sample weather data, and streams the final answer. It opens its own agent and tool spans around the two model calls. The `-fail` flag adds a separate request with an invalid model to demonstrate an error span. -Open the project in **Observe > Tracing**. The run is one trace with the agent span, two LLM spans and the tool span. The rejected call is a separate trace with status ERROR. +The weather trace contains an agent span, two LLM spans and a tool span. The rejected request appears in a separate trace with status ERROR. Tool requests are captured on the LLM span; the middleware does not automatically trace tool code running in your application. -## What is captured +A streaming response produces one LLM span, not one per event. Consume the stream to completion or close it so the span can finish and export. -Each Messages call is one span named `anthropic.messages.create`, type LLM. +## What is captured -| Attribute | Value | +| Field | Contents | | --- | --- | -| `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.response.id` | from the request and the response | -| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` | token counts from the response, or from a stream's final event | -| `gen_ai.usage.cache_read.input_tokens`, `gen_ai.usage.cache_write.input_tokens` | prompt-cache counts, when the response has them | -| `gen_ai.response.finish_reasons` | the stop reason, such as `end_turn` or `tool_use` | -| `input.value`, `output.value` | the request body and the response message, as JSON. A stream's message is assembled from its events. These fill the span's Input and Output in Observe | -| `gen_ai.input.messages`, `gen_ai.system_instructions`, `gen_ai.output.messages` | the conversation, including `tool_call` parts (tool name, call id, arguments) and `tool_call_response` parts | -| `gen_ai.tool.definitions`, `gen_ai.request.parameters` | the tools you offered, and settings such as `max_tokens`, `temperature`, `stream` and `tool_choice` | -| `session.id`, `user.id` | only when you set them with `ContextWithSessionID` and `ContextWithUserID`. Future AGI groups traces by [session](/docs/observe/features/session) and [user](/docs/observe/features/users) | -| `error.type`, status ERROR | on an API error (the error type, such as `rate_limit_error`), a stream error event, a stream that ends early or a canceled context | - -`gen_ai.usage.input_tokens` counts every input token, cached or not: Anthropic's `input_tokens` plus its cache read and cache write tokens, as the [OpenTelemetry GenAI conventions for Anthropic](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/anthropic.md) define it. The uncached count is `input_tokens` minus the two cache counts. In a test with a 17,102-token cached system prompt, the span recorded 17,115 input tokens with `cache_write.input_tokens` 17,102 on the first call and `cache_read.input_tokens` 17,102 on the second. - -A stream is one span: no span is opened per event, and the span ends when the stream ends, fails, is closed or its context is canceled. The model's tool calls are recorded on the LLM span. The middleware does not trace your tool code, because it runs in your program and not in the API call; open a span around it yourself, as the example does. +| `gen_ai.span.kind`, `gen_ai.provider.name` | `LLM`, `anthropic` | +| `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.response.id` | Requested model and returned model/message identifiers | +| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` | Token usage from the response, including the final streamed usage | +| `gen_ai.response.finish_reasons` | Stop reason, such as `end_turn` or `tool_use` | +| `input.value`, `output.value` | Request and response JSON, including the assembled streaming response | +| `gen_ai.input.messages`, `gen_ai.output.messages` | Conversation content, including tool calls and tool results | +| `gen_ai.tool.definitions`, `gen_ai.request.parameters` | Offered tools and generation settings | +| `session.id`, `user.id` | Values supplied through the context helpers | +| `error.type`, status ERROR | The API failure type; with content capture enabled, `output.value` also contains the API error body | -### The SDK's own span +Cached input is included in `gen_ai.usage.input_tokens`. Cache reads and writes are also recorded separately as `gen_ai.usage.cache_read.input_tokens` and `gen_ai.usage.cache_write.input_tokens` when returned by the API. Do not add these counts to the total again. Observe's input-token cost calculation does not reflect prompt-cache discounts. -From v1.81.0, anthropic-sdk-go opens a span for each API call itself, through the tracer provider you register. When that span is recording, the middleware adds the attributes above to it, so a call is still one span. When you turn the SDK's spans off (`option.WithoutOpenTelemetry()` or `ANTHROPIC_OPEN_TELEMETRY=false`), the middleware opens the span itself, with the same name and attributes. - -| | SDK span on (default) | SDK span off | -| --- | --- | --- | -| Spans per call | 1 (the SDK's, enriched) | 1 per HTTP attempt (a retry is a second span) | -| Error status message | empty, `error.type` set | the error type | -| Request URL | recorded by the SDK (`url.full`, `server.address`) | not recorded | -| Tracer provider | the one registered with `otel.SetTracerProvider`, or the SDK's `option.WithTracerProvider` | the registered one, or `traceaianthropic.WithTracerProvider` | +The middleware enriches the SDK's existing Messages span. If you disable the SDK's tracing with `ANTHROPIC_OPEN_TELEMETRY=false`, the middleware creates its own span per HTTP attempt; retries can then produce additional spans. The module targets Messages requests, not token counting, batches, files or models endpoints. Use this recipe for direct Anthropic API calls, not Bedrock's binary streaming transport. ## Privacy -Content is captured by default, as in every traceAI instrumentor. Turn it off with the same variables traceAI uses in Python and TypeScript ([TraceConfig](/docs/sdk/tracing/trace-config)): +Set `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true` before constructing the client to omit prompt, response and tool content. The corresponding Input and Output values become `__REDACTED__`; model names, token counts, finish reasons and error types remain available. + +Additional [TraceConfig](/docs/sdk/tracing/trace-config) settings supported by this module: | Variable | Effect | | --- | --- | -| `FI_HIDE_INPUTS=true` | `input.value` becomes `__REDACTED__`. No input messages, system instructions, tool definitions or stop sequences | -| `FI_HIDE_OUTPUTS=true` | `output.value` becomes `__REDACTED__`. No output messages | -| `FI_HIDE_INPUT_MESSAGES=true`, `FI_HIDE_OUTPUT_MESSAGES=true` | no `gen_ai.input.messages` and `gen_ai.system_instructions`, or no `gen_ai.output.messages` | -| `FI_HIDE_INPUT_TEXT=true`, `FI_HIDE_OUTPUT_TEXT=true` | the text of each message part becomes `__REDACTED__` | -| `FI_HIDE_INPUT_IMAGES=true` | image data and image parts are left out | -| `FI_BASE64_IMAGE_MAX_LENGTH` | the longest base64 image kept (default 32000) | -| `FI_HIDE_LLM_INVOCATION_PARAMETERS=true` | no `gen_ai.request.parameters` | - -The variables are read when you call `Middleware()`. To set them in code, pass `traceaianthropic.WithTraceConfig(traceaianthropic.TraceConfig{HideInputs: true, HideOutputs: true})`. Model, token counts, finish reason and error type stay in every mode. With `FI_HIDE_INPUTS` and `FI_HIDE_OUTPUTS` set, a unique marker sent in prompts, tool arguments and answers was absent from every stored column of the test project, while the same marker was present in runs with the default setting. +| `FI_HIDE_INPUT_MESSAGES`, `FI_HIDE_OUTPUT_MESSAGES` | Omit structured input messages/system instructions or output messages | +| `FI_HIDE_INPUT_TEXT`, `FI_HIDE_OUTPUT_TEXT` | Replace message-part text with `__REDACTED__` | +| `FI_HIDE_INPUT_IMAGES` | Omit image data and image parts | +| `FI_BASE64_IMAGE_MAX_LENGTH` | Maximum captured base64 image length; defaults to 32000 | +| `FI_HIDE_LLM_INVOCATION_PARAMETERS` | Omit `gen_ai.request.parameters` | -Never exported, in any mode: the Anthropic API key and other request headers, the Future AGI keys, the `authorization_token` of an MCP server in a request, error message text in the span status, and stack traces. +Boolean settings accept `true` or `false` and are read when `Middleware()` is created. Request headers are not captured by the middleware. Treat prompts, tool arguments and error bodies as application content: do not put credentials in them. -The `FI_HIDE_*` variables control what traceAI adds. If you also set `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content` (or `option.WithOpenTelemetryTracesContentMode`), anthropic-sdk-go puts request and response content on its own span, and `FI_HIDE_*` does not remove it. Leave that setting unset. The middleware logs a warning when both are set. +Leave `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE` unset. Setting it to `content`, or enabling the equivalent SDK client option, lets the SDK export content independently of traceAI's `FI_HIDE_*` settings. -The SDK's own span records the API endpoint (`url.full`, `server.address`). For `api.anthropic.com` that is a public host name. If `ANTHROPIC_BASE_URL` points at an internal gateway, its host name is exported; turn the SDK's span off to avoid that. - -## Live verification (2026-10-19, real Claude via an Anthropic-compatible proxy) - -These calls went through a local Anthropic-compatible proxy (CLIProxy), not directly to `api.anthropic.com`. The proxy serves the Anthropic Messages API backed by real Claude models, so the model answers are real, but the endpoint is the proxy's, and it has not been run against `api.anthropic.com` with an Anthropic API key. The SDK was pointed at the proxy exactly as in step 2: `ANTHROPIC_BASE_URL` set to the proxy and `ANTHROPIC_API_KEY` set to the proxy's key. The middleware does not read either. - -- Setup: anthropic-sdk-go v1.82.0, Go 1.24.3, OpenTelemetry Go v1.33.0, model `claude-haiku-5-5`, local Future AGI collector, `go run ./example -stream -fail`. -- Tool use: a trace is the agent span, an LLM span that asks for `get_weather`, the TOOL span and an LLM span with the answer. The streamed answer is one span with its token counts (483 input, 26 output). -- Failure: a call with a model id that does not exist is an LLM span with status ERROR and no content beyond the request. -- Stored spans: type `llm`, `provider` anthropic, the model, input and output tokens (403/50 for the tool-asking call), and Input and Output filled. `fi_verify` passed. -- Privacy: with `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true`, a unique marker (also sent as an email address and a file path) was absent from every stored column of the project, including resource attributes and span events. With the defaults, the marker was present in the Input and Output columns. The Future AGI keys, the proxy key, host name, user name and home directory were never stored. The SDK's own span still stored the proxy's address (`server.address`, `url.full`), as described under Privacy. - -## Limitations - -- Not yet run against `api.anthropic.com` with an Anthropic API key (see the warning at the top). -- Amazon Bedrock and Google Vertex clients use the same middleware but are not tested. A Bedrock streaming response (binary event stream) is passed through without LLM attributes. -- `count_tokens`, message batches, files and models calls get no LLM attributes. -- Cost in Observe is computed from `gen_ai.usage.input_tokens`, which includes cached tokens, so prompt-cache discounts are not reflected. -- The module needs anthropic-sdk-go v1.82.0 or later. Older SDK versions are not supported. +The SDK's own span includes the API endpoint (`url.full`, `server.address`). If you use an internal gateway and must hide its address, disable the SDK's tracing with `ANTHROPIC_OPEN_TELEMETRY=false`; the middleware still traces Messages calls without those endpoint fields. ## Troubleshooting -| Symptom | Cause and fix | +| Symptom | Fix | | --- | --- | -| No traces | The program exited before the exporter flushed. Make sure `tp.Shutdown` runs (it does not after `log.Fatal` or `os.Exit`). Check that both `X-Api-Key` and `X-Secret-Key` are set and that `project_name` is a resource attribute, not a span attribute. | -| Spans arrive with empty Input and Output | The middleware is not on the client: these are anthropic-sdk-go's own spans. Pass `option.WithMiddleware(traceaianthropic.Middleware())` to `anthropic.NewClient`. | -| Two spans per call | The SDK's span is created by a tracer provider that is not the OpenTelemetry Go SDK, so the middleware cannot recognize it and opens its own. Use the OpenTelemetry Go SDK provider, or turn the SDK's spans off with `option.WithoutOpenTelemetry()`. | -| A streamed call never shows up | The span ends when the stream is read to the end or closed. Read the stream to the end, or `defer stream.Close()`. | -| Content still visible with `FI_HIDE_*` set | Check `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE` (see Privacy), and that the variables are set before `Middleware()` is called. Values must be `true` or `false`. | -| Exporter errors or traces are dropped | Send uncompressed OTLP/HTTP protobuf: keep `WithCompression(otlptracehttp.NoCompression)` and the full `/tracer/v1/traces` path. | - -## Next Steps - -- [TraceConfig and the FI_HIDE_* variables](/docs/sdk/tracing/trace-config) -- [Sessions](/docs/observe/features/session) -- [Anthropic (Python and TypeScript)](/docs/integrations/traceai/anthropic) +| No traces | Ensure `tp.Shutdown` runs before exit. Check both Future AGI headers and the `project_name` resource attribute. | +| Empty Input and Output | Add the traceAI middleware to the client; the SDK's default metadata-only spans do not populate these fields. | +| Two spans per call | Reuse the OpenTelemetry Go SDK tracer provider. The middleware recognizes the SDK's existing span through that provider. | +| Missing streamed call | Read the stream to the end or close it before shutting down the tracer provider. | +| Content remains visible | Leave the SDK's content mode unset and set `FI_HIDE_*` before constructing the middleware. | +| Exporter rejects requests | Use uncompressed OTLP/HTTP protobuf and the full `/tracer/v1/traces` path. | + +For other languages, see [Anthropic Python and TypeScript](/docs/integrations/traceai/anthropic) or [Anthropic Java](/docs/integrations/traceai/java/anthropic).