Skip to content

feat: fi.sampling.ratio on spans kept by head sampling across the traceAI SDKs - #713

Merged
nik13 merged 56 commits into
devfrom
feat/sampling-ratio-1117
Nov 17, 2026
Merged

nik13 merged 56 commits into
devfrom
feat/sampling-ratio-1117

Conversation

@nik13

@nik13 nik13 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Adds fi.sampling.ratio, so Future AGI can estimate true counts and cost from head-sampled traces. It applies wherever a traceAI SDK or agent creates its own tracer provider, in all six SDKs.

Behaviour

  • When traceAI's own ratio sampler keeps a trace at a rate below 1 (from FI_SAMPLE_RATE, OTEL_TRACES_SAMPLER=traceidratio|parentbased_traceidratio, or the Java/C# register sampler option built by traceAI's own factory), every kept span carries fi.sampling.ratio (a double in (0, 1)). The rate is also written to the W3C tracestate as fi=r:<rate>.
  • Under a parent-based sampler, a span kept because its parent is sampled copies the parent's valid fi entry. This holds even when its own root rate is 1, so every kept span of a trace carries the same value across services.
  • Never stamped:
    • a locally decided root at rate 1;
    • always_on / always_off;
    • unknown custom samplers;
    • dropped or record-only spans;
    • an invalid parent context;
    • an upstream decision without an fi entry;
    • application-owned providers.
  • Absent means 1.0. Sampling decisions are unchanged; only span attributes and tracestate are added.

Languages

Python (fi_instrumentation.auto), TypeScript (@traceai/auto), Java (core + agent), Go (go/auto), C# (FIInstrumentation + auto), Ruby (traceai-auto). Each language has tests, then the implementation, then docs.

Known limits

  • Full tracestate: W3C tracestate holds at most 32 entries. If an incoming tracestate is already full and has no fi entry, there is no room to add one. The kept span still carries fi.sampling.ratio, but descendants in other processes count as 1.0.
  • Orphan spans in Node (pre-existing): when an upstream service drops a trace, the Node agent currently starts a new root for the next AI call instead of honouring the non-recording incoming parent (typescript/packages/traceai_auto/src/agent-context.ts). This is unrelated to this change and is tracked separately.

Also fixes a regression already on dev

The zero-code Node agent read its sampler settings through getStringFromEnv from @opentelemetry/core. Hosts that resolve the older @opentelemetry/core 1.30.1 (for example the Vercel AI SDK packages' install) lack that helper, so the agent failed to initialize there. This came in with the sampler work in #711. The agent now builds its sampler from public constructors that work across OpenTelemetry versions.

How it was tested

  • Each language's full test suite ran on a CI-like VM after its last change; the Java agent's verify passed (967 tests, including 188 child-JVM end-to-end tests); Go passed under -race.
  • A cross-language end-to-end test (a Python service at FI_SAMPLE_RATE=0.5 calling a Node service with default settings) exports fi.sampling.ratio=0.5 on all three spans of a kept trace, with correct parentage.
  • The Vercel AI SDK suite never ran on feat: honour OTEL_TRACES_SAMPLER and add sampler options across the traceAI SDKs #711. It runs here: 280 tests, including all 18 cases for a host with no OpenTelemetry of its own.

nik13 added 30 commits November 17, 2026 12:46
nik13 added 24 commits November 17, 2026 12:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant