Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions .github/workflows/vertexai-typescript-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
name: Vertex AI TypeScript compatibility

on:
pull_request:
branches: [dev, main]
paths:
- 'typescript/packages/traceai_vertexai/**'
- 'typescript/packages/fi-core/**'
- 'typescript/packages/fi-semantic-conventions/**'
- 'typescript/pnpm-lock.yaml'
- 'typescript/tsconfig*.json'
- '.github/workflows/vertexai-typescript-tests.yml'

permissions:
contents: read

jobs:
compatibility:
name: Vertex SDK ${{ matrix.sdk }} / Node ${{ matrix.node }}
runs-on: macos-15
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
sdk: ['1.0.0', '1.12.0']
node: ['18.19.0', '22.15.0', '26.8.1']
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: '22.15.0'
- name: Install frozen build dependencies
run: |
npm install --global pnpm@10.30.1
pnpm --dir typescript --filter '@traceai/fi-instrumentation-vertexai...' install --ignore-scripts --frozen-lockfile
- name: Build, unit test and pack without outbound networking
run: |
policy="$GITHUB_WORKSPACE/typescript/packages/traceai_vertexai/test/network.sb"
sandbox-exec -f "$policy" pnpm --dir typescript --filter '@traceai/fi-instrumentation-vertexai...' run build
sandbox-exec -f "$policy" pnpm --dir typescript --filter @traceai/fi-instrumentation-vertexai test --runInBand
sandbox-exec -f "$policy" pnpm --dir typescript/packages/traceai_vertexai pack --pack-destination "$RUNNER_TEMP/tarballs"
sandbox-exec -f "$policy" python3 -I .github/release/release_plan.py --check
- name: Install packed adapter with registry dependencies and real SDK
env:
VERTEX_SDK: ${{ matrix.sdk }}
run: |
tarball=$(find "$RUNNER_TEMP/tarballs" -name '*.tgz' -type f)
npm install --prefix "$RUNNER_TEMP/consumer" --ignore-scripts --no-audit --no-fund \
"$tarball" "@google-cloud/vertexai@$VERTEX_SDK"
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: ${{ matrix.node }}
- name: Verify real SDK, README and OTLP payloads without outbound networking
run: |
export VERTEX_CONSUMER="$RUNNER_TEMP/consumer"
export VERTEX_INSTRUMENTATION="$VERTEX_CONSUMER/node_modules/@traceai/fi-instrumentation-vertexai"
sandbox-exec -f typescript/packages/traceai_vertexai/test/network.sb \
node --test typescript/packages/traceai_vertexai/test/compat.test.cjs \
typescript/packages/traceai_vertexai/test/export.test.cjs \
typescript/packages/traceai_vertexai/test/readme.test.cjs
2 changes: 1 addition & 1 deletion typescript/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"scripts": {
"build": "pnpm run build:ordered",
"build:deps": "pnpm --filter @traceai/fi-core --filter @traceai/fi-semantic-conventions run build",
"build:consumers": "pnpm --filter @traceai/openai --filter @traceai/anthropic --filter @traceai/langchain --filter @traceai/bedrock --filter @traceai/vercel --filter @traceai/chromadb --filter @traceai/pinecone --filter @traceai/qdrant --filter @traceai/weaviate --filter @traceai/milvus --filter @traceai/lancedb --filter @traceai/mongodb --filter @traceai/pgvector --filter @traceai/redis --filter @traceai/together --filter @traceai/huggingface --filter @traceai/vllm --filter @traceai/deepseek --filter @traceai/fireworks --filter @traceai/cerebras --filter @traceai/xai run build",
"build:consumers": "pnpm --filter @traceai/openai --filter @traceai/anthropic --filter @traceai/langchain --filter @traceai/bedrock --filter @traceai/vercel --filter @traceai/chromadb --filter @traceai/pinecone --filter @traceai/qdrant --filter @traceai/weaviate --filter @traceai/milvus --filter @traceai/lancedb --filter @traceai/mongodb --filter @traceai/pgvector --filter @traceai/redis --filter @traceai/together --filter @traceai/huggingface --filter @traceai/vllm --filter @traceai/deepseek --filter @traceai/fireworks --filter @traceai/cerebras --filter @traceai/xai --filter @traceai/fi-instrumentation-vertexai run build",
"build:ordered": "pnpm run build:deps && pnpm run build:consumers",
"test": "pnpm run -r test",
"test:coverage": "pnpm run -r test:coverage",
Expand Down
96 changes: 57 additions & 39 deletions typescript/packages/traceai_vertexai/README.md
Original file line number Diff line number Diff line change
@@ -1,64 +1,82 @@
# @traceai/fi-instrumentation-vertexai

OpenTelemetry instrumentation for Google Cloud Vertex AI SDK. Part of traceAI, Future AGI's OpenTelemetry instrumentation libraries.
Trace generation, chat, streaming responses and token-count requests from the legacy `@google-cloud/vertexai` SDK in Future AGI.

[Documentation](https://docs.futureagi.com/docs/integrations/traceai/vertexai) · [Source](https://github.com/future-agi/traceAI/tree/dev/typescript/packages/traceai_vertexai) · [Issues](https://github.com/future-agi/traceAI/issues)
Google has deprecated this SDK in favor of [`@google/genai`](https://github.com/googleapis/js-genai). Use this adapter for existing Vertex AI SDK applications; it does not instrument the modern Google Gen AI SDK. See Google's [migration guide](https://cloud.google.com/vertex-ai/generative-ai/docs/deprecations/genai-vertexai-sdk) when moving an application.

## Install

Use Node.js 18.19+ on the 18.x line, or Node.js 20.6+ (a maintained Node.js release is recommended).

```sh
npm install @traceai/fi-instrumentation-vertexai @traceai/fi-core @opentelemetry/instrumentation @opentelemetry/api@^1.9.0 @opentelemetry/context-async-hooks@^2.0.1
npm install @google-cloud/vertexai@"^1.0.0"
npm install @traceai/fi-instrumentation-vertexai @traceai/fi-core @google-cloud/vertexai@"^1.0.0" @opentelemetry/api@"^1.9.0" @opentelemetry/context-async-hooks@"^2.0.1"
```

The SDK ranges above match this instrumentor's module-version filters. Install
only the SDKs your application uses. For Future AGI export, set `FI_API_KEY` and
`FI_SECRET_KEY` in your environment; keep provider credentials outside source code.

## Package entry points

This source revision fixes the package entry points. Both CommonJS `require()`
and native Node ESM `import` use the same CommonJS implementation; this avoids
broken, extensionless ESM build imports. The corrected packages still need a
patch release. A previously published `0.1.0` tarball is not changed by this README.
Configure Google Application Default Credentials and set `GOOGLE_CLOUD_PROJECT` for the Google project where Vertex AI is enabled. Set `FI_API_KEY` and `FI_SECRET_KEY` for Future AGI. Keep credentials outside your source code.

## Quick start
## Trace a request

Load this setup **before** loading the SDK you want to instrument. This CommonJS
example registers tracing; it does not make a provider request.
Save this as `vertex.cjs`. Manual instrumentation works when the SDK is already loaded, so the example does not depend on import order.

```javascript
const { context } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register, ProjectType } = require("@traceai/fi-core");
// Standalone process only: if your OTel SDK already installs a context manager,
// reuse it instead of registering another one.
context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { VertexAIInstrumentation } = require("@traceai/fi-instrumentation-vertexai");
const tracerProvider = register({
projectName: "vertexai-app",
projectType: ProjectType.OBSERVE,
});
registerInstrumentations({
tracerProvider, instrumentations: [new VertexAIInstrumentation()],
const vertexai = require("@google-cloud/vertexai");

// In an application with an existing OTel SDK, reuse its context manager.
context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
const provider = register({ projectName: "vertexai-app", projectType: ProjectType.OBSERVE });
const instrumentation = new VertexAIInstrumentation();
instrumentation.setTracerProvider(provider);
instrumentation.manuallyInstrument(vertexai);

async function main() {
try {
const vertex = new vertexai.VertexAI({
project: process.env.GOOGLE_CLOUD_PROJECT,
location: process.env.GOOGLE_CLOUD_LOCATION || "us-central1",
});
const model = vertex.getGenerativeModel({ model: "gemini-2.5-flash" });
const result = await model.generateContent("Explain why the sky looks blue in one sentence.");
console.log(result.response.candidates?.[0]?.content?.parts);
} finally {
instrumentation.disable();
await provider.shutdown();
}
}

main().catch(console.error);
```

Run `node vertex.cjs`, then open the **vertexai-app** project in Future AGI to inspect the request and response. `register()` exports standard OTLP to `https://api.futureagi.com/tracer/v1/traces` using your Future AGI credentials.

CommonJS applications can alternatively register the instrumentation before requiring the SDK to use automatic module hooks. For native ESM, import the SDK namespace and pass it to `manuallyInstrument()`; do not rely on static import ordering for automatic hooks.

## Capture and privacy

The adapter covers the stable and preview `GenerativeModel` and `ChatSession` APIs in SDK versions `>=1.0.0 <2.0.0`. It records model, generation settings, chat history, text and tool content, finish reasons, and usage returned by the SDK. It does not add embedding or cached-content management APIs that these generation hooks do not implement.

Streaming spans finish when the SDK's existing `response` promise settles. You can consume `result.stream`, await `result.response`, or do both; the adapter does not consume your iterator or replace either object. Breaking out of iteration does not cancel the SDK's independent aggregation. Configure the SDK's request timeout when you need to limit request duration.

Content capture is bounded. Raw request/response bodies, media bytes, file URIs, and provider error messages or stacks are not exported. Text, function arguments and function results may still contain sensitive information. To disable content capture, construct the instrumentation with:

```javascript
const instrumentation = new VertexAIInstrumentation({
traceConfig: { hideInputs: true, hideOutputs: true },
});
```

`register()` installs a tracer provider, not an async context manager. The
explicit context manager above keeps nested asynchronous calls in one trace.
Run your application's SDK calls after this setup. Call
`await tracerProvider.shutdown()` when the application finishes to flush pending
spans. For ESM, follow the documentation for your OpenTelemetry loader and SDK
instead of assuming import order alone enables automatic patching.
The shared FI controls also support input/output message hiding, text hiding, PII redaction, and the corresponding `FI_HIDE_*` environment variables. Content is kept in the standard `gen_ai.input.messages` and `gen_ai.output.messages` attributes so granular text controls also apply to function data.

Calling `disable()` restores this instance's automatic and manual hooks. Requests already in progress still complete their spans. Do not register an additional instrumentor for the same SDK methods.

## Compatibility and privacy
## Troubleshooting

This instruments the SDK hooks implemented by this package, not every API offered
by the provider. The install ranges above are intentionally limited to the module versions this
instrumentor patches; its peer declarations may be broader.
Traces can contain prompts, responses, and tool data; configure capture and
redaction before sending production traffic.
- **No spans:** pass the provider returned by `register()` to `setTracerProvider()` and pass the actual SDK module to `manuallyInstrument()` before making requests.
- **Authentication or model errors:** check your Google credentials, project, regional model availability and SDK response. Provider errors retain their original behavior in your application; spans record failure without copying provider error text.
- **Missing stream spans at shutdown:** await the SDK's `result.response` before shutting down the tracer provider.

## License

Expand Down
5 changes: 3 additions & 2 deletions typescript/packages/traceai_vertexai/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
"clean": "rimraf dist",
"lint": "eslint src --ext .ts",
"test": "jest",
"test:compat": "node --test test/compat.test.cjs test/export.test.cjs test/readme.test.cjs",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"prepublishOnly": "npm run clean && npm run build"
Expand Down Expand Up @@ -63,15 +64,15 @@
"typescript": "^5.3.0"
},
"peerDependencies": {
"@google-cloud/vertexai": ">=1.0.0"
"@google-cloud/vertexai": ">=1.0.0 <2.0.0"
},
"peerDependenciesMeta": {
"@google-cloud/vertexai": {
"optional": true
}
},
"engines": {
"node": ">=18.0.0"
"node": "^18.19.0 || >=20.6.0"
},
"homepage": "https://docs.futureagi.com/docs/integrations/traceai/vertexai",
"bugs": {
Expand Down
Loading
Loading