feat(instrumentation-langchain): Add LangChain.js instrumentation skeleton

.github/component_owners.yml

@@ -66,6 +66,9 @@ components:
     # Unmaintained
   packages/instrumentation-kafkajs:
     - seemk
+  packages/instrumentation-langchain:
+    - haneric00
+    - yiyuan-he
   packages/instrumentation-lru-memoizer:
     - blumamir
   packages/instrumentation-mongoose:

packages/instrumentation-langchain/.eslintignore

@@ -0,0 +1 @@
+build

packages/instrumentation-langchain/.eslintrc.js

@@ -0,0 +1,9 @@
+module.exports = {
+  "env": {
+    "mocha": true,
+    "node": true
+  },
+  "extends": "../../eslint.config.js",
+  "ignorePatterns": ["dist/", "*.d.ts"],
+  "root": true
+};

packages/instrumentation-langchain/README.md

@@ -0,0 +1,74 @@
+# OpenTelemetry Spec Instrumentation for LangChain.js
+
+
+[component owners](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/.github/component_owners.yml): @haneric00
+
+
+This module provides automatic instrumentation for the [`AWS Lambda`](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html) 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 [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle.
+
+
+This module provides automatic instrumentation for the ['langchain.js'] (https://v02.api.js.langchain.com/modules/langchain.html) module, which may be loaded using the [`@langchain/...`] packages.
+
+This module is currently under active development and not ready for general use.
+
+## Installation
+
+```bash
+npm install --save @opentelemetry/instrumentation-langchain
+```
+
+
+## Usage
+
+
+To load the Langchain instrumentation, manually instrument the `@langchain/core/callbacks/manager` module. The callbacks manager must be manually instrumented due to the non-traditional module structure in `@langchain/core`.
+
+```typescript
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { LangChainInstrumentation } from "@opentelemetry/instrumentation-langchain";
+import * as CallbackManagerModule from "@langchain/core/callbacks/manager";
+
+const provider = new NodeTracerProvider();
+provider.register();
+
+const lcInstrumentation = new LangChainInstrumentation();
+// LangChain must be manually instrumented as it doesn't have a traditional module structure
+lcInstrumentation.manuallyInstrument(CallbackManagerModule);
+```
+
+For more information on OpenTelemetry Node.js SDK, see the [OpenTelemetry Node.js SDK documentation](https://opentelemetry.io/docs/instrumentation/js/getting-started/nodejs/).
+
+
+## Using a Custom Tracer Provider
+
+You can specify a custom tracer provider when creating the LangChain instrumentation. This is useful when you want to use a non-global tracer provider or have more control over the tracing configuration.
+
+```typescript
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { LangChainInstrumentation } from "@opentelemetry/instrumentation-langchain";
+import * as CallbackManagerModule from "@langchain/core/callbacks/manager";
+
+// Create a custom tracer provider
+const customTracerProvider = new NodeTracerProvider({
+  resource: new Resource({
+    [ATTR_SERVICE_NAME]: "my-langchain-project",
+  }),
+});
+
+// Pass the custom tracer provider to the instrumentation
+const lcInstrumentation = new LangChainInstrumentation({
+  tracerProvider: customTracerProvider,
+});
+
+// Manually instrument the LangChain module
+lcInstrumentation.manuallyInstrument(CallbackManagerModule);
+```
+
+Alternatively, you can set the tracer provider after creating the instrumentation:
+
+```typescript
+const lcInstrumentation = new LangChainInstrumentation();
+lcInstrumentation.setTracerProvider(customTracerProvider);
+```

packages/instrumentation-langchain/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?\$': 'ts-jest',
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+};

packages/instrumentation-langchain/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@opentelemetry/instrumentation-langchain",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Langchain.js instrumentation following OpenTelemetry semantic convention.",
+  "main": "dist/src/index.js",
+  "module": "dist/esm/index.js",
+  "esnext": "dist/esnext/index.js",
+  "types": "dist/src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-telemetry/opentelemetry-js-contrib.git",
+    "directory": "packages/instrumentation-langchain"
+  },
+  "author": "[email protected]",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@langchain/aws": "^0.1.14",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.25.1",
+    "@opentelemetry/instrumentation": "^0.46.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^0.2.0 || ^0.3.0"
+  },
+  "devDependencies": {
+    "@langchain/aws": "^0.1.14",
+    "@langchain/community": "^0.3.53",
+    "@langchain/core": "^0.3.13",
+    "@langchain/coreV0.2": "npm:@langchain/core@^0.2.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.50.0",
+    "@opentelemetry/resources": "^1.25.1",
+    "@opentelemetry/sdk-trace-base": "^1.25.1",
+    "@opentelemetry/sdk-trace-node": "^1.25.1",
+    "@opentelemetry/semantic-conventions": "^1.25.1",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.11",
+    "dotenv": "^16.4.5",
+    "jest": "^29.7.0",
+    "langchain": "^0.3.3",
+    "rimraf": "^5.0.0",
+    "tsc-alias": "^1.8.7",
+    "typescript": "^5.0.0",
+    "nyc": "17.1.0",
+    "semver": "7.7.2",
+    "sinon": "15.2.0",
+    "test-all-versions": "6.1.0"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.json tsconfig.esm.json tsconfig.esnext.json && tsc-alias -p tsconfig.esm.json",
+    "postbuild": "echo '{\"type\": \"module\"}' > ./dist/esm/package.json && rimraf dist/test",
+    "type:check": "tsc --noEmit",
+    "clean": "rimraf build/*",
+    "compile": "tsc -p .",
+    "compile:with-dependencies": "nx run-many -t compile -p @opentelemetry/instrumentation-langchain",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "lint:readme": "node ../../scripts/lint-readme.js",
+    "prepublishOnly": "npm run compile",
+    "tdd": "npm run test -- --watch-extensions ts --watch",
+    "test": "nyc mocha 'test/**/*.ts'",
+    "test-all-versions": "tav",
+    "version:update": "node ../../scripts/version-update.js",
+    "watch": "tsc -w"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "keywords": [],
+  "files": [
+    "dist",
+    "src"
+  ]
+}

