@google/adk 2.3.0 → 2.5.0

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

@@ -0,0 +1,632 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var instrumentation_exports = {};
+__export(instrumentation_exports, {
+  instrumentMcpFetch: () => instrumentMcpFetch,
+  propagateTraceContext: () => propagateTraceContext,
+  recordAgentInvocation: () => recordAgentInvocation,
+  recordCompaction: () => recordCompaction,
+  recordInference: () => recordInference,
+  recordInvocation: () => recordInvocation,
+  recordMergedToolCalls: () => recordMergedToolCalls,
+  recordNodeInvocation: () => recordNodeInvocation,
+  recordSendData: () => recordSendData,
+  recordSkillActivity: () => recordSkillActivity,
+  recordToolExecution: () => recordToolExecution,
+  recordWorkflowInvocation: () => recordWorkflowInvocation,
+  runWithRemoteTraceContext: () => runWithRemoteTraceContext
+});
+module.exports = __toCommonJS(instrumentation_exports);
+var import_api = require("@opentelemetry/api");
+var import_logger = require("../../utils/logger.js");
+var import_accumulators = require("./internal/common/accumulators.js");
+var import_attributes = require("./internal/common/attributes.js");
+var import_config = require("./internal/common/config.js");
+var import_error = require("./internal/common/error.js");
+var import_finish_reason = require("./internal/common/finish_reason.js");
+var import_genai_messages = require("./internal/common/genai_messages.js");
+var import_provider_name = require("./internal/common/provider_name.js");
+var import_token_usage = require("./internal/common/token_usage.js");
+var import_inference = require("./internal/logs/inference.js");
+var import_mcp = require("./internal/logs/mcp.js");
+var import_agent = require("./internal/metrics/agent.js");
+var import_inference_start_hook = require("./internal/metrics/inference_start_hook.js");
+var import_tool = require("./internal/metrics/tool.js");
+var import_workflow = require("./internal/metrics/workflow.js");
+var import_agent2 = require("./internal/trace/agent.js");
+var import_compaction = require("./internal/trace/compaction.js");
+var import_inference2 = require("./internal/trace/inference.js");
+var import_live = require("./internal/trace/live.js");
+var import_node = require("./internal/trace/node.js");
+var import_propagation = require("./internal/trace/propagation.js");
+var import_tool2 = require("./internal/trace/tool.js");
+var import_tracer = require("./internal/trace/tracer.js");
+var import_workflow2 = require("./internal/trace/workflow.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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* (0, import_tracer.bindOtelContextToAsyncGenerator)(
+        scope.context,
+        import_api.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 = import_api.context.active();
+  const { frame, context: frameContext } = (0, import_accumulators.openWorkflowFrame)({
+    workflowName,
+    config: (0, import_config.resolveTelemetryConfig)(telemetry),
+    entrypoint,
+    parentContext
+  });
+  const nested = frame.parent !== void 0;
+  const span = (0, import_workflow2.startWorkflowSpan)({
+    workflowName,
+    sessionId,
+    nested,
+    parentContext
+  });
+  const ctx = import_api.trace.setSpan(frameContext, span);
+  let ended = false;
+  return {
+    context: ctx,
+    run: /* @__PURE__ */ __name((fn) => import_api.context.with(ctx, fn), "run"),
+    end(error) {
+      if (ended) {
+        return;
+      }
+      ended = true;
+      let errorType;
+      if (error !== void 0) {
+        errorType = (0, import_error.resolveErrorType)(error);
+        (0, import_tracer.setSpanError)(span, error);
+      }
+      span.end();
+      (0, import_workflow.recordWorkflowDuration)({
+        workflowName,
+        durationSeconds: elapsedSeconds(startMillis),
+        nested,
+        errorType
+      });
+      (0, import_workflow.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 = (0, import_config.resolveTelemetryConfig)(
+      (_a = invocationContext.runConfig) == null ? void 0 : _a.telemetry
+    );
+    const parentContext = import_api.context.active();
+    const { frame, context: frameContext } = (0, import_accumulators.openAgentFrame)(parentContext);
+    const span = (0, import_tracer.getTracer)().startSpan(
+      `invoke_agent ${agent.name}`,
+      {
+        attributes: (0, import_agent2.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 = import_api.trace.setSpan(frameContext, span);
+    let ended = false;
+    return {
+      context: ctx,
+      end(error) {
+        if (ended) {
+          return;
+        }
+        ended = true;
+        let errorType;
+        if (error !== void 0) {
+          errorType = (0, import_error.resolveErrorType)(error);
+          (0, import_tracer.setSpanError)(span, error);
+        }
+        span.end();
+        (0, import_agent.recordAgentDuration)({
+          agentName: agent.name,
+          durationSeconds: elapsedSeconds(startMillis),
+          errorType
+        });
+        (0, import_agent.recordAgentTotals)({
+          agentName: agent.name,
+          totals: frame.totals,
+          config
+        });
+      }
+    };
+  }, createGenerator);
+}
+__name(recordAgentInvocation, "recordAgentInvocation");
+function startInference({
+  invocationContext,
+  llmRequest,
+  modelResponseEvent
+}) {
+  var _a, _b, _c;
+  const config = (0, import_config.resolveTelemetryConfig)((_a = invocationContext.runConfig) == null ? void 0 : _a.telemetry);
+  const accumulators = (0, import_accumulators.captureAccumulators)(import_api.context.active());
+  const agentName = (_b = invocationContext.agent) == null ? void 0 : _b.name;
+  const commonAttributes = {
+    ...agentName ? { [import_attributes.GenAiAttr.AGENT_NAME]: agentName } : {},
+    [import_attributes.GenAiAttr.CONVERSATION_ID]: (_c = invocationContext.session) == null ? void 0 : _c.id,
+    [import_attributes.GcpAttr.EVENT_ID]: modelResponseEvent.id,
+    [import_attributes.GcpAttr.INVOCATION_ID]: invocationContext.invocationId,
+    [import_attributes.GenAiAttr.PROVIDER_NAME]: (0, import_provider_name.resolveProviderName)(llmRequest.model)
+  };
+  const span = (0, import_inference2.startInferenceSpan)({ llmRequest, commonAttributes });
+  (0, import_inference_start_hook.notifyInferenceStart)();
+  const requestDetails = (0, import_genai_messages.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) {
+      (0, import_tracer.setSpanError)(span, failure.error);
+    }
+    const details = outputMessages.length > 0 ? { ...requestDetails, [import_attributes.GenAiAttr.OUTPUT_MESSAGES]: outputMessages } : requestDetails;
+    const captureContent = (0, import_config.shouldAddContentToLogs)(config);
+    (0, import_inference.emitInferenceOperationDetails)(span, {
+      ...commonAttributes,
+      ...captureContent ? { [import_attributes.USER_ID_ATTR]: (_a2 = invocationContext.session) == null ? void 0 : _a2.userId } : {},
+      ...responseAttributes,
+      ...captureContent ? details : (0, import_genai_messages.withoutContent)(details)
+    });
+    (0, import_inference2.setInferenceOperationDetails)(span, details, config);
+    span.end();
+  }, "endSpan");
+  return {
+    context: import_api.trace.setSpan(import_api.context.active(), span),
+    record(llmResponse) {
+      var _a2;
+      newestUsage = (_a2 = llmResponse.usageMetadata) != null ? _a2 : newestUsage;
+      if (spanEnded) {
+        return;
+      }
+      (0, import_inference2.setInferenceResponseAttributes)(span, llmResponse, config);
+      responseAttributes = {
+        ...responseAttributes,
+        ...(0, import_inference2.buildResponseAttributes)(llmResponse)
+      };
+      const outputMessage = (0, import_genai_messages.buildOutputMessage)(llmResponse);
+      if (outputMessage) {
+        outputMessages.push(outputMessage);
+      }
+      if ((0, import_finish_reason.isReportedFinishReason)(llmResponse.finishReason)) {
+        endSpan();
+      }
+    },
+    finish(failure) {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      endSpan(failure);
+      accumulators.addInferenceCall();
+      if (newestUsage !== void 0) {
+        const usage = new import_token_usage.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 (0, import_tracer.bindOtelContextToAsyncGenerator)(
+        inference.context,
+        import_api.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 (0, import_tracer.getTracer)().startActiveSpan("send_data", async (span) => {
+    try {
+      const result = await fn();
+      (0, import_live.setSendDataAttributes)(span, params);
+      return result;
+    } finally {
+      span.end();
+    }
+  });
+}
+__name(recordSendData, "recordSendData");
+const TOOL_SCOPE_KEY = (0, import_api.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 = (0, import_config.resolveTelemetryConfig)((_a = invocationContext.runConfig) == null ? void 0 : _a.telemetry);
+  const accumulators = (0, import_accumulators.captureAccumulators)(import_api.context.active());
+  const toolScope = { skill: void 0 };
+  return (0, import_tracer.getTracer)().startActiveSpan(
+    `execute_tool ${tool.name}`,
+    {},
+    import_api.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: (0, import_error.getToolResponseErrorType)(rawResult)
+            };
+          }
+        });
+      } catch (error) {
+        outcome = { kind: "error", errorType: (0, import_error.resolveErrorType)(error) };
+        (0, import_tracer.setSpanError)(span, error);
+        throw error;
+      } finally {
+        const agentName = (_a2 = invocationContext.agent) == null ? void 0 : _a2.name;
+        span.setAttributes(
+          (0, import_tool2.buildToolCallAttributes)({
+            tool,
+            args,
+            agentName,
+            outcome,
+            config
+          })
+        );
+        if (outcome.kind === "response" && outcome.errorType !== void 0) {
+          span.setStatus({
+            code: import_api.SpanStatusCode.ERROR,
+            message: outcome.errorType
+          });
+        }
+        const skillReport = toolScope.skill;
+        if (skillReport) {
+          (0, import_tool2.setSkillSpanAttributes)(span, tool.name, skillReport);
+          if (skillReport.isSkillLoad) {
+            accumulators.addSkillLoad();
+            if (agentName !== void 0) {
+              (0, import_tool.recordSkillLoad)({
+                agentName,
+                skill: skillReport.skill,
+                errorType: outcome.errorType,
+                config
+              });
+            }
+          } else if (skillReport.isSkillScript && skillReport.resourceName !== void 0 && agentName !== void 0) {
+            (0, import_tool.recordSkillScriptExecution)({
+              agentName,
+              skill: skillReport.skill,
+              scriptPath: skillReport.resourceName,
+              config
+            });
+          }
+        }
+        span.end();
+        accumulators.addToolCall();
+        (0, import_tool.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 = import_api.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
+}) {
+  (0, import_tracer.getTracer)().startSpan("execute_tool (merged)", {
+    attributes: (0, import_tool2.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) => import_api.context.with(ctx, fn), "run"),
+    end(error) {
+      if (ended) {
+        return;
+      }
+      ended = true;
+      if (error === void 0) {
+        onSuccess == null ? void 0 : onSuccess();
+      } else {
+        (0, import_tracer.setSpanError)(span, error);
+      }
+      span.end();
+    }
+  };
+}
+__name(startSyncScope, "startSyncScope");
+function recordWorkflowInvocation({
+  workflow,
+  sessionId
+}) {
+  const entrypointContext = (0, import_accumulators.claimEntrypointWorkflowFrame)(workflow);
+  if (entrypointContext) {
+    return { run: /* @__PURE__ */ __name((fn) => import_api.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 ((0, import_node.hasOwnInvocationSpan)(node)) {
+    return PASS_THROUGH_NODE_SCOPE;
+  }
+  const span = (0, import_node.startNodeSpan)({ nodeName, sessionId });
+  const eventIds = [];
+  return {
+    ...startSyncScope(
+      span,
+      import_api.trace.setSpan(import_api.context.active(), span),
+      () => (0, import_node.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 = (0, import_accumulators.captureAccumulators)(import_api.context.active());
+  const span = (0, import_compaction.startCompactionSpan)({ sessionId: session.id, trigger });
+  return import_api.context.with(import_api.trace.setSpan(import_api.context.active(), span), async () => {
+    try {
+      const result = await fn();
+      const attributes = (0, import_compaction.buildCompactionResultAttributes)(
+        eventsBefore,
+        session.events
+      );
+      span.setAttributes(attributes);
+      if (import_attributes.GenAiAttr.COMPACTION_RESULT_EVENT_ID in attributes) {
+        accumulators.addCompaction();
+      }
+      return result;
+    } catch (error) {
+      (0, import_tracer.setSpanError)(span, error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+__name(recordCompaction, "recordCompaction");
+function instrumentMcpFetch(fetch) {
+  if (!(0, import_config.isExperimentalFeatureEnabled)((0, import_config.resolveTelemetryConfig)(), "mcp")) {
+    return fetch;
+  }
+  return async (url, init) => {
+    const settings = (0, import_mcp.readMcpHttpExchangeSettings)();
+    const requestContext = import_api.context.active();
+    const response = await (fetch != null ? fetch : globalThis.fetch)(url, init);
+    void (0, import_mcp.reportMcpHttpExchange)({
+      url,
+      init,
+      response,
+      settings,
+      context: requestContext
+    }).catch((error) => {
+      import_logger.logger.warn(
+        `Failed to record an MCP HTTP exchange: ${(0, import_error.resolveErrorType)(error)}`
+      );
+    });
+    return response;
+  };
+}
+__name(instrumentMcpFetch, "instrumentMcpFetch");
+function propagateTraceContext(fetchImpl) {
+  return (input, init) => {
+    const send = fetchImpl != null ? fetchImpl : globalThis.fetch;
+    const injected = {};
+    try {
+      import_api.propagation.inject(import_api.context.active(), injected);
+    } catch (error) {
+      import_logger.logger.warn(
+        `Failed to inject trace context into a request: ${(0, import_error.resolveErrorType)(error)}`
+      );
+      return send(input, init);
+    }
+    if (Object.keys(injected).length === 0) {
+      return send(input, init);
+    }
+    return send(input, {
+      ...init,
+      headers: (0, import_propagation.addMissingHeaders)(input, init, injected)
+    });
+  };
+}
+__name(propagateTraceContext, "propagateTraceContext");
+function runWithRemoteTraceContext(headers, fn) {
+  const active = import_api.context.active();
+  if (import_api.trace.getSpan(active)) {
+    return fn();
+  }
+  let remote = active;
+  try {
+    remote = import_api.propagation.extract(active, headers, import_propagation.INCOMING_HEADERS_GETTER);
+  } catch (error) {
+    import_logger.logger.warn(
+      `Failed to extract trace context from a request: ${(0, import_error.resolveErrorType)(error)}`
+    );
+  }
+  return import_api.context.with(remote, fn);
+}
+__name(runWithRemoteTraceContext, "runWithRemoteTraceContext");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  instrumentMcpFetch,
+  propagateTraceContext,
+  recordAgentInvocation,
+  recordCompaction,
+  recordInference,
+  recordInvocation,
+  recordMergedToolCalls,
+  recordNodeInvocation,
+  recordSendData,
+  recordSkillActivity,
+  recordToolExecution,
+  recordWorkflowInvocation,
+  runWithRemoteTraceContext
+});