feat(agents): add OpenTelemetry telemetry support by zrosenbauer · Pull Request #75 · joggrdocs/funkai

zrosenbauer · 2026-04-01T03:30:58Z

Summary

Thread telemetry settings through agents, flow agents, and flow engines to the AI SDK's experimental_telemetry option
Auto-enrich spans with functionId (defaults to agent name) and funkai.agentChain metadata for multi-agent trace visibility
Telemetry propagates to sub-agents and merges across layers (engine -> flow -> agent -> per-call) with shallow-merged metadata
Add telemetry docs with provider setup guides (Braintrust, VoltAgent, Langfuse, Laminar, PostHog, SigNoz/Jaeger/OTLP)

Changes

File	Description
`base/telemetry.ts`	New `resolveTelemetry()` helper — merges config + override, auto-sets functionId and agentChain
`base/telemetry.test.ts`	10 unit tests for merge logic, chain serialization, precedence
`base/agent.ts`	Call `resolveTelemetry()` in `prepareGeneration()`, pass to AI SDK and sub-agents
`base/utils.ts`	Add `telemetry` to `ParentAgentContext` and `buildParentParams()`
`types.ts`	Add `telemetry` to `AgentConfig` and `AgentGenerateOverrides`, re-export `TelemetrySettings`
`flow/types.ts`	Add `telemetry` to `FlowAgentConfigBase`
`flow/flow-agent.ts`	Pass config telemetry to step builder
`flow/steps/factory.ts`	Thread telemetry through step builders and `$.agent()` calls
`flow/engine.ts`	Add `telemetry` to `FlowEngineConfig`, merge engine + flow telemetry
`index.ts`	Re-export `TelemetrySettings`
`docs/telemetry.md`	Full telemetry documentation mirroring Vercel AI SDK structure

Test plan

pnpm typecheck --filter=@funkai/agents — clean
pnpm test --filter=@funkai/agents — 664 tests pass (including 10 new telemetry tests)
CI passes

Thread telemetry settings through agents, flow agents, and flow engines to the AI SDK's experimental_telemetry option. Auto-enriches spans with functionId (defaults to agent name) and funkai.agentChain metadata for multi-agent trace visibility. Telemetry propagates to sub-agents and merges across layers with shallow-merged metadata. Co-Authored-By: Claude <noreply@anthropic.com>

changeset-bot · 2026-04-01T03:31:03Z

🦋 Changeset detected

Latest commit: deed9e0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@funkai/agents	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-04-01T03:31:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
funkai	Ready	Preview, Comment	Apr 2, 2026 4:42pm

coderabbitai · 2026-04-01T03:31:11Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds OpenTelemetry telemetry support across agents and flows: new telemetry config fields at engine/flow/agent/per-call layers, a resolver that shallow-merges metadata and injects functionId and funkai.agentChain, and threads resolved settings into the AI SDK as experimental_telemetry. Documentation and tests added.

Changes

Cohort / File(s)	Summary
Changeset & Docs `.changeset/telemetry-otel-support.md`, `packages/agents/docs/telemetry.md`	New changeset and comprehensive telemetry documentation describing enablement, span attributes, merge/precedence rules, provider examples, and TelemetrySettings reference.
Telemetry Core & Tests `packages/agents/src/core/agents/base/telemetry.ts`, `packages/agents/src/core/agents/base/telemetry.test.ts`	Added exported `resolveTelemetry(...)` to merge config and per-call telemetry (override wins), shallow-merge `metadata`, inject `funkai.agentChain` string, default `functionId` to agent name; tests cover precedence, merging, and edge cases.
Agent Base & Context plumbing `packages/agents/src/core/agents/base/agent.ts`, `packages/agents/src/core/agents/base/utils.ts`	Resolve telemetry during prepare, attach `telemetry` to `ParentAgentContext`, include telemetry in `buildParentParams`, and pass `experimental_telemetry` into AI SDK `generate()`/`stream()` calls.
Flow Engine / Flow Agent Integration `packages/agents/src/core/agents/flow/engine.ts`, `packages/agents/src/core/agents/flow/flow-agent.ts`, `packages/agents/src/core/agents/flow/types.ts`, `packages/agents/src/core/agents/flow/steps/factory.ts`	Added `telemetry` to FlowEngine/flow/flow-agent configs; engine merges engine & flow defaults (`mergeTelemetry`) with shallow metadata merge; threaded telemetry into step builder and ensured `$.agent()` forwards flow telemetry to sub-agents.
Types & Exports `packages/agents/src/core/agents/types.ts`, `packages/agents/src/index.ts`	Re-exported `TelemetrySettings` from `ai`; added `telemetry?: TelemetrySettings` to `AgentConfig` and per-call `AgentGenerateOverrides`; updated public exports to include telemetry types.

