fix(telemetry): describe option objects in the session report - #2431
Merged
Conversation
🦋 Changeset detectedLatest commit: bc729ab The changes in this PR will be included in the next version bump. This PR includes changesets to release 38 packages
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 |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
davidzhao
approved these changes
Sep 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ports livekit/agents#7127.
Summary
telemetry.DescribesOptionsso option objects explicitly control safe telemetry descriptionsTurnDetectorconfiguration without credentials or endpointsinstructionsrecursively and retain PII aliasesSource diff coverage
livekit-agents/livekit/agents/inference/eot/detector.py: ported toagents/src/inference/eot/detector.ts.describe_options()becomesdescribeOptions()and fields use target camelCase conventions; the target always supports local fallback, solocalFallbackis reported astrue.livekit-agents/livekit/agents/telemetry/__init__.py: ported toagents/src/telemetry/index.ts. The Python protocol export becomes the public structural TypeScript interfaceDescribesOptions.livekit-agents/livekit/agents/telemetry/traces.py: ported toagents/src/telemetry/traces.ts. Python mappings, sequences, sets, andmodule.Classnames are adapted to JS records/maps, iterables, sets, and stable constructor names. Recursive aliases, prompt omission, deterministic descriptions, failure fallback, and JSON safety are preserved.tests/test_session_options_report.py: adapted intoagents/src/telemetry/traces.test.ts, following the target co-located Vitest convention. Every source test behavior is covered: default detector, threshold overrides, credential safety, mode strings, opt-in and opaque objects, sparse/failing descriptions, custom iterables and sets, prompt omission, nested aliases, and JSON safety.Target infrastructure adaptation:
agents/src/voice/agent_session.tsstores the eager effective default detector in reportable session options, matching the Python options object used by the source serializer.agents/etc/agents.api.mdand the patch changeset are updated for the new public API.No source files were omitted and there are no infrastructure gaps.
Validation
pnpm test agents(151 files, 2,486 passed, 5 skipped)pnpm build:agentspnpm --filter @livekit/agents lintpnpm exec prettier --check "agents/src/**/*.ts"pnpm --filter @livekit/agents api:checkPorted from livekit/agents#7127
Original PR description
What
session.optionsin the session report carried the turn detector as its default repr:The OTel exporter stringifies any non-primitive log attribute, so anything left as an object in the options dict ends up like this.
How
_serialize_session_optionsnow serializes explicitly: primitives pass through, mappings recurse, any non-stringSequenceorSetis serialized elementwise (tts_text_transformsaccepts anySequence), and any other object is reported by class,module.Class. An object that wants its configuration shown implements thetelemetry.DescribesOptionsprotocol, adescribe_options()method returning the options worth reporting; it is then rendered asmodule.Class(k=v, ...). The object decides what is safe to show, so nothing is guessed from public attributes and credentials and endpoints stay out by construction (test included; a failingdescribe_options()falls back to the class name).instructionskeys (the keyterm-detection prompt override) are dropped at any depth rather than emitted under an unmarked key.TurnDetectorimplementsdescribe_options(): model, provider, sample rate, local fallback, and the threshold overrides only when the user set any. Mode strings ("vad","manual", ...) pass through unchanged. Third-party detectors and models opt in the same way.Result:
with
threshold_overrides/backchannel_threshold_overridesappended only when the user set them.Tests
tests/test_session_options_report.py(unit): default detector description, threshold overrides, no credential leakage, mode strings, plugin-like objects, customSequenceandSetvalues, omitted prompt text, nested containers and thekeytermsPII alias, and a JSON-safety invariant on the whole serialized dict.Bottom layer of the tracing coverage stack.
🤖 Generated with Claude Code