diff --git a/.github/workflows/ruby-llm-docs.yml b/.github/workflows/ruby-llm-docs.yml
new file mode 100644
index 000000000..cbf99d490
--- /dev/null
+++ b/.github/workflows/ruby-llm-docs.yml
@@ -0,0 +1,44 @@
+name: RubyLLM documentation
+
+on:
+ pull_request:
+ branches: [main]
+ paths:
+ - src/pages/docs/integrations/frameworks/ruby-llm.mdx
+ - scripts/ruby-llm-*.test.*
+ - .github/workflows/ruby-llm-docs.yml
+
+permissions:
+ contents: read
+
+jobs:
+ native-tracing:
+ name: Native tracing (Ruby ${{ matrix.ruby }}, RubyLLM ${{ matrix.ruby_llm }})
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ strategy:
+ fail-fast: false
+ matrix:
+ ruby: ['3.2', '3.4']
+ ruby_llm: ['2.1.0', '2.1.1']
+ steps:
+ - uses: actions/checkout@v4
+ - uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: ${{ matrix.ruby }}
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ - name: Install published framework and exporter gems
+ run: >-
+ gem install --no-document ruby_llm:${{ matrix.ruby_llm }}
+ opentelemetry-sdk:1.10.0 opentelemetry-exporter-otlp:0.32.0
+ webrick:1.9.1 minitest:5.25.5
+ - name: Check the native and legacy page contracts
+ run: node --test scripts/ruby-llm-page.test.mjs
+ - name: Run the snippets with only loopback networking
+ # A private network namespace blocks provider/OTLP egress, even on regressions.
+ run: |
+ sudo --preserve-env=GEM_HOME,GEM_PATH env PATH="$PATH" \
+ RUBY_LLM_VERSION="${{ matrix.ruby_llm }}" \
+ unshare --net sh -c 'ip link set lo up; ruby scripts/ruby-llm-native.test.rb'
diff --git a/scripts/ruby-llm-native.test.rb b/scripts/ruby-llm-native.test.rb
new file mode 100644
index 000000000..718c83b07
--- /dev/null
+++ b/scripts/ruby-llm-native.test.rb
@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# Uses released gems and real RubyLLM HTTP calls, with synthetic loopback services.
+# Install ruby_llm ($RUBY_LLM_VERSION), opentelemetry-sdk (1.10.0),
+# opentelemetry-exporter-otlp (0.32.0), webrick (1.9.1), and minitest (5.25.5).
+# Run: RUBY_LLM_VERSION=2.1.1 ruby scripts/ruby-llm-native.test.rb
+require 'minitest/autorun'
+require 'json'
+require 'open3'
+require 'tmpdir'
+require 'webrick'
+require 'zlib'
+require 'stringio'
+require 'net/http'
+gem 'opentelemetry-sdk', '1.10.0'
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+
+class RubyLLMNativeTest < Minitest::Test
+ VERSION = ENV.fetch('RUBY_LLM_VERSION', '2.1.1')
+ PAGE = File.read(File.expand_path('../src/pages/docs/integrations/frameworks/ruby-llm.mdx', __dir__))
+ REQUEST = Opentelemetry::Proto::Collector::Trace::V1::ExportTraceServiceRequest
+ CANARY = 'SYNTHETIC_PRIVATE'
+
+ def setup
+ @wire = Queue.new
+ @provider_requests = Queue.new
+ @server = WEBrick::HTTPServer.new(Port: 0, BindAddress: '127.0.0.1',
+ Logger: WEBrick::Log.new(File::NULL), AccessLog: [])
+ @server.mount_proc('/tracer/v1/traces') do |req, res|
+ body = req['content-encoding'] == 'gzip' ? Zlib::GzipReader.new(StringIO.new(req.body)).read : req.body
+ decoded = if req['content-type'] == 'application/json'
+ REQUEST.decode_json(body)
+ else
+ REQUEST.decode(body)
+ end
+ @wire << { request: decoded, headers: req.header, body: body }
+ res['Content-Type'] = req['content-type']
+ res.body = req['content-type'] == 'application/json' ? '{}' : ''.b
+ end
+ @server.mount_proc('/v1') { |req, res| provider_response(req, res) }
+ @thread = Thread.new { @server.start }
+ @origin = "http://127.0.0.1:#{@server.config[:Port]}"
+ end
+
+ def teardown
+ @server.shutdown
+ @thread.join
+ end
+
+ def snippet(name)
+ PAGE.match(/```ruby title="#{Regexp.escape(name)}"\n(.*?)\n```/m)&.captures&.first ||
+ flunk("Missing runnable #{name} block")
+ end
+
+ def run_app(program = snippet('chat.rb'), compression: 'none')
+ Dir.mktmpdir('ruby-llm-native') do |dir|
+ File.write(File.join(dir, 'tracing.rb'), snippet('tracing.rb').sub('compression: "none"', "compression: #{compression.inspect}"))
+ File.write(File.join(dir, 'chat.rb'), program)
+ File.write(File.join(dir, 'prelude.rb'), <<~RUBY)
+ gem 'ruby_llm', #{VERSION.inspect}
+ gem 'opentelemetry-sdk', '1.10.0'
+ gem 'opentelemetry-exporter-otlp', '0.32.0'
+ require 'ruby_llm'
+ RubyLLM.configure do |config|
+ config.openai_api_base = #{"#{@origin}/v1".inspect}
+ config.openai_api_key = 'synthetic-openai-key'
+ config.max_retries = 0
+ config.request_timeout = 5
+ end
+ RUBY
+ env = {
+ 'PATH' => ENV.fetch('PATH'), 'HOME' => dir,
+ 'GEM_HOME' => ENV['GEM_HOME'], 'GEM_PATH' => ENV['GEM_PATH'],
+ 'FI_BASE_URL' => "#{@origin}/", 'FI_PROJECT_NAME' => 'native-ruby-test',
+ 'FI_API_KEY' => 'synthetic-fi-key', 'FI_SECRET_KEY' => 'synthetic-fi-secret',
+ 'OPENAI_API_KEY' => 'synthetic-openai-key',
+ 'OTEL_BSP_SCHEDULE_DELAY' => '60000',
+ # Legacy content switches must not change native privacy behavior.
+ 'FI_CAPTURE_CONTENT' => '1', 'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT' => 'true'
+ }
+ stdout, stderr, status = Open3.capture3(env, RbConfig.ruby, '-r', File.join(dir, 'prelude.rb'),
+ File.join(dir, 'chat.rb'), unsetenv_others: true)
+ assert status.success?, "RubyLLM #{VERSION} failed:\n#{stdout}\n#{stderr}"
+ refute_match(/ERROR|Failed to export|Unable to export/, stderr)
+ end
+ refute @wire.empty?, 'Documented shutdown must export spans'
+ items = []
+ items << @wire.pop until @wire.empty?
+ items
+ end
+
+ def attributes(list)
+ list.to_h { |kv| [kv.key, kv.value.public_send(kv.value.value)] }
+ end
+
+ def spans(items)
+ items.flat_map { |item| item[:request].resource_spans.flat_map { |rs| rs.scope_spans.flat_map(&:spans) } }
+ end
+
+ def assert_envelope(items, compression)
+ items.each do |item|
+ assert_equal ['synthetic-fi-key'], item[:headers]['x-api-key']
+ assert_equal ['synthetic-fi-secret'], item[:headers]['x-secret-key']
+ assert_equal ['application/x-protobuf'], item[:headers]['content-type']
+ assert_equal(compression == 'gzip' ? ['gzip'] : [], item[:headers]['content-encoding'])
+ item[:request].resource_spans.each do |rs|
+ resource = attributes(rs.resource.attributes)
+ assert_equal 'native-ruby-test', resource['project_name']
+ assert_equal 'observe', resource['project_type']
+ assert_equal 'ruby-llm-app', resource['service.name']
+ rs.scope_spans.select { |ss| ss.scope.name == 'ruby_llm' }.each do |ss|
+ assert_equal VERSION, ss.scope.version
+ end
+ end
+ refute_includes REQUEST.encode_json(item[:request]), CANARY
+ refute_includes item[:body], 'synthetic-openai-key'
+ refute_includes item[:body], 'synthetic-fi-secret'
+ end
+ end
+
+ def test_exact_documented_chat_exports_plain_protobuf_at_exit
+ items = run_app
+ assert_envelope(items, 'none')
+ assert_equal 1, spans(items).size
+ chat = spans(items).first
+ assert_equal 'chat gpt-4o-mini', chat.name
+ assert_equal 'chat', attributes(chat.attributes)['gen_ai.operation.name']
+ assert_equal 'openai', attributes(chat.attributes)['gen_ai.provider.name']
+ assert_equal 10, attributes(chat.attributes)['gen_ai.usage.input_tokens']
+ assert_equal 5, attributes(chat.attributes)['gen_ai.usage.output_tokens']
+ assert_equal '/v1/responses', @provider_requests.pop[:path]
+ end
+
+ def test_tool_loop_keeps_context_and_per_request_usage_without_content_or_duplicate_spans
+ items = run_app(<<~RUBY, compression: 'gzip')
+ require_relative 'tracing'
+ RubyLLM::OpenTelemetry.enable # Calling enable again must not duplicate spans.
+ class Lookup < RubyLLM::Tool
+ description 'SYNTHETIC_PRIVATE_DESCRIPTION'
+ def execute(value:)
+ raise 'unexpected arguments' unless value == 'SYNTHETIC_PRIVATE_ARGUMENT'
+ 'SYNTHETIC_PRIVATE_RESULT'
+ end
+ end
+ OpenTelemetry.tracer_provider.tracer('test').in_span('application-request') do
+ RubyLLM.chat(model: 'gpt-4o-mini').with_tools(Lookup).ask('SYNTHETIC_PRIVATE_PROMPT')
+ end
+ RUBY
+ assert_envelope(items, 'gzip')
+ all = spans(items)
+ assert_equal 4, all.size # application root, two actual completions, one tool
+ root = all.find { |span| span.name == 'application-request' }
+ all.reject { |span| span == root }.each do |span|
+ assert_equal root.trace_id, span.trace_id
+ assert_equal root.span_id, span.parent_span_id
+ assert_empty span.events
+ assert_empty span.status.message
+ end
+ tool = all.find { |span| span.name == 'execute_tool lookup' }
+ refute_nil tool
+ assert_equal 'call_synthetic', attributes(tool.attributes)['gen_ai.tool.call.id']
+ chats = all.select { |span| attributes(span.attributes)['gen_ai.operation.name'] == 'chat' }
+ assert_equal [10, 20], chats.map { |span| attributes(span.attributes)['gen_ai.usage.input_tokens'] }.sort
+ assert_equal [5, 6], chats.map { |span| attributes(span.attributes)['gen_ai.usage.output_tokens'] }.sort
+ assert_equal 2, @provider_requests.size
+ end
+
+ def test_stream_and_error_metadata_remain_private
+ items = run_app(<<~RUBY)
+ require_relative 'tracing'
+ text = +''
+ RubyLLM.chat(model: 'gpt-4o-mini', protocol: :chat_completions).ask('SYNTHETIC_PRIVATE_STREAM') do |chunk|
+ text << chunk.content.to_s
+ end
+ raise 'stream missing' unless text == 'SYNTHETIC_PRIVATE_ANSWER'
+ begin
+ RubyLLM.chat(model: 'gpt-4o-mini').ask('SYNTHETIC_PRIVATE_ERROR')
+ raise 'provider error was swallowed'
+ rescue RubyLLM::BadRequestError
+ # The library must preserve application error behavior without exporting error text.
+ end
+ RUBY
+ assert_envelope(items, 'none')
+ assert_equal 2, spans(items).size
+ stream = spans(items).find { |span| attributes(span.attributes)['gen_ai.request.stream'] }
+ refute_nil stream
+ assert_equal 10, attributes(stream.attributes)['gen_ai.usage.input_tokens']
+ error = spans(items).find { |span| span.status.code == :STATUS_CODE_ERROR }
+ refute_nil error
+ assert_equal 'RubyLLM::BadRequestError', attributes(error.attributes)['error.type']
+ assert_empty error.status.message
+ assert_empty error.events
+ end
+
+ def test_exported_payload_round_trips_json_and_protobuf_plain_and_gzip
+ # Ruby exports protobuf only. JSON is a wire-codec replay, not a claimed Ruby exporter mode.
+ original = run_app.first[:request]
+ %w[protobuf json].product(%w[none gzip]).each do |format, compression|
+ body = format == 'json' ? REQUEST.encode_json(original) : REQUEST.encode(original)
+ if compression == 'gzip'
+ io = StringIO.new
+ writer = Zlib::GzipWriter.new(io)
+ writer.write(body)
+ writer.close
+ body = io.string
+ end
+ uri = URI("#{@origin}/tracer/v1/traces")
+ request = Net::HTTP::Post.new(uri)
+ request['Content-Type'] = format == 'json' ? 'application/json' : 'application/x-protobuf'
+ request['Content-Encoding'] = 'gzip' if compression == 'gzip'
+ request.body = body
+ response = Net::HTTP.start(uri.host, uri.port, nil) { |http| http.request(request) }
+ assert_equal '200', response.code
+ assert_equal original, @wire.pop[:request]
+ end
+ end
+
+ def provider_response(req, res)
+ data = JSON.parse(req.body)
+ @provider_requests << { path: req.path, data: data }
+ res['Content-Type'] = 'application/json'
+ if req.body.include?('SYNTHETIC_PRIVATE_ERROR')
+ res.status = 400
+ res.body = JSON.generate(error: { message: 'SYNTHETIC_PRIVATE_PROVIDER_ERROR', type: 'invalid_request_error' })
+ elsif data['stream']
+ res['Content-Type'] = 'text/event-stream'
+ chunks = [
+ { choices: [{ index: 0, delta: { role: 'assistant', content: 'SYNTHETIC_PRIVATE_ANSWER' }, finish_reason: nil }] },
+ { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+ { choices: [], usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 } }
+ ]
+ res.body = chunks.map { |chunk| "data: #{JSON.generate(chunk.merge(id: 'synthetic-stream', object: 'chat.completion.chunk', model: 'gpt-4o-mini'))}\n\n" }.join + "data: [DONE]\n\n"
+ else
+ followup = Array(data['input']).any? { |entry| entry['type'] == 'function_call_output' }
+ output = if data['tools']&.any? && !followup
+ [{ type: 'function_call', name: 'lookup', call_id: 'call_synthetic',
+ arguments: JSON.generate(value: 'SYNTHETIC_PRIVATE_ARGUMENT') }]
+ else
+ [{ type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'SYNTHETIC_PRIVATE_ANSWER' }] }]
+ end
+ res.body = JSON.generate(id: 'synthetic-response', object: 'response', status: 'completed',
+ model: 'gpt-4o-mini', output: output,
+ usage: { input_tokens: followup ? 20 : 10, output_tokens: followup ? 6 : 5 })
+ end
+ end
+end
diff --git a/scripts/ruby-llm-page.test.mjs b/scripts/ruby-llm-page.test.mjs
new file mode 100644
index 000000000..7447640d5
--- /dev/null
+++ b/scripts/ruby-llm-page.test.mjs
@@ -0,0 +1,38 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const page = readFileSync(new URL('../src/pages/docs/integrations/frameworks/ruby-llm.mdx', import.meta.url), 'utf8');
+const [native, legacy = ''] = page.split('## Existing RubyLLM 1.x installations');
+
+test('RubyLLM uses released native tracing as the default', () => {
+ assert.match(native, /gem "ruby_llm", "2\.1\.1"/);
+ assert.match(native, /Ruby 3\.2 or newer/);
+ assert.match(native, /RubyLLM::OpenTelemetry\.enable/);
+ assert.doesNotMatch(native, /gem "opentelemetry-instrumentation-ruby_llm"|class SanitizingExporter/);
+ assert.match(native, /"project_name" =>/);
+ assert.match(native, /"project_type" => "observe"/);
+ assert.match(native, /"X-Api-Key" => ENV.fetch\("FI_API_KEY"\)/);
+ assert.match(native, /"X-Secret-Key" => ENV.fetch\("FI_SECRET_KEY"\)/);
+ assert.match(native, /\/tracer\/v1\/traces/);
+ assert.match(native, /tracer_provider.shutdown/);
+});
+
+test('native setup does not promise legacy content or session parity', () => {
+ assert.match(native, /metadata only/i);
+ assert.match(native, /does not export prompts, responses, tool arguments or results/);
+ assert.match(native, /does not provide.*content-capture/s);
+ assert.match(native, /does not add.*session.*user/s);
+ assert.match(native, /Do not enable.*third-party.*native/s);
+});
+
+test('existing 1.x users retain their bounded compatibility and privacy reference', () => {
+ assert.match(legacy, /gem "ruby_llm", "1\.16\.0"/);
+ assert.match(legacy, /gem "opentelemetry-instrumentation-ruby_llm", "0\.7\.1"/);
+ assert.match(legacy, /class SanitizingExporter/);
+ assert.match(legacy, /copy.events = nil/);
+ assert.match(legacy, /capture_content: true/);
+ assert.match(legacy, /with_otel_attributes/);
+ assert.match(legacy, /invoke_agent/);
+ assert.match(legacy, /token counts.*inflated/s);
+});
diff --git a/src/pages/docs/integrations/frameworks/ruby-llm.mdx b/src/pages/docs/integrations/frameworks/ruby-llm.mdx
index 45756c6ce..89fa55b33 100644
--- a/src/pages/docs/integrations/frameworks/ruby-llm.mdx
+++ b/src/pages/docs/integrations/frameworks/ruby-llm.mdx
@@ -1,17 +1,133 @@
---
title: "Ruby LLM tracing with Future AGI"
-description: "Send ruby_llm chat, tool and agent spans to Future AGI with the OpenTelemetry Ruby SDK and the opentelemetry-instrumentation-ruby_llm gem. Use the metadata-only default or opt in to content capture."
+description: "Trace RubyLLM with its native OpenTelemetry integration. Send model, token usage, tool and error metadata to Future AGI without capturing message content."
---
-Trace RubyLLM chat and tool calls in Future AGI using the third-party `opentelemetry-instrumentation-ruby_llm` gem and the OpenTelemetry Ruby SDK. This guide covers the OpenAI provider and a self-hosted Future AGI endpoint.
+## Prerequisites
+
+- Ruby 3.2 or newer and RubyLLM 2.1. This guide uses the released `ruby_llm` 2.1.1 gem.
+- Future AGI API and secret keys, and an OpenAI API key for the example.
+
+
+Native tracing in RubyLLM 2.1.1 sends metadata only: it does not export prompts, responses, tool arguments or results, or exception messages. It does not provide a content-capture option. If your existing 1.x application relies on content capture, agent root spans, or session and user attributes, read [Existing RubyLLM 1.x installations](#existing-rubyllm-1x-installations) before migrating.
+
+
+## Install
+
+```ruby title="Gemfile"
+source "https://rubygems.org"
+
+gem "ruby_llm", "2.1.1"
+gem "opentelemetry-sdk", "1.10.0"
+gem "opentelemetry-exporter-otlp", "0.32.0"
+```
+
+```bash
+bundle install
+```
+
+The exporter version above supports Ruby 3.2. Exporter 0.33 and later requires Ruby 3.3 or newer. You do not need the third-party `opentelemetry-instrumentation-ruby_llm` gem for native tracing.
+
+## Configure tracing
+
+```bash
+export FI_API_KEY="YOUR_API_KEY"
+export FI_SECRET_KEY="YOUR_SECRET_KEY"
+export FI_PROJECT_NAME="ruby-llm"
+export FI_BASE_URL="https://api.futureagi.com"
+export OPENAI_API_KEY="YOUR_OPENAI_KEY"
+```
+
+For self-hosted Future AGI, set `FI_BASE_URL` to your instance's origin without a path. The configuration below adds `/tracer/v1/traces` and sends both authentication headers. `project_name` must be a **resource attribute**, not a span attribute.
+
+Save this standard OpenTelemetry configuration as `tracing.rb` and load it once at application startup, before making RubyLLM calls:
+
+```ruby title="tracing.rb"
+require "ruby_llm"
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+
+exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
+ endpoint: "#{ENV.fetch('FI_BASE_URL').chomp('/')}/tracer/v1/traces",
+ headers: {
+ "X-Api-Key" => ENV.fetch("FI_API_KEY"),
+ "X-Secret-Key" => ENV.fetch("FI_SECRET_KEY")
+ },
+ compression: "none"
+)
+
+OpenTelemetry::SDK.configure do |config|
+ config.service_name = "ruby-llm-app"
+ config.resource = OpenTelemetry::SDK::Resources::Resource.create(
+ "project_name" => ENV.fetch("FI_PROJECT_NAME"),
+ "project_type" => "observe"
+ )
+ config.add_span_processor(
+ OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+ )
+end
+
+RubyLLM::OpenTelemetry.enable
+at_exit { OpenTelemetry.tracer_provider.shutdown }
+```
+
+`compression: "none"` also works with self-hosted releases before v1.56.0, which reject gzip. Cloud and self-hosted v1.56.0 or later also accept `compression: "gzip"`. The Ruby exporter sends OTLP/HTTP protobuf.
+
+If your application already configures OpenTelemetry, add the exporter, processor and project resource to that existing setup rather than configuring a second provider. Then call `RubyLLM::OpenTelemetry.enable` once.
-Use `ruby_llm` 1.x with instrumentation version 0.7.1. With RubyLLM 2.0.0 and 2.1.1, the instrumentation raises an error on `chat.ask`. RubyLLM versions before 1.8.0 are not supported by the instrumentation.
+Do not enable the third-party instrumentation gem and native tracing together. When migrating, remove the old gem and its `config.use "OpenTelemetry::Instrumentation::RubyLLM"` call, stop loading `futureagi_tracing.rb`, and restart the process. Removing the configuration without restarting does not undo an already installed patch.
-On Ruby 3.2, use `opentelemetry-exporter-otlp` 0.32.0; version 0.33 and later requires Ruby 3.3 or newer.
+## Run a chat
+
+Save `chat.rb` next to `tracing.rb`:
+
+```ruby title="chat.rb"
+require_relative "tracing"
+
+RubyLLM.configure { |config| config.openai_api_key = ENV.fetch("OPENAI_API_KEY") }
+
+chat = RubyLLM.chat(model: "gpt-4o-mini")
+response = chat.ask("What is OpenTelemetry?")
+puts response.content
+```
+
+```bash
+bundle exec ruby chat.rb
+```
+
+Open **Observe** in Future AGI and select the project named by `FI_PROJECT_NAME`. Look for `chat gpt-4o-mini` and inspect its model, provider, duration and token usage. Prompt and response panels remain empty because native RubyLLM 2.1.1 does not export content.
+
+The exit hook flushes pending spans on a normal process exit. For a managed server, call `OpenTelemetry.tracer_provider.shutdown` in its stop hook. Do not shut down the provider after each request.
-## 1. Install
+## What native tracing captures
+
+- **Chat and streaming:** a `chat ` span for each model request, with model/provider metadata and token usage when reported by the provider. Streaming produces one span for the request, not one per chunk.
+- **Tools:** `execute_tool ` spans with the tool name and call ID, without arguments, results or descriptions. Follow-up model requests are separate chat spans.
+- **Errors:** an `ERROR` status and `error.type`, without the provider error message or exception stack trace.
+
+These privacy defaults apply to RubyLLM's native spans, not to attributes or events added by your application or other instrumentation. Use non-sensitive tool and workflow names because names are exported.
+
+Native RubyLLM 2.1.1 does not add an `invoke_agent` root or session and user attributes, and does not expose the third-party `with_otel_attributes` API. Do not expect a 1.x application's content capture or session grouping to carry over automatically. Follow the [RubyLLM upgrade guide](https://rubyllm.com/upgrading/) for application API changes as well.
+
+## Troubleshooting
+
+- **No traces:** confirm both Future AGI keys, the origin in `FI_BASE_URL`, and the `project_name` resource attribute. Check exporter logs for HTTP failures.
+- **`NoMethodError` mentioning `model_id`:** the old third-party patch is still active with RubyLLM 2.x. Remove it and restart the process before using native tracing.
+- **No prompt or response text:** expected for native tracing in 2.1.1. Setting `FI_CAPTURE_CONTENT` or the third-party capture environment variable does not enable native content capture.
+- **Missing spans at exit:** allow the shutdown hook to complete. Forced termination such as `kill -9` cannot flush queued spans.
+
+## Existing RubyLLM 1.x installations
+
+Keep an existing 1.x setup on its pinned dependencies until you can migrate its application APIs and tracing behavior together. The legacy route below retains opt-in content capture, `with_otel_attributes`, and `invoke_agent` spans; the native 2.1.1 route is not a drop-in replacement for those features. Its exporter safeguard is still required: the legacy instrumentation's `capture_content: false` does not suppress tool data or exception events by itself.
+
+
+Legacy reference for existing 1.x applications
+
+This reference is for applications already using `FutureAGITracing`. For new applications, use the native setup above. Do not combine the two configurations.
+
+### Legacy dependencies
```ruby title="Gemfile"
source "https://rubygems.org"
@@ -22,9 +138,9 @@ gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
```
-The instrumentation gem depends only on `opentelemetry-api` and `opentelemetry-instrumentation-base`. The SDK and the OTLP exporter are yours to add. Pin `ruby_llm` below 2.0 (`"~> 1.16"`).
+Keep the OpenTelemetry version pins already working in your 1.x application. The instrumentation gem depends only on `opentelemetry-api` and `opentelemetry-instrumentation-base`; the SDK and exporter remain separate dependencies. Keep `ruby_llm` below 2.0 (`"~> 1.16"`).
-## 2. Set environment variables
+### Legacy environment variables
```bash
export FI_API_KEY="YOUR_API_KEY"
@@ -38,9 +154,9 @@ export FI_BASE_URL="http://localhost:4318" # replace with your instance
Set `FI_BASE_URL` to the origin only. The code adds `/tracer/v1/traces`.
-## 3. Add the helper file
+### Keep the legacy exporter safeguard
-The instrumentation gem sets no endpoint, headers or project. The OpenTelemetry SDK you configure does, and Future AGI needs all three: the OTLP/HTTP endpoint, both `X-Api-Key` and `X-Secret-Key`, and the resource attribute `project_name` (a span attribute of that name is not a substitute). Save this as `futureagi_tracing.rb`:
+The instrumentation gem sets no endpoint, headers or project. The OpenTelemetry SDK you configure does, and Future AGI needs all three: the OTLP/HTTP endpoint, both `X-Api-Key` and `X-Secret-Key`, and the resource attribute `project_name` (a span attribute of that name is not a substitute). Keep the following safeguard in your existing `futureagi_tracing.rb`:
```ruby title="futureagi_tracing.rb"
# frozen_string_literal: true
@@ -176,9 +292,9 @@ end
Two details in it matter. `compression: "none"` is there because the Ruby OTLP exporter gzips by default and self-hosted releases before v1.56.0 answered gzip with HTTP 400. Future AGI cloud and self-hosted v1.56.0 and later accept gzip, so the line is optional there. The `SanitizingExporter` is there because of what the instrumentation exports, described under privacy below.
-## 4. Use it
+### Legacy application setup
-Save the following as `chat.rb` next to the helper. It calls `setup` once at boot, before any `RubyLLM` call.
+Existing applications call `setup` once at boot, before any `RubyLLM` call:
```ruby
require_relative "futureagi_tracing"
@@ -207,9 +323,9 @@ chat.ask("Hi")
chat.ask("And now?")
```
-Both calls land in one Future AGI session. RubyLLM spans carry no session or user unless you set them. The instrumentation sets `gen_ai.conversation.id` only for persisted `acts_as_chat` records or when you set it yourself; `gen_ai.conversation.id` on its own is outside this guide’s coverage as a session key.
+The legacy spans include the same `session.id` and `user.id` on both calls for session grouping. RubyLLM spans carry no session or user unless you set them. The instrumentation sets `gen_ai.conversation.id` only for persisted `acts_as_chat` records or when you set it yourself; `gen_ai.conversation.id` on its own is outside this guide’s coverage as a session key.
-## What is captured
+### Legacy captured data
| Case | What you get |
| --- | --- |
@@ -222,7 +338,7 @@ Both calls land in one Future AGI session. RubyLLM spans carry no session or use
Everything RubyLLM does not report is absent, not zero.
-## Privacy: metadata only by default
+### Legacy privacy settings
With no opt-in, Future AGI receives model, provider, token counts, span names and timing, tool names, agent names, status and `error.type`, and the `session.id`, `user.id` and `gen_ai.conversation.id` you set. It does not receive prompts, answers, system instructions, tool arguments, tool results, tool descriptions, error messages, stack traces, local paths, host names, or any other attribute you set with `with_otel_attributes`.
@@ -230,14 +346,14 @@ The instrumentation's `capture_content` switch alone does not suppress tool argu
To opt in, set `FI_CAPTURE_CONTENT=1` or call `FutureAGITracing.setup(capture_content: true)`. That turns on `gen_ai.input.messages`, `gen_ai.output.messages` and `gen_ai.system_instructions` (prompts and answers), keeps the tool arguments, results and descriptions, and keeps every other attribute you set. Span events, and so exception messages and stack traces, are never exported, in either mode. Content arrives as span attributes and may not appear in the trace's Input and Output panels.
-## Limitations
+### Legacy limitations
-- `ruby_llm` 2.x is not supported (above).
+- The legacy instrumentation does not support `ruby_llm` 2.x. Use the native route above when migrating to 2.1.
- In a tool loop the outer `chat` span reports the token counts of the final response, the same numbers as the follow-up `chat` span under it, so summed token counts for the trace are inflated. This comes from the instrumentation: it reads the last message after the nested completion returns.
- `invoke_agent` spans show as type `unknown` in Future AGI: the instrumentation sets no `fi.span.kind`.
- The instrumentation exports `gen_ai.usage.cache_creation.input_tokens=0` when the provider reports none. Future AGI tokens are unaffected.
-## Troubleshooting
+### Legacy troubleshooting
- **`NoMethodError ... 'model_id'` on `chat.ask`.** You are on `ruby_llm` 2.x. Pin `ruby_llm` to 1.x.
- **No traces for the project.** `project_name` must be a resource attribute, which `setup` sets. A missing `FI_PROJECT_NAME` falls back to `ruby-llm`: look there.
@@ -246,3 +362,5 @@ To opt in, set `FI_CAPTURE_CONTENT=1` or call `FutureAGITracing.setup(capture_co
- **Short script, zero spans.** Call `FutureAGITracing.shutdown` before exit, and do not `kill -9` the process.
- **Content shows up when you did not opt in.** Check that `FI_CAPTURE_CONTENT` is unset and that you are using `SanitizingExporter` through `setup`. `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` turns the instrumentation's content on, but the exporter still drops it unless you opted in here.
- **`RubyLLM::ModelNotFoundError: Unknown model`**. Pass `provider: :openai, assume_model_exists: true` for a model RubyLLM does not list, such as a model behind an OpenAI-compatible endpoint.
+
+