@google/adk 2.4.0 → 2.5.0

package/dist/esm/telemetry/api/instrumentation.js

@@ -0,0 +1,655 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  context,
+  createContextKey,
+  propagation,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+import { logger } from "../../utils/logger.js";
+import {
+  captureAccumulators,
+  claimEntrypointWorkflowFrame,
+  openAgentFrame,
+  openWorkflowFrame
+} from "./internal/common/accumulators.js";
+import {
+  GcpAttr,
+  GenAiAttr,
+  USER_ID_ATTR
+} from "./internal/common/attributes.js";
+import {
+  isExperimentalFeatureEnabled,
+  resolveTelemetryConfig,
+  shouldAddContentToLogs
+} from "./internal/common/config.js";
+import {
+  getToolResponseErrorType,
+  resolveErrorType
+} from "./internal/common/error.js";
+import { isReportedFinishReason } from "./internal/common/finish_reason.js";
+import {
+  buildOutputMessage,
+  buildRequestOperationDetails,
+  withoutContent
+} from "./internal/common/genai_messages.js";
+import { resolveProviderName } from "./internal/common/provider_name.js";
+import { TokenUsage } from "./internal/common/token_usage.js";
+import { emitInferenceOperationDetails } from "./internal/logs/inference.js";
+import {
+  readMcpHttpExchangeSettings,
+  reportMcpHttpExchange
+} from "./internal/logs/mcp.js";
+import {
+  recordAgentDuration,
+  recordAgentTotals
+} from "./internal/metrics/agent.js";
+import { notifyInferenceStart } from "./internal/metrics/inference_start_hook.js";
+import {
+  recordSkillLoad,
+  recordSkillScriptExecution,
+  recordToolDuration
+} from "./internal/metrics/tool.js";
+import {
+  recordWorkflowDuration,
+  recordWorkflowTotals
+} from "./internal/metrics/workflow.js";
+import { buildAgentInvocationAttributes } from "./internal/trace/agent.js";
+import {
+  buildCompactionResultAttributes,
+  startCompactionSpan
+} from "./internal/trace/compaction.js";
+import {
+  buildResponseAttributes,
+  setInferenceOperationDetails,
+  setInferenceResponseAttributes,
+  startInferenceSpan
+} from "./internal/trace/inference.js";
+import { setSendDataAttributes } from "./internal/trace/live.js";
+import {
+  hasOwnInvocationSpan,
+  setAssociatedEventIds,
+  startNodeSpan
+} from "./internal/trace/node.js";
+import {
+  addMissingHeaders,
+  INCOMING_HEADERS_GETTER
+} from "./internal/trace/propagation.js";
+import {
+  buildMergedToolCallsAttributes,
+  buildToolCallAttributes,
+  setSkillSpanAttributes
+} from "./internal/trace/tool.js";
+import {
+  bindOtelContextToAsyncGenerator,
+  getTracer,
+  setSpanError
+} from "./internal/trace/tracer.js";
+import { startWorkflowSpan } from "./internal/trace/workflow.js";
+function nowMillis() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+__name(nowMillis, "nowMillis");
+function elapsedSeconds(startMillis) {
+  return Math.max(0, (nowMillis() - startMillis) / 1e3);
+}
+__name(elapsedSeconds, "elapsedSeconds");
+function streamInScope(start, createGenerator) {
+  return (async function* () {
+    const scope = start();
+    try {
+      yield* bindOtelContextToAsyncGenerator(
+        scope.context,
+        context.with(scope.context, createGenerator)
+      );
+    } catch (error) {
+      scope.end(error);
+      throw error;
+    } finally {
+      scope.end();
+    }
+  })();
+}
+__name(streamInScope, "streamInScope");
+function startWorkflowScope({
+  workflowName,
+  sessionId,
+  entrypoint,
+  telemetry
+}) {
+  const startMillis = nowMillis();
+  const parentContext = context.active();
+  const { frame, context: frameContext } = openWorkflowFrame({
+    workflowName,
+    config: resolveTelemetryConfig(telemetry),
+    entrypoint,
+    parentContext
+  });
+  const nested = frame.parent !== void 0;
+  const span = startWorkflowSpan({
+    workflowName,
+    sessionId,
+    nested,
+    parentContext
+  });
+  const ctx = trace.setSpan(frameContext, span);
+  let ended = false;
+  return {
+    context: ctx,
+    run: /* @__PURE__ */ __name((fn) => context.with(ctx, fn), "run"),
+    end(error) {
+      if (ended) {
+        return;
+      }
+      ended = true;
+      let errorType;
+      if (error !== void 0) {
+        errorType = resolveErrorType(error);
+        setSpanError(span, error);
+      }
+      span.end();
+      recordWorkflowDuration({
+        workflowName,
+        durationSeconds: elapsedSeconds(startMillis),
+        nested,
+        errorType
+      });
+      recordWorkflowTotals({
+        rootAgentName: frame.rootAgentName,
+        workflowName,
+        nested,
+        totals: frame.totals,
+        config: frame.config
+      });
+    }
+  };
+}
+__name(startWorkflowScope, "startWorkflowScope");
+function recordInvocation({ entrypoint, sessionId, runConfig }, createGenerator) {
+  return streamInScope(
+    () => startWorkflowScope({
+      workflowName: entrypoint.name,
+      sessionId,
+      entrypoint,
+      telemetry: runConfig == null ? void 0 : runConfig.telemetry
+    }),
+    createGenerator
+  );
+}
+__name(recordInvocation, "recordInvocation");
+function recordAgentInvocation({ agent, invocationContext }, createGenerator) {
+  return streamInScope(() => {
+    var _a, _b;
+    const startMillis = nowMillis();
+    const config = resolveTelemetryConfig(
+      (_a = invocationContext.runConfig) == null ? void 0 : _a.telemetry
+    );
+    const parentContext = context.active();
+    const { frame, context: frameContext } = openAgentFrame(parentContext);
+    const span = getTracer().startSpan(
+      `invoke_agent ${agent.name}`,
+      {
+        attributes: buildAgentInvocationAttributes({
+          agent,
+          // Read defensively: telemetry must not fail a run whose context was
+          // assembled without a session.
+          sessionId: (_b = invocationContext.session) == null ? void 0 : _b.id
+        })
+      },
+      parentContext
+    );
+    const ctx = trace.setSpan(frameContext, span);
+    let ended = false;
+    return {
+      context: ctx,
+      end(error) {
+        if (ended) {
+          return;
+        }
+        ended = true;
+        let errorType;
+        if (error !== void 0) {
+          errorType = resolveErrorType(error);
+          setSpanError(span, error);
+        }
+        span.end();
+        recordAgentDuration({
+          agentName: agent.name,
+          durationSeconds: elapsedSeconds(startMillis),
+          errorType
+        });
+        recordAgentTotals({
+          agentName: agent.name,
+          totals: frame.totals,
+          config
+        });
+      }
+    };
+  }, createGenerator);
+}
+__name(recordAgentInvocation, "recordAgentInvocation");
+function startInference({
+  invocationContext,
+  llmRequest,
+  modelResponseEvent
+}) {
+  var _a, _b, _c;
+  const config = resolveTelemetryConfig((_a = invocationContext.runConfig) == null ? void 0 : _a.telemetry);
+  const accumulators = captureAccumulators(context.active());
+  const agentName = (_b = invocationContext.agent) == null ? void 0 : _b.name;
+  const commonAttributes = {
+    ...agentName ? { [GenAiAttr.AGENT_NAME]: agentName } : {},
+    [GenAiAttr.CONVERSATION_ID]: (_c = invocationContext.session) == null ? void 0 : _c.id,
+    [GcpAttr.EVENT_ID]: modelResponseEvent.id,
+    [GcpAttr.INVOCATION_ID]: invocationContext.invocationId,
+    [GenAiAttr.PROVIDER_NAME]: resolveProviderName(llmRequest.model)
+  };
+  const span = startInferenceSpan({ llmRequest, commonAttributes });
+  notifyInferenceStart();
+  const requestDetails = buildRequestOperationDetails(llmRequest);
+  const outputMessages = [];
+  let responseAttributes = {};
+  let newestUsage;
+  let spanEnded = false;
+  let finished = false;
+  const endSpan = /* @__PURE__ */ __name((failure) => {
+    var _a2;
+    if (spanEnded) {
+      return;
+    }
+    spanEnded = true;
+    if (failure) {
+      setSpanError(span, failure.error);
+    }
+    const details = outputMessages.length > 0 ? { ...requestDetails, [GenAiAttr.OUTPUT_MESSAGES]: outputMessages } : requestDetails;
+    const captureContent = shouldAddContentToLogs(config);
+    emitInferenceOperationDetails(span, {
+      ...commonAttributes,
+      ...captureContent ? { [USER_ID_ATTR]: (_a2 = invocationContext.session) == null ? void 0 : _a2.userId } : {},
+      ...responseAttributes,
+      ...captureContent ? details : withoutContent(details)
+    });
+    setInferenceOperationDetails(span, details, config);
+    span.end();
+  }, "endSpan");
+  return {
+    context: trace.setSpan(context.active(), span),
+    record(llmResponse) {
+      var _a2;
+      newestUsage = (_a2 = llmResponse.usageMetadata) != null ? _a2 : newestUsage;
+      if (spanEnded) {
+        return;
+      }
+      setInferenceResponseAttributes(span, llmResponse, config);
+      responseAttributes = {
+        ...responseAttributes,
+        ...buildResponseAttributes(llmResponse)
+      };
+      const outputMessage = buildOutputMessage(llmResponse);
+      if (outputMessage) {
+        outputMessages.push(outputMessage);
+      }
+      if (isReportedFinishReason(llmResponse.finishReason)) {
+        endSpan();
+      }
+    },
+    finish(failure) {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      endSpan(failure);
+      accumulators.addInferenceCall();
+      if (newestUsage !== void 0) {
+        const usage = new TokenUsage(newestUsage);
+        if (usage.input !== void 0 || usage.output !== void 0) {
+          accumulators.addTokens(usage);
+        }
+      }
+    }
+  };
+}
+__name(startInference, "startInference");
+function recordInference(params, createStream) {
+  return (async function* () {
+    const inference = startInference(params);
+    try {
+      for await (const llmResponse of bindOtelContextToAsyncGenerator(
+        inference.context,
+        context.with(inference.context, createStream)
+      )) {
+        inference.record(llmResponse);
+        yield llmResponse;
+      }
+    } catch (error) {
+      inference.finish({ error });
+      throw error;
+    } finally {
+      inference.finish();
+    }
+  })();
+}
+__name(recordInference, "recordInference");
+async function recordSendData(params, fn) {
+  return getTracer().startActiveSpan("send_data", async (span) => {
+    try {
+      const result = await fn();
+      setSendDataAttributes(span, params);
+      return result;
+    } finally {
+      span.end();
+    }
+  });
+}
+__name(recordSendData, "recordSendData");
+const TOOL_SCOPE_KEY = createContextKey("adk_tool_scope");
+function isToolScopeState(value) {
+  return typeof value === "object" && value !== null && "skill" in value;
+}
+__name(isToolScopeState, "isToolScopeState");
+async function recordToolExecution({ tool, args, invocationContext }, fn) {
+  var _a;
+  const startMillis = nowMillis();
+  const config = resolveTelemetryConfig((_a = invocationContext.runConfig) == null ? void 0 : _a.telemetry);
+  const accumulators = captureAccumulators(context.active());
+  const toolScope = { skill: void 0 };
+  return getTracer().startActiveSpan(
+    `execute_tool ${tool.name}`,
+    {},
+    context.active().setValue(TOOL_SCOPE_KEY, toolScope),
+    async (span) => {
+      var _a2;
+      let outcome = { kind: "response" };
+      try {
+        return await fn({
+          recordSuccess({ functionResponseEvent, rawResult }) {
+            outcome = {
+              kind: "response",
+              functionResponseEvent,
+              errorType: getToolResponseErrorType(rawResult)
+            };
+          }
+        });
+      } catch (error) {
+        outcome = { kind: "error", errorType: resolveErrorType(error) };
+        setSpanError(span, error);
+        throw error;
+      } finally {
+        const agentName = (_a2 = invocationContext.agent) == null ? void 0 : _a2.name;
+        span.setAttributes(
+          buildToolCallAttributes({
+            tool,
+            args,
+            agentName,
+            outcome,
+            config
+          })
+        );
+        if (outcome.kind === "response" && outcome.errorType !== void 0) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: outcome.errorType
+          });
+        }
+        const skillReport = toolScope.skill;
+        if (skillReport) {
+          setSkillSpanAttributes(span, tool.name, skillReport);
+          if (skillReport.isSkillLoad) {
+            accumulators.addSkillLoad();
+            if (agentName !== void 0) {
+              recordSkillLoad({
+                agentName,
+                skill: skillReport.skill,
+                errorType: outcome.errorType,
+                config
+              });
+            }
+          } else if (skillReport.isSkillScript && skillReport.resourceName !== void 0 && agentName !== void 0) {
+            recordSkillScriptExecution({
+              agentName,
+              skill: skillReport.skill,
+              scriptPath: skillReport.resourceName,
+              config
+            });
+          }
+        }
+        span.end();
+        accumulators.addToolCall();
+        recordToolDuration({
+          agentName: agentName != null ? agentName : "",
+          toolName: tool.name,
+          toolType: tool.constructor.name,
+          durationSeconds: elapsedSeconds(startMillis),
+          errorType: outcome.errorType
+        });
+      }
+    }
+  );
+}
+__name(recordToolExecution, "recordToolExecution");
+const NO_OP_SKILL_ACTIVITY_SCOPE = Object.freeze({
+  recordSkill() {
+  }
+});
+function toSkillReport(activity) {
+  switch (activity.kind) {
+    case "load":
+      return { skillName: activity.skillName, isSkillLoad: true };
+    case "resource":
+      return {
+        skillName: activity.skillName,
+        resourceName: activity.resourcePath,
+        isSkillLoad: false
+      };
+    case "script":
+      return {
+        skillName: activity.skillName,
+        resourceName: activity.scriptPath,
+        isSkillLoad: false,
+        isSkillScript: true
+      };
+    default: {
+      const exhaustive = activity;
+      throw new Error(`Unknown skill activity: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+__name(toSkillReport, "toSkillReport");
+function recordSkillActivity(activity) {
+  const toolScope = context.active().getValue(TOOL_SCOPE_KEY);
+  if (!isToolScopeState(toolScope)) {
+    return NO_OP_SKILL_ACTIVITY_SCOPE;
+  }
+  const report = toSkillReport(activity);
+  toolScope.skill = report;
+  return {
+    recordSkill(skill) {
+      toolScope.skill = { ...report, skill };
+    }
+  };
+}
+__name(recordSkillActivity, "recordSkillActivity");
+function recordMergedToolCalls({
+  responseEventId
+}) {
+  getTracer().startSpan("execute_tool (merged)", {
+    attributes: buildMergedToolCallsAttributes(responseEventId)
+  }).end();
+}
+__name(recordMergedToolCalls, "recordMergedToolCalls");
+const PASS_THROUGH_SCOPE = Object.freeze({
+  run: /* @__PURE__ */ __name((fn) => fn(), "run"),
+  end() {
+  }
+});
+function startSyncScope(span, ctx, onSuccess) {
+  let ended = false;
+  return {
+    run: /* @__PURE__ */ __name((fn) => context.with(ctx, fn), "run"),
+    end(error) {
+      if (ended) {
+        return;
+      }
+      ended = true;
+      if (error === void 0) {
+        onSuccess == null ? void 0 : onSuccess();
+      } else {
+        setSpanError(span, error);
+      }
+      span.end();
+    }
+  };
+}
+__name(startSyncScope, "startSyncScope");
+function recordWorkflowInvocation({
+  workflow,
+  sessionId
+}) {
+  const entrypointContext = claimEntrypointWorkflowFrame(workflow);
+  if (entrypointContext) {
+    return { run: /* @__PURE__ */ __name((fn) => context.with(entrypointContext, fn), "run"), end() {
+    } };
+  }
+  return startWorkflowScope({
+    workflowName: workflow.name,
+    sessionId
+  });
+}
+__name(recordWorkflowInvocation, "recordWorkflowInvocation");
+const PASS_THROUGH_NODE_SCOPE = Object.freeze({
+  ...PASS_THROUGH_SCOPE,
+  recordEvent() {
+  }
+});
+function recordNodeInvocation({
+  node,
+  nodeName,
+  sessionId
+}) {
+  if (hasOwnInvocationSpan(node)) {
+    return PASS_THROUGH_NODE_SCOPE;
+  }
+  const span = startNodeSpan({ nodeName, sessionId });
+  const eventIds = [];
+  return {
+    ...startSyncScope(
+      span,
+      trace.setSpan(context.active(), span),
+      () => setAssociatedEventIds(span, eventIds)
+    ),
+    recordEvent(event) {
+      eventIds.push(event.id);
+    }
+  };
+}
+__name(recordNodeInvocation, "recordNodeInvocation");
+async function recordCompaction({ invocationContext, trigger }, fn) {
+  const { session } = invocationContext;
+  const eventsBefore = [...session.events];
+  const accumulators = captureAccumulators(context.active());
+  const span = startCompactionSpan({ sessionId: session.id, trigger });
+  return context.with(trace.setSpan(context.active(), span), async () => {
+    try {
+      const result = await fn();
+      const attributes = buildCompactionResultAttributes(
+        eventsBefore,
+        session.events
+      );
+      span.setAttributes(attributes);
+      if (GenAiAttr.COMPACTION_RESULT_EVENT_ID in attributes) {
+        accumulators.addCompaction();
+      }
+      return result;
+    } catch (error) {
+      setSpanError(span, error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+__name(recordCompaction, "recordCompaction");
+function instrumentMcpFetch(fetch) {
+  if (!isExperimentalFeatureEnabled(resolveTelemetryConfig(), "mcp")) {
+    return fetch;
+  }
+  return async (url, init) => {
+    const settings = readMcpHttpExchangeSettings();
+    const requestContext = context.active();
+    const response = await (fetch != null ? fetch : globalThis.fetch)(url, init);
+    void reportMcpHttpExchange({
+      url,
+      init,
+      response,
+      settings,
+      context: requestContext
+    }).catch((error) => {
+      logger.warn(
+        `Failed to record an MCP HTTP exchange: ${resolveErrorType(error)}`
+      );
+    });
+    return response;
+  };
+}
+__name(instrumentMcpFetch, "instrumentMcpFetch");
+function propagateTraceContext(fetchImpl) {
+  return (input, init) => {
+    const send = fetchImpl != null ? fetchImpl : globalThis.fetch;
+    const injected = {};
+    try {
+      propagation.inject(context.active(), injected);
+    } catch (error) {
+      logger.warn(
+        `Failed to inject trace context into a request: ${resolveErrorType(error)}`
+      );
+      return send(input, init);
+    }
+    if (Object.keys(injected).length === 0) {
+      return send(input, init);
+    }
+    return send(input, {
+      ...init,
+      headers: addMissingHeaders(input, init, injected)
+    });
+  };
+}
+__name(propagateTraceContext, "propagateTraceContext");
+function runWithRemoteTraceContext(headers, fn) {
+  const active = context.active();
+  if (trace.getSpan(active)) {
+    return fn();
+  }
+  let remote = active;
+  try {
+    remote = propagation.extract(active, headers, INCOMING_HEADERS_GETTER);
+  } catch (error) {
+    logger.warn(
+      `Failed to extract trace context from a request: ${resolveErrorType(error)}`
+    );
+  }
+  return context.with(remote, fn);
+}
+__name(runWithRemoteTraceContext, "runWithRemoteTraceContext");
+export {
+  instrumentMcpFetch,
+  propagateTraceContext,
+  recordAgentInvocation,
+  recordCompaction,
+  recordInference,
+  recordInvocation,
+  recordMergedToolCalls,
+  recordNodeInvocation,
+  recordSendData,
+  recordSkillActivity,
+  recordToolExecution,
+  recordWorkflowInvocation,
+  runWithRemoteTraceContext
+};