feat: instrumentation-openai (#469)

This adds a `@elastic/opentelemetry-instrumentation-openai` instrumentation.

.github/workflows/release-instrumentation-openai.yml

@@ -0,0 +1,55 @@
+# Release a tagged version of the '@elastic/opentelemetry-instrumentation-openai' package.
+name: release-instrumentation-openai
+
+on:
+  push:
+    tags:
+      - instrumentation-openai-v*.*.*
+
+# 'id-token' perm needed for npm publishing with provenance (see
+# https://docs.npmjs.com/generating-provenance-statements#example-github-actions-workflow)
+permissions:
+  contents: write
+  pull-requests: read
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      PKGDIR: packages/instrumentation-openai
+      PKGNAME: "@elastic/opentelemetry-instrumentation-openai"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'v18.20.4'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: npm publish
+        working-directory: $PKGDIR
+        run: npm publish
+        env:
+          # https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages#publishing-packages-to-the-npm-registry
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: GitHub release
+        run: |
+          npm ci  # need top-level devDeps for github-release.sh script
+          ./scripts/github-release.sh "$PKGDIR" "${{ github.ref_name }}"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Notify in Slack
+        # Only notify on failure, because on success the published GitHub
+        # Release will result in a notification from the GitHub Slack app
+        # (assuming '/github subscribe elastic/elastic-otel-node').
+        if: ${{ failure() }}
+        uses: elastic/oblt-actions/slack/[email protected]
+        with:
+          bot-token: ${{ secrets.SLACK_BOT_TOKEN }}
+          channel-id: "#apm-agent-node"
+          message: '[${{ github.repository }}] Release `${{ env.PKGNAME }}` *${{ github.ref_name }}*'

.github/workflows/release-mockotlpserver.yml

@@ -16,6 +16,9 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    env:
+      PKGDIR: packages/mockotlpserver
+      PKGNAME: "@elastic/mockotlpserver"
     steps:
       - uses: actions/checkout@v4
         with:
@@ -27,7 +30,7 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
 
       - name: npm publish
-        working-directory: ./packages/mockotlpserver
+        working-directory: $PKGDIR
         run: npm publish
         env:
           # https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages#publishing-packages-to-the-npm-registry
@@ -36,7 +39,7 @@ jobs:
       - name: GitHub release
         run: |
           npm ci  # need top-level devDeps for github-release.sh script
-          ./scripts/github-release.sh "packages/mockotlpserver" "${{ github.ref_name }}"
+          ./scripts/github-release.sh "$PKGDIR" "${{ github.ref_name }}"
         env:
           GH_TOKEN: ${{ github.token }}
 
@@ -49,4 +52,4 @@ jobs:
         with:
           bot-token: ${{ secrets.SLACK_BOT_TOKEN }}
           channel-id: "#apm-agent-node"
-          message: '[${{ github.repository }}] Release `@elastic/mockotlpserver` *${{ github.ref_name }}*'
+          message: '[${{ github.repository }}] Release `${{ env.PKGNAME }}` *${{ github.ref_name }}*'

.github/workflows/test.yml → .github/workflows/test-edot.yml

@@ -1,23 +1,20 @@
-name: test
+# Test "packages/opentelemetry-node" (a.k.a. EDOT Node.js).
+name: test-edot
 
 on:
   workflow_dispatch:
   push:
     branches:
     - main
-    paths-ignore:
-    - '**/*.md'
-    - '**/*.asciidoc'
-    - 'docs/**'
-    - 'examples/**'
+    paths:
+    - 'packages/opentelemetry-node/**'
+    - '.github/workflows/test-edot.yml'
   pull_request:
     branches:
     - main
-    paths-ignore:
-    - '**/*.md'
-    - '**/*.asciidoc'
-    - 'docs/**'
-    - 'examples/**'
+    paths:
+    - 'packages/opentelemetry-node/**'
+    - '.github/workflows/test-edot.yml'
 
 # Cancel jobs running for old commits on a PR. Allow concurrent runs on 'main'.
 concurrency:
@@ -81,7 +78,12 @@ jobs:
     - name: Update npm to a version that supports package-lock lockfileVersion=2.
       if: ${{ startsWith(matrix.node, '14') }}
       run: npm install -g npm@9 # npm@9 supports node >=14.17.0
-    - run: npm run ci-all
+    - name: npm ci in mockotlpserver package, used in EDOT tests
+      run: npm ci
+      working-directory: packages/mockotlpserver
+    - run: npm ci
+      working-directory: packages/opentelemetry-node
     - run: npm test
+      working-directory: packages/opentelemetry-node
 
   # TODO: test-windows eventually

.github/workflows/test-instrumentation-openai.yml

@@ -0,0 +1,94 @@
+name: test-instrumentation-openai
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+    - main
+    paths:
+    - 'packages/instrumentation-openai/**'
+    - '.github/workflows/test-instrumentation-openai.yml'
+  pull_request:
+    branches:
+    - main
+    paths:
+    - 'packages/instrumentation-openai/**'
+    - '.github/workflows/test-instrumentation-openai.yml'
+
+# Cancel jobs running for old commits on a PR. Allow concurrent runs on 'main'.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+  contents: read
+
+jobs:
+  unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node:
+          - '22'
+          - '20'
+          - '18'
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node }}
+    - run: npm ci
+      working-directory: packages/instrumentation-openai
+    - run: npm run compile
+      working-directory: packages/instrumentation-openai
+    - run: npm test
+      working-directory: packages/instrumentation-openai
+
+  # This runs the unit tests against a number of 'openai' versions in the
+  # supported range.
+  test-all-versions:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 18
+    - run: npm install
+      working-directory: packages/instrumentation-openai
+    - run: npm run compile
+      working-directory: packages/instrumentation-openai
+    - run: npm run test-all-versions
+      working-directory: packages/instrumentation-openai
+
+  integration-test:
+    runs-on: ubuntu-latest
+    services:
+      ollama:
+        # A light fork of Ollama to float some in-progress contributions related
+        # to more closely matching OpenAI behavior.
+        image: ghcr.io/elastic/ollama/ollama:testing
+        ports:
+          - 11434:11434
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 18
+    - name: Pull Ollama models
+      run: |
+        source packages/instrumentation-openai/ollama.env
+        curl -s http://localhost:11434/api/pull -d "{\"model\": \"$TEST_MODEL_TOOLS\"}"
+        curl -s http://localhost:11434/api/pull -d "{\"model\": \"$TEST_MODEL_EMBEDDINGS\"}"
+        curl -s http://localhost:11434/api/tags | jq
+        # Dump Ollama container logs if it doesn't appear to be working.
+        curl -fsS http://localhost:11434/ || docker logs $(docker ps -q)
+    - run: npm install
+      working-directory: packages/instrumentation-openai
+    - run: npm run compile
+      working-directory: packages/instrumentation-openai
+    - name: Integration tests
+      run: |
+        set -a; source ./ollama.env
+        npm run test:integration
+      working-directory: packages/instrumentation-openai

