@launchdarkly/server-sdk-ai - v2.0.21
    Preparing search index...

    Interface LDGraphTracker

    The LDGraphTracker records metrics for a single AI run of an agent graph.

    All events a graph tracker emits share a runId (a UUIDv4) so LaunchDarkly can correlate them in metrics views. Call createTracker on the agent graph to start a new run. A resumption token preserves the runId, so events emitted by a tracker reconstructed in another process correlate with the original run.

    Graph-level methods enforce at-most-once semantics: calling the same method twice on a tracker instance drops the second call and emits a warning. Edge-level methods (trackRedirect, trackHandoffSuccess, trackHandoffFailure) are multi-fire and are not subject to this constraint.

    const tracker = graphDefinition.createTracker();
    try {
      // ... execute graph ...
      tracker.trackInvocationSuccess();
      tracker.trackDuration(durationMs);
    } catch {
      tracker.trackInvocationFailure();
    }
    interface LDGraphTracker {
        resumptionToken: string;
        getSummary(): Partial<LDAIGraphMetricSummary>;
        getTrackData(): {
            graphKey: string;
            runId: string;
            variationKey?: string;
            version: number;
        };
        trackDuration(durationMs: number): void;
        trackHandoffFailure(sourceKey: string, targetKey: string): void;
        trackHandoffSuccess(sourceKey: string, targetKey: string): void;
        trackInvocationFailure(): void;
        trackInvocationSuccess(): void;
        trackPath(path: string[]): void;
        trackRedirect(sourceKey: string, redirectedTarget: string): void;
        trackTotalTokens(tokens: LDTokenUsage): void;
    }

    Implemented by

    Index
    resumptionToken
    getSummary getTrackData trackDuration trackHandoffFailure trackHandoffSuccess trackInvocationFailure trackInvocationSuccess trackPath trackRedirect trackTotalTokens
    resumptionToken: string

    A URL-safe Base64-encoded (RFC 4648, no padding) token encoding the tracker's identity. Pass this token to LDGraphTrackerImpl.fromResumptionToken to reconstruct the tracker across process boundaries, preserving the original runId.

    Security note: The token contains the flag variation key and version. If passed to an untrusted client (e.g., a browser) this could expose feature-flag targeting details. Keep the token server-side and use an opaque reference in client-facing APIs.

    • Returns a snapshot of all graph-level metrics tracked so far. Fields populate incrementally as track* methods are called, so the result is a Partial<LDAIGraphMetricSummary>. Once the graph run has completed via ManagedAgentGraph.run(), prefer ManagedGraphResult.metrics which is fully populated.

      Returns Partial<LDAIGraphMetricSummary>

    • Returns tracking metadata to be included in every LDClient.track call.

      Returns { graphKey: string; runId: string; variationKey?: string; version: number }

    • Tracks the total duration of the graph run in milliseconds. Emits event $ld:ai:graph:duration:total with the duration as the metric value. At-most-once: subsequent calls are dropped with a warning.

      Parameters

      • durationMs: number

        Duration in milliseconds.

      Returns void

    • Tracks a failed handoff between two nodes. Emits event $ld:ai:graph:handoff_failure with metric value 1.

      Parameters

      • sourceKey: string

        Config key of the source node.

      • targetKey: string

        Config key of the target node.

      Returns void

    • Tracks a successful handoff between two nodes. Emits event $ld:ai:graph:handoff_success with metric value 1.

      Parameters

      • sourceKey: string

        Config key of the source node.

      • targetKey: string

        Config key of the target node.

      Returns void

    • Tracks an unsuccessful graph run. Emits event $ld:ai:graph:invocation_failure with metric value 1. At-most-once: subsequent calls are dropped with a warning.

      Returns void

    • Tracks a successful graph run. Emits event $ld:ai:graph:invocation_success with metric value 1. At-most-once: subsequent calls are dropped with a warning.

      Returns void

    • Tracks the path taken through the graph during this run. Emits event $ld:ai:graph:path with metric value 1. The data payload includes the path array in addition to standard track data. At-most-once: subsequent calls are dropped with a warning.

      Parameters

      • path: string[]

        An ordered array of agent config keys representing the path taken.

      Returns void

    • Tracks when a node redirects to a different target than originally specified. Emits event $ld:ai:graph:redirect with metric value 1.

      Parameters

      • sourceKey: string

        Config key of the source node.

      • redirectedTarget: string

        Config key of the actual target node.

      Returns void

    • Tracks aggregate token usage across the entire graph run. Emits event $ld:ai:graph:total_tokens with the total token count as the metric value. At-most-once: subsequent calls are dropped with a warning.

      Parameters

      Returns void

    Settings
    Member Visibility

    On This Page
    Properties
    Methods