Sequence Diagram(s)

sequenceDiagram
    participant FlowEngine as FlowEngine
    participant FlowAgent as FlowAgent
    participant Agent as Agent
    participant AI as AI SDK

    FlowEngine->>FlowAgent: create flow (mergeTelemetry(engine.telemetry, flow.telemetry))
    activate FlowAgent
    FlowAgent->>FlowAgent: forward telemetry to StepBuilder
    loop for each $.agent() call
        FlowAgent->>Agent: call agent(params + telemetry)
        activate Agent
        Agent->>Agent: resolveTelemetry(config.telemetry, params.telemetry, agentName, agentChain)
        Note over Agent: precedence: override → agent → flow/engine\ninject functionId (agentName) if missing\ninject metadata["funkai.agentChain"] = "id1 > id2"
        Agent->>AI: generate/stream (experimental_telemetry: resolvedTelemetry)
        AI-->>Agent: emit spans (GenAI + funkai metadata)
        deactivate Agent
    end
    deactivate FlowAgent

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

feat(agents): input parameter parity with Vercel AI SDK #65 — direct overlap adding/forwarding telemetry and wiring experimental_telemetry through agent prepare/generation.
feat(agents): add agentChain propagation and fix flow agent step hook forwarding #50 — related to agentChain propagation used to populate metadata["funkai.agentChain"].
feat(agents): add middleware config and enable tool input examples by default #48 — modifies prepareGeneration to forward extra AI-SDK options; overlaps with experimental_telemetry passthrough.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding OpenTelemetry telemetry support to the agents package.
Description check	✅ Passed	The description comprehensively outlines the implementation details, file-by-file changes, and test coverage for the telemetry feature.
Docstring Coverage	✅ Passed	Docstring coverage is 81.82% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/agents/src/core/agents/types.ts`:
- Line 32: Add a JSDoc block above the exported type TelemetrySettings to
document the new public export: provide a one-line description, any relevant
property notes, and a short usage/example (e.g., "import type {
TelemetrySettings } from '@funkai/agents';"); ensure the block sits immediately
above the export statement "export type { TelemetrySettings } from 'ai';" and
include any required tags per project guidelines (e.g., `@example` and
`@typedef/`@type or `@remarks`) so the exported type is properly documented for
consumers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: aa3628b1-ea93-4833-85cd-520ad6b09a10

📥 Commits

Reviewing files that changed from the base of the PR and between a7d1e53 and 324e5c6.

📒 Files selected for processing (12)

.changeset/telemetry-otel-support.md
packages/agents/docs/telemetry.md
packages/agents/src/core/agents/base/agent.ts
packages/agents/src/core/agents/base/telemetry.test.ts
packages/agents/src/core/agents/base/telemetry.ts
packages/agents/src/core/agents/base/utils.ts
packages/agents/src/core/agents/flow/engine.ts
packages/agents/src/core/agents/flow/flow-agent.ts
packages/agents/src/core/agents/flow/steps/factory.ts
packages/agents/src/core/agents/flow/types.ts
packages/agents/src/core/agents/types.ts
packages/agents/src/index.ts

packages/agents/src/core/agents/types.ts

Merge separate `from "ai"` import statements to satisfy oxlint no-duplicates rule. Co-Authored-By: Claude <noreply@anthropic.com>

Co-Authored-By: Claude <noreply@anthropic.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/agents/docs/telemetry.md`:
- Around line 193-198: The fenced diagram showing telemetry precedence should
include a language identifier for formatting; update the code block to use a
language tag like ```text (or replace it with a Markdown quote block) so the
diagram containing FlowEngine.telemetry, FlowAgentConfig.telemetry,
AgentConfig.telemetry, and GenerateParams.telemetry is rendered consistently and
follows doc formatting standards.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a6261202-0d17-4e74-9021-5626c8e8e571

📥 Commits

Reviewing files that changed from the base of the PR and between f3dd5da and 2bad852.

📒 Files selected for processing (1)

packages/agents/docs/telemetry.md

packages/agents/docs/telemetry.md

Co-Authored-By: Claude <noreply@anthropic.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/agents/docs/telemetry.md`:
- Line 68: Update the telemetry docs to clarify that while per-call scalar
fields override config and metadata is shallow-merged between config and
per-call values, the reserved key "funkai.agentChain" is injected by the system
after the merge and cannot be overridden by either config or per-call metadata;
explicitly state that "funkai.agentChain" is an exception to the
preservation/override rules and will always be set by the system post-merge so
readers know it cannot be changed via metadata.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7091bc4e-2556-4699-b815-63c659f49146