CONTRIBUTING.md

@@ -29,7 +29,7 @@ obvious at first sight.
 Ensure your code contribution pass our linting (style and static checking):
 
 ```
-npm run ci-all
+npm run ci-all      # runs 'npm ci' in all package dirs; see note 1
 npm run lint
 ```
 
@@ -39,22 +39,18 @@ Often style checking issues can be automatically resolve by running:
 npm run lint:fix
 ```
 
+> *Note 1*: While this repo holds multiple packages, it is *not* using npm workspaces. This means that one must `npm ci` (or `npm install`) in each package directory separately. See [this issue](https://github.com/elastic/elastic-otel-node/pull/279) for why npm workspaces are not being used.
+
 
 ## Testing
 
-tl;dr:
+This repo holds a number of mostly-independent packages. Please see the
+`packages/**/TESTING.md` document in a specific package for notes on how to run
+its test suite. For example:
 
-```shell
-npm run ci-all   # runs 'npm ci' in all package dirs; see note 1
-cd packages/opentelemetry-node
-npm run test-services:start  # requires Docker
-npm test
-npm run test-services:stop
-```
+- [Testing opentelemetry-node](./packages/opentelemetry-node/TESTING.md)
+- [Testing instrumentation-openai](./packages/instrumentation-openai/TESTING.md)
 
-See [TESTING.md](./TESTING.md) for full details.
-
-> *Note 1*: While this repo holds multiple packages, it is *not* using npm workspaces. This means that one must `npm ci` (or `npm install`) in each package directory separately. See [this issue](https://github.com/elastic/elastic-otel-node/pull/279) for why npm workspaces are not being used.
 
 
 ## Commit message guidelines

RELEASING.md

@@ -14,6 +14,7 @@ packages will use a prefix (the basename of the npm package name). For example,
 | ----------------------------- | ------------------- | -------- |
 | `@elastic/opentelemetry-node` | `v*`                | v1.0.0   |
 | `@elastic/mockotlpserver`     | `mockotlpserver-v*` | mockotlpserver-v0.2.0 |
+| `@elastic/opentelemetry-instrumentation-openai` | `instrumentation-openai-v*` | instrumentation-openai-v0.3.0 |
 
 
 ## How to release `@elastic/opentelemetry-node`
@@ -40,26 +41,32 @@ Assuming "x.y.z" is the release verison:
     https://github.com/elastic/elastic-otel-node/actions/workflows/release.yml
 
 
-## How to release `@elastic/mockotlpserver`
+## How to release other packages
 
-Assuming "x.y.z" is the release verison:
+Assuming:
+- **VERSION="x.y.z"** is the release version and
+- **PKGSUBDIR="instrumentation-openai"** is the package being released.
+  (Note that the PKGSUBDIR, the directory under "packages/" is *not necessarily*
+  the basename of the npm package.)
 
 1. Choose the appropriate version number according to semver.
 
 2. Create a PR with these changes:
-    - Bump the "version" in "packages/mockotlpserver/package.json".
-    - Run `npm install` in "packages/mockotlpserver/" to update "packages/mockotlpserver/package-lock.json".
-    - Update "packages/mockotlpserver/CHANGELOG.md" as necessary.
-    - Name the PR something like "release @elastic/[email protected]".
+
+    - Bump the "version" in "packages/$PKGSUBDIR/package.json".
+    - Run `npm install` in "packages/$PKGSUBDIR/" to update "packages/$PKGSUBDIR/package-lock.json".
+    - Update "packages/$PKGSUBDIR/CHANGELOG.md" as necessary.
+    - Name the PR something like "release $PKGSUBDIR x.y.z".
 
 3. Get the PR approved and merged.
 
 4. Working on the elastic repo (not a fork), tag the commit as follows:
+
     ```
-    git tag mockotlpserver-vx.y.z
-    git push origin mockotlpserver-vx.y.z
+    git tag $PKGSUBDIR-vx.y.z
+    git push origin $PKGSUBDIR-vx.y.z
     ```
-    The GitHub Actions "release-mockotlpserver" workflow will handle the release
-    steps -- including the `npm publish`. See the appropriate run at:
-    https://github.com/elastic/elastic-otel-node/actions/workflows/release-mockotlpserver.yml
 
+    The GitHub Actions "release-$PKGSUBDIR" workflow will handle the release
+    steps -- including the `npm publish`. See the appropriate run at:
+    https://github.com/elastic/elastic-otel-node/actions

examples/package.json

@@ -3,7 +3,9 @@
   "license": "Apache-2.0",
   "private": true,
   "version": "0.1.0",
-  "scripts": {},
+  "scripts": {
+    "clean": "rm -rf node_modules"
+  },
   "dependencies": {
     "@elastic/opentelemetry-node": "../packages/opentelemetry-node",
     "@opentelemetry/api": "^1.9.0",