feat(instrumentation-google-generativeai): add OTel 1.40 GenAI semantic conventions instrumentation (#931)

Author: lenatraceloop

packages/ai-semantic-conventions/src/SemanticAttributes.ts

@@ -162,4 +162,5 @@ export const FinishReasons = {
   TOOL_CALL: "tool_call",
   CONTENT_FILTER: "content_filter",
   ERROR: "error",
+  FINISH_REASON_UNSPECIFIED: "",
 } as const;

packages/instrumentation-google-generativeai/.prettierignore

@@ -0,0 +1,2 @@
+/dist
+/coverage

packages/instrumentation-google-generativeai/README.md

@@ -0,0 +1,55 @@
+# OpenTelemetry Google Gen AI SDK instrumentation for Node.js
+
+[![NPM Published Version][npm-img]][npm-url]
+[![Apache License][license-image]][license-url]
+
+This module provides automatic instrumentation for [`Google Gen AI SDK`](https://github.com/googleapis/js-genai) (`@google/genai`) module, which may be loaded using the [`@opentelemetry/sdk-trace-node`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node) package and is included in the [`@traceloop/node-server-sdk`](https://www.npmjs.com/package/@traceloop/node-server-sdk) bundle.
+
+If total installation size is not constrained, it is recommended to use the [`@traceloop/node-server-sdk`](https://www.npmjs.com/package/@traceloop/node-server-sdk) bundle for the most seamless instrumentation experience.
+
+Compatible with OpenTelemetry JS API and SDK `1.0+`.
+
+## Installation
+
+```bash
+npm install --save @traceloop/instrumentation-google-generativeai
+```
+
+## Supported Versions
+
+- `>=1.0.0`
+
+## Usage
+
+To load a specific plugin, specify it in the registerInstrumentations's configuration:
+
+```js
+const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
+const {
+  GenAIInstrumentation,
+} = require("@traceloop/instrumentation-google-generativeai");
+const { registerInstrumentations } = require("@opentelemetry/instrumentation");
+
+const provider = new NodeTracerProvider();
+provider.register();
+
+registerInstrumentations({
+  instrumentations: [new GenAIInstrumentation()],
+});
+```
+
+## Useful links
+
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
+- For help or feedback on this project, join us on [Slack][slack-url]
+
+## License
+
+Apache 2.0 - See [LICENSE][license-url] for more information.
+
+[slack-url]: https://traceloop.com/slack
+[license-url]: https://github.com/traceloop/openllmetry-js/blob/main/LICENSE
+[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
+[npm-url]: https://www.npmjs.com/package/@traceloop/instrumentation-google-generativeai
+[npm-img]: https://badge.fury.io/js/%40traceloop%2Finstrumentation-google-generativeai.svg

packages/instrumentation-google-generativeai/eslint.config.cjs

@@ -0,0 +1,29 @@
+const js = require("@eslint/js");
+const rootConfig = require("../../eslint.config.cjs");
+
+const { FlatCompat } = require("@eslint/eslintrc");
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+module.exports = [
+  {
+    ignores: ["!**/*", "**/node_modules", "dist/**/*"],
+  },
+  ...rootConfig,
+  {
+    files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+    rules: {},
+  },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    rules: {},
+  },
+  {
+    files: ["**/*.js", "**/*.jsx"],
+    rules: {},
+  },
+];

packages/instrumentation-google-generativeai/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@traceloop/instrumentation-google-generativeai",
+  "version": "0.24.1",
+  "description": "Google Gen AI SDK Instrumentation",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "repository": "traceloop/openllmetry-js",
+  "scripts": {
+    "build": "rollup -c",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "ts-mocha -p tsconfig.test.json 'tests/**/*.test.ts' --timeout 20000"
+  },
+  "keywords": [
+    "opentelemetry",
+    "nodejs",
+    "tracing",
+    "attributes",
+    "semantic conventions",
+    "google",
+    "gemini",
+    "genai"
+  ],
+  "author": "Traceloop",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.mjs",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "doc",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.1",
+    "@opentelemetry/instrumentation": "^0.203.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@traceloop/ai-semantic-conventions": "workspace:*",
+    "@traceloop/instrumentation-utils": "workspace:*",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@google/genai": "^1.50.1",
+    "@opentelemetry/context-async-hooks": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "@types/mocha": "^10.0.10",
+    "ts-mocha": "^11.1.0"
+  },
+  "homepage": "https://github.com/traceloop/openllmetry-js/tree/main/packages/instrumentation-google-generativeai"
+}

packages/instrumentation-google-generativeai/rollup.config.js

@@ -0,0 +1,39 @@
+const dts = require("rollup-plugin-dts");
+const typescript = require("@rollup/plugin-typescript");
+const json = require("@rollup/plugin-json");
+
+const name = require("./package.json").main.replace(/\.js$/, "");
+
+const bundle = (config) => ({
+  ...config,
+  input: "src/index.ts",
+  external: (id) => !/^[./]/.test(id),
+});
+
+exports.default = [
+  bundle({
+    plugins: [
+      typescript.default({ exclude: ["test/**/*", "tests/**/*"] }),
+      json.default(),
+    ],
+    output: [
+      {
+        file: `${name}.js`,
+        format: "cjs",
+        sourcemap: true,
+      },
+      {
+        file: `${name}.mjs`,
+        format: "es",
+        sourcemap: true,
+      },
+    ],
+  }),
+  bundle({
+    plugins: [dts.default({ exclude: ["test/**/*", "tests/**/*"] })],
+    output: {
+      file: `${name}.d.ts`,
+      format: "es",
+    },
+  }),
+];

packages/instrumentation-google-generativeai/src/content-block-mapper.ts

@@ -0,0 +1,129 @@
+/*
+ * Copyright Traceloop
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type * as genai from "@google/genai";
+
+//  Maps a single @google/genai Part to its OTel-compliant part object.
+//
+//   text (thought: true)    → ReasoningPart { type: "reasoning", content }
+//   text                    → TextPart
+//   inlineData (base64)     → BlobPart   { modality derived from mimeType, mime_type, content }
+//   fileData (URI)          → UriPart    { modality derived from mimeType, mime_type, uri }
+//   functionCall            → ToolCallRequestPart
+//   functionResponse        → ToolCallResponsePart
+//   executableCode          → GenericPart { type: "executable_code", language, content }
+//   codeExecutionResult     → GenericPart { type: "code_execution_result", outcome, content }
+//   <unknown>               → GenericPart
+
+/** OTel gen_ai part type strings used by the GenAI mapper. */
+export const GenAIOtelPartType = {
+  TEXT: "text",
+  REASONING: "reasoning",
+  BLOB: "blob",
+  URI: "uri",
+  TOOL_CALL: "tool_call",
+  TOOL_CALL_RESPONSE: "tool_call_response",
+  EXECUTABLE_CODE: "executable_code",
+  CODE_EXECUTION_RESULT: "code_execution_result",
+  UNKNOWN: "unknown",
+} as const;
+
+function genaiModalityFromMimeType(mimeType: string): string {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "document";
+}
+
+export function mapGenAIContentBlock(block: genai.Part | string): object {
+  if (typeof block === "string") {
+    return { type: GenAIOtelPartType.TEXT, content: block };
+  }
+
+  // thought: true marks a model reasoning/thinking block (Gemini thinking models).
+  // text may be undefined on malformed parts — fall back to empty string.
+  if (block.thought === true) {
+    return { type: GenAIOtelPartType.REASONING, content: block.text ?? "" };
+  }
+
+  if (block.text !== undefined) {
+    return { type: GenAIOtelPartType.TEXT, content: block.text };
+  }
+
+  if (block.inlineData) {
+    const mimeType = block.inlineData.mimeType;
+    return {
+      type: GenAIOtelPartType.BLOB,
+      modality: genaiModalityFromMimeType(mimeType ?? ""),
+      ...(mimeType ? { mime_type: mimeType } : {}),
+      content: block.inlineData.data,
+    };
+  }
+
+  if (block.fileData) {
+    const mimeType = block.fileData.mimeType;
+    return {
+      type: GenAIOtelPartType.URI,
+      modality: genaiModalityFromMimeType(mimeType ?? ""),
+      ...(mimeType ? { mime_type: mimeType } : {}),
+      uri: block.fileData.fileUri,
+    };
+  }
+
+  if (block.functionCall) {
+    return {
+      type: GenAIOtelPartType.TOOL_CALL,
+      id: block.functionCall.id ?? null,
+      name: block.functionCall.name,
+      arguments: block.functionCall.args,
+    };
+  }
+
+  if (block.functionResponse) {
+    const resp = block.functionResponse.response;
+    return {
+      type: GenAIOtelPartType.TOOL_CALL_RESPONSE,
+      id: block.functionResponse.id ?? null,
+      // Serialize objects to JSON string so the dashboard can display them.
+      // Normalize undefined (missing response) to null so the field is always present.
+      response:
+        resp === undefined
+          ? null
+          : resp !== null && typeof resp === "object"
+            ? JSON.stringify(resp)
+            : resp,
+    };
+  }
+
+  if (block.executableCode) {
+    return {
+      type: GenAIOtelPartType.EXECUTABLE_CODE,
+      language: block.executableCode.language,
+      content: block.executableCode.code,
+    };
+  }
+
+  if (block.codeExecutionResult) {
+    return {
+      type: GenAIOtelPartType.CODE_EXECUTION_RESULT,
+      outcome: block.codeExecutionResult.outcome,
+      content: block.codeExecutionResult.output,
+    };
+  }
+
+  // Do not spread the block — it may contain circular references or sensitive data.
+  return { type: GenAIOtelPartType.UNKNOWN };
+}

packages/instrumentation-google-generativeai/src/index.ts

@@ -0,0 +1,2 @@
+export { GenAIInstrumentation, genaiFinishReasonMap } from "./instrumentation";
+export type { GenAIInstrumentationConfig } from "./types";