packages/instrumentation-langchain/src/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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.
+ */
+
+export * from './instrumentation';

packages/instrumentation-langchain/src/instrumentation-utils.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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.
+ */

packages/instrumentation-langchain/src/instrumentation.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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.
+ */
+
+export class LangChainInstrumentation {
+
+}

packages/instrumentation-langchain/src/span-attributes.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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.
+ */

packages/instrumentation-langchain/tests/callback-handler.test.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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.
+ */

packages/instrumentation-langchain/tsconfig.esm.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "outDir": "dist/esm",
+    "rootDir": "src", 
+    "tsBuildInfoFile": "dist/esm/tsconfig.esm.tsbuildinfo",
+
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": false,
+    "declaration": true,
+    "sourceMap": true,
+    "composite": true,
+    "incremental": true,
+
+    "baseUrl": ".",
+
+    "paths": {
+      "langchainV0.1/*": ["node_modules/langchainV0.1/*"],
+      "@langchain/coreV0.1/*": ["node_modules/@langchain/coreV0.1/*"],
+      "@langchain/aws": ["node_modules/@langchain/aws"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "references": [],
+
+  "tsc-alias": {
+    "verbose": false,
+    "resolveFullPaths": true
+  }
+}

packages/instrumentation-langchain/tsconfig.esnext.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "outDir": "dist/esnext",
+    "rootDir": "src",
+    "tsBuildInfoFile": "dist/esnext/tsconfig.esnext.tsbuildinfo",
+
+    "module": "esnext",
+    "target": "es2017",
+    "moduleResolution": "node",
+
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": false,
+    "declaration": true,
+    "sourceMap": true,
+    "composite": true,
+    "incremental": true,
+
+    "baseUrl": ".",
+
+    "paths": {
+      "langchainV0.1/*": ["node_modules/langchainV0.1/*"],
+      "@langchain/coreV0.1/*": ["node_modules/@langchain/coreV0.1/*"],
+      "@langchain/aws": ["node_modules/@langchain/aws"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "references": []
+}

packages/instrumentation-langchain/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "incremental": true,
+    "composite": true,
+    "outDir": "dist",
+    "rootDir": ".",
+
+    "target": "es2016",
+    "lib": ["esnext"],
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "baseUrl": ".",
+
+    "strict": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": false,
+
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+
+    "paths": {
+      "langchainV0.1/*": ["node_modules/langchainV0.1/*"],
+      "@langchain/coreV0.1/*": ["node_modules/@langchain/coreV0.1/*"],
+      "@langchain/aws": ["node_modules/@langchain/aws"]
+    },
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*.ts",
+              "test/**/*.ts" 
+  ]
+}

release-please-config.json

@@ -31,6 +31,7 @@
     "packages/instrumentation-fs": {},
     "packages/instrumentation-kafkajs": {},
     "packages/instrumentation-lru-memoizer": {},
+    "packages/instrumentation-langchain": { "skip-github-release": true },
     "packages/instrumentation-mongoose": {},
     "packages/instrumentation-runtime-node": {},
     "packages/instrumentation-socket.io": {},