docs: Clarify runId purpose and per-method tracker semantics#1378
Merged
Conversation
Reword the at-most-once warning messages emitted by LDAIConfigTracker and LDGraphTracker so each warning names the method being skipped, the thing that was already recorded, and the remedy (call createTracker for a new run). Aligns with the wording recently landed for the Go SDK. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Expand class- and method-level TSDoc on LDAIConfigTracker, LDGraphTracker,
LDAIConfig.createTracker, AgentGraphDefinition.createTracker, and the AI
client config-fetch methods so that:
- The role of the runId (UUIDv4 shared by all events from one tracker so
LaunchDarkly can correlate them in metrics views) is stated up front.
- Each per-method docstring states whether the metric is at-most-once or
multi-call, and what happens when the at-most-once guarantee is hit.
- completionConfig / agentConfig / judgeConfig examples reflect the actual
return shape (the returned object IS the config, with a createTracker()
factory) instead of the stale `{ config, messages, tracker }` shape.
- Narrative text refers to "AI run" or "graph run" rather than
"execution" / "invocation" where those mean a single tracker's lifetime.
Public API names (methods, event keys, type names, parameter names) are
unchanged.
Aligns with the wording recently landed for the Go SDK.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
@launchdarkly/js-sdk-common size report |
Contributor
|
@launchdarkly/js-client-sdk size report |
Contributor
|
@launchdarkly/browser size report |
Contributor
|
@launchdarkly/js-client-sdk-common size report |
Replace "original run's runId" with "original tracker's runId" on LDAIClient.createTracker so the doc no longer juxtaposes "run" and "runId". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
knfreemLD
approved these changes
May 13, 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
2 participants
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.
Summary
Follow-up to the recently-merged billing-spec alignment PR for js-core's
server-aipackage. Brings tracker docs and at-most-once warning strings in line with what just landed for the Go SDK in launchdarkly/go-server-sdk#363.refactor:commit: Reword the at-most-once warning messages onLDAIConfigTrackerandLDGraphTrackerso each one names the method being skipped, what was already recorded, and the remedy (callcreateTrackeron the AI Config / agent graph for a new run).docs:commit:LDAIConfigTrackerandLDGraphTrackerto explain that therunIdis what LaunchDarkly uses to correlate a tracker's events in metrics views, and that the resumption token preserves therunIdacross process boundaries.LDAIConfig.createTrackerandAgentGraphDefinition.createTrackerTSDoc with the samerunIdframing.track*method, state at-most-once vs. multi-call semantics and what happens when the limit is hit.trackSuccess/trackErrorshare state; the docstring on each says so. Wrapper methods (trackDurationOf,trackMetricsOf,trackStreamMetricsOf,trackBedrockConverseMetrics) note that calling the wrapper twice runs the inner function again but emits no additional metric events.completionConfig/agentConfig/judgeConfig/agentConfigsTSDoc and examples that still described a returned{ config, messages, tracker }shape. The actual return is the config object with acreateTracker()factory; examples now reflect this.executionContext) are unchanged.No behavior changes, no version / changelog edits.
Test plan
LDAIConfigTrackerImplandLDGraphTrackerImplunit tests still pass (the two warning-text assertions were updated to match the new wording).Note
Low Risk
Low risk: changes are limited to TSDoc/example updates and rewording warning log messages; no tracking behavior or event payloads change, but any consumers depending on exact warning text may be affected.
Overview
Clarifies tracker semantics across
LDAIConfigTracker/LDGraphTrackerand related APIs by explicitly framing a tracker as one AI/graph run whose events share arunId, and documenting at-most-once vs multi-call behavior pertrack*method (including wrapper helpers).Standardizes at-most-once warning messages in
LDAIConfigTrackerImplandLDGraphTrackerImplto name the skipped method, what was already recorded, and the remedy (callcreateTracker()for a new run), and updates unit tests accordingly. Also refreshesLDAIClientdoc examples to reflect thecreateTracker()factory on returned configs rather than a returnedtrackerfield.Reviewed by Cursor Bugbot for commit 1407150. Bugbot is set up for automated code reviews on this repo. Configure here.