📥 Commits

Reviewing files that changed from the base of the PR and between 2bad852 and e3dbe99.

📒 Files selected for processing (1)

packages/agents/docs/telemetry.md

packages/agents/docs/telemetry.md

…ge semantics Co-Authored-By: Claude <noreply@anthropic.com>

… subagent) Co-Authored-By: Claude <noreply@anthropic.com>

Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 1, 2026 03:31 View deployment

coderabbitai bot requested changes Apr 1, 2026

View reviewed changes

packages/agents/src/core/agents/types.ts Outdated Show resolved Hide resolved

coderabbitai bot approved these changes Apr 1, 2026

View reviewed changes

fix(agents): consolidate duplicate ai module imports

f3dd5da

Merge separate `from "ai"` import statements to satisfy oxlint no-duplicates rule. Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 1, 2026 14:47 View deployment

style(agents): format telemetry docs with oxfmt

2bad852

Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 1, 2026 14:50 View deployment

coderabbitai bot requested changes Apr 1, 2026

View reviewed changes

packages/agents/docs/telemetry.md Outdated Show resolved Hide resolved

style(agents): add language tag to fenced code block in telemetry docs

e3dbe99

Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 1, 2026 15:57 View deployment

coderabbitai bot requested changes Apr 1, 2026

View reviewed changes

packages/agents/docs/telemetry.md Outdated Show resolved Hide resolved

docs(agents): clarify reserved metadata key behavior in telemetry mer…

cfa90fa

…ge semantics Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 1, 2026 16:01 View deployment

coderabbitai bot approved these changes Apr 1, 2026

View reviewed changes

test(agents): add 3-level chain propagation test (flowAgent → agent →…

03e96d0

… subagent) Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 2, 2026 05:37 View deployment

fix(agents): replace ternary with if/else in chain propagation test

deed9e0

Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview April 2, 2026 16:42 View deployment

zrosenbauer merged commit e6a2df8 into main Apr 2, 2026
5 checks passed

zrosenbauer deleted the feat/agents-telemetry-otel branch April 2, 2026 20:59

coderabbitai bot mentioned this pull request Apr 2, 2026

refactor(agents): simplify mergeTelemetry implementation #76

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(agents): add OpenTelemetry telemetry support#75

feat(agents): add OpenTelemetry telemetry support#75
zrosenbauer merged 7 commits intomainfrom
feat/agents-telemetry-otel

zrosenbauer commented Apr 1, 2026

Uh oh!

changeset-bot bot commented Apr 1, 2026 •

edited

Loading

Uh oh!

vercel bot commented Apr 1, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Apr 1, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

zrosenbauer commented Apr 1, 2026

Summary

Changes

Test plan

Uh oh!

changeset-bot bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-bot bot commented Apr 1, 2026 •

edited

Loading

vercel bot commented Apr 1, 2026 •

edited

Loading

coderabbitai bot commented Apr 1, 2026 •

edited

Loading