@saguiitay/eventhouse-ai-observability 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +48 -0
- package/README.md +159 -43
- package/dist/adapters/openai.d.ts +25 -0
- package/dist/adapters/vercel.d.ts +25 -0
- package/dist/{chunk-XFSF25OP.js → chunk-XGCHW72B.js} +11 -55
- package/dist/{chunk-XFSF25OP.js.map → chunk-XGCHW72B.js.map} +1 -1
- package/dist/copilot.js +5 -3
- package/dist/copilot.js.map +1 -1
- package/dist/index.d.ts +1 -6
- package/dist/index.js +3 -11
- package/dist/openai.d.ts +12 -0
- package/dist/openai.js +408 -0
- package/dist/openai.js.map +1 -0
- package/dist/validate.d.ts +2 -0
- package/dist/validate.js +237 -0
- package/dist/validate.js.map +1 -0
- package/dist/validation/fabric.d.ts +29 -0
- package/dist/vercel.d.ts +15 -0
- package/dist/vercel.js +369 -0
- package/dist/vercel.js.map +1 -0
- package/docs/architecture.md +19 -3
- package/docs/copilot-adapter.md +1 -1
- package/docs/extending.md +45 -1
- package/docs/fabric-setup.md +24 -0
- package/docs/implementation-report.md +62 -18
- package/docs/openai-adapter.md +137 -0
- package/docs/quickstart.md +75 -6
- package/docs/research-eventstream.md +8 -6
- package/docs/research.md +1 -1
- package/docs/security.md +1 -1
- package/docs/telemetry-schema.md +18 -0
- package/docs/vercel-adapter.md +201 -0
- package/examples/README.md +85 -5
- package/examples/copilot-basic/package.json +1 -1
- package/examples/openai-basic/env.example +8 -0
- package/examples/openai-basic/index.ts +46 -0
- package/examples/shared.ts +3 -62
- package/examples/telemetry.ts +124 -0
- package/examples/vercel-basic/env.example +8 -0
- package/examples/vercel-basic/index.ts +60 -0
- package/fabric-setup.zip +0 -0
- package/package.json +39 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,7 +1,55 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0 - prepared 2026-11-15 (unpublished)
|
|
4
|
+
|
|
5
|
+
- Add optional `/openai` and `/vercel` integrations sharing the existing
|
|
6
|
+
OpenTelemetry engine, privacy filtering, and Fabric/custom exporters.
|
|
7
|
+
- Keep SDK-specific dependencies optional and isolate each public entry point.
|
|
8
|
+
- Remove 287 machine-specific registry tarball routes from the lockfile without
|
|
9
|
+
changing versions or integrity hashes. Add a registry-agnostic pnpm hook and
|
|
10
|
+
regression tests to keep registry resolutions portable.
|
|
11
|
+
- Add runnable OpenAI and Vercel samples with per-example environment templates,
|
|
12
|
+
streaming, metadata-only diagnostics, and offline lifecycle tests.
|
|
13
|
+
- Remove built-in OTLP configuration and the runtime OTLP dependency/export.
|
|
14
|
+
Supply a standard exporter through `exporter` instead of `transport`,
|
|
15
|
+
`endpoint`, or `headers`. Root configuration no longer reads OTLP environment
|
|
16
|
+
variables; checkout examples explicitly construct the official exporter.
|
|
17
|
+
- Upgrade development Zod to 4.6.7 to fix GHSA-mrhx-c7xc-m3w5
|
|
18
|
+
(CVE-2023-54404); remove affected Zod resolutions from the lockfile.
|
|
19
|
+
- Normalize provider-reported cache and reasoning token details on model-request
|
|
20
|
+
spans without adding them again to input/output totals.
|
|
21
|
+
- Change the Fabric distribution policy: include one generated
|
|
22
|
+
`fabric-setup.zip` at the npm package root for public setup downloads, without
|
|
23
|
+
access to the private source repository. Keep raw checkout Fabric assets and
|
|
24
|
+
tenant-bound files out of the tarball. Preserve standalone versioned ZIPs and
|
|
25
|
+
Release/Actions assets for repository collaborators.
|
|
26
|
+
- Generate setup assets in isolation with version/schema/SHA-256 metadata
|
|
27
|
+
matching the package. Permit only this personal project's authored generic
|
|
28
|
+
public-API templates and synthetic samples; exclude Microsoft-private content,
|
|
29
|
+
tenant identifiers/bindings, credentials, private registry configuration,
|
|
30
|
+
real telemetry, and copied external-repository files. Neutrality alone does
|
|
31
|
+
not establish safe source provenance.
|
|
32
|
+
- Add the installed `eventhouse-ai-observability-validate` CLI for opt-in producer,
|
|
33
|
+
ingestion, and trace/parent verification, with environment-only credentials
|
|
34
|
+
and offline tests.
|
|
35
|
+
- Remove low-level root exports `createEngine`, `serializeSpan`, and
|
|
36
|
+
`redactSecrets`. Use `createObservability`, SDK adapters, and the standard
|
|
37
|
+
exporter interface; `EventstreamExporter` remains public.
|
|
38
|
+
|
|
39
|
+
## 0.1.2 - 2026-11-14
|
|
40
|
+
|
|
41
|
+
- Published and registry-verified on npmjs; does not include the new setup ZIP.
|
|
42
|
+
- Publish to npmjs using GitHub Actions OIDC trusted publishing without a stored
|
|
43
|
+
npm token. Provenance requires a public source repository and is not generated
|
|
44
|
+
for this private repository.
|
|
45
|
+
- Preserve the separate GitHub Packages publishing workflow and registry defaults.
|
|
46
|
+
- Verify packed publication settings and the published npmjs version.
|
|
47
|
+
- Update the basic example's dependency pin and instrumentation scope to 0.1.2.
|
|
48
|
+
- No runtime behavior changes beyond the instrumentation scope version.
|
|
49
|
+
|
|
3
50
|
## 0.1.1 - 2026-11-12
|
|
4
51
|
|
|
52
|
+
- Published and registry-verified on GitHub Packages.
|
|
5
53
|
- Fix the reported development-dependency advisories by upgrading AJV to 8.18.0
|
|
6
54
|
and fast-uri to 3.1.9.
|
|
7
55
|
- Publish with public access and require verified public GitHub package visibility
|
package/README.md
CHANGED
|
@@ -2,14 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
Instrument an **existing GitHub Copilot SDK session** and send OpenTelemetry spans directly to Microsoft Fabric Eventstream. No Collector, gateway, or custom frontend.
|
|
4
4
|
|
|
5
|
-
1.
|
|
6
|
-
2. Set `FABRIC_EVENTSTREAM_CONNECTION_STRING` to the Fabric-provided connection string. If it omits `EntityPath`, also set `FABRIC_EVENTSTREAM_ENTITY_NAME` to the provided event hub name.
|
|
7
|
-
3. Configure [GitHub Packages authentication](#installation-from-github-packages), then install and instrument:
|
|
5
|
+
1. Install from npmjs (or your organization's approved npm mirror):
|
|
8
6
|
|
|
9
7
|
```sh
|
|
10
8
|
npm install @saguiitay/eventhouse-ai-observability
|
|
11
9
|
```
|
|
12
10
|
|
|
11
|
+
2. Obtain the [Fabric setup assets](#fabric-setup-bundle-and-ingestion-check). In Fabric, add an Eventstream **Custom endpoint source**, then connect its output to an Eventhouse KQL database. Use the source's **Event Hub** producer credentials, not an outward destination. Apply the [schema and setup](docs/fabric-setup.md).
|
|
12
|
+
3. Set `FABRIC_EVENTSTREAM_CONNECTION_STRING` to the Fabric-provided connection string. If it omits `EntityPath`, also set `FABRIC_EVENTSTREAM_ENTITY_NAME` to the provided event hub name. Instrument your existing session:
|
|
13
|
+
|
|
13
14
|
```typescript
|
|
14
15
|
import { observeCopilot } from "@saguiitay/eventhouse-ai-observability/copilot";
|
|
15
16
|
|
|
@@ -26,9 +27,11 @@ try {
|
|
|
26
27
|
}
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
Version 0.1.1 is published
|
|
30
|
-
|
|
31
|
-
|
|
30
|
+
Version **0.1.1 is published and registry-verified on GitHub Packages**;
|
|
31
|
+
**0.1.2 is published and registry-verified on npmjs**. This checkout prepares
|
|
32
|
+
**0.2.0, not yet published**, including the setup ZIP and new SDK entry points.
|
|
33
|
+
A separate npmjs workflow publishes future versions directly using GitHub
|
|
34
|
+
Actions OIDC trusted publishing.
|
|
32
35
|
To test an unpublished release,
|
|
33
36
|
run `pnpm install` and `pnpm pack`; install the root tarball with npm.
|
|
34
37
|
Node.js **22.15+** (including Node 24 LTS), ESM, Copilot SDK **1.0.31** / compatible
|
|
@@ -36,27 +39,53 @@ Node.js **22.15+** (including Node 24 LTS), ESM, Copilot SDK **1.0.31** / compat
|
|
|
36
39
|
The repository's `.npmrc` routes only `@saguiitay` packages to GitHub Packages;
|
|
37
40
|
other dependencies continue to use your configured, organization-approved registry.
|
|
38
41
|
|
|
39
|
-
Packing with `pnpm pack` or `npm pack` automatically rebuilds the ESM runtime
|
|
40
|
-
TypeScript declarations through `prepack`; a failed build stops packaging. Do not
|
|
42
|
+
Packing with `pnpm pack` or `npm pack` automatically rebuilds the ESM runtime,
|
|
43
|
+
TypeScript declarations, and neutral setup ZIP through `prepack`; a failed build stops packaging. Do not
|
|
41
44
|
disable lifecycle scripts when preparing a release.
|
|
42
45
|
|
|
43
46
|
The tarball includes these documentation pages and example sources/templates, so
|
|
44
|
-
relative links work from the installed package. Run
|
|
45
|
-
|
|
46
|
-
|
|
47
|
+
relative links work from the installed package. Run examples from the source
|
|
48
|
+
checkout. Starting with the prepared 0.2.0 package, the tarball also includes
|
|
49
|
+
one generated `fabric-setup.zip`; raw working-tree Fabric assets and tenant
|
|
50
|
+
content remain excluded.
|
|
47
51
|
|
|
48
52
|
Metadata only is captured by default. Prompts, responses, tool arguments, tool results, and error messages are not collected unless explicitly enabled. Credentials are redacted; review [security](docs/security.md) before enabling content.
|
|
49
53
|
|
|
50
54
|
## What is included
|
|
51
55
|
|
|
52
|
-
One npm package with root and `/
|
|
56
|
+
One npm package with root, `/copilot`, `/openai`, and `/vercel` exports and ordinary internal modules under `src`. OpenTelemetry supplies batching and sampling; our code supplies the Fabric exporter, privacy filtering, and SDK adapters. Standard OpenTelemetry exporters can be supplied by the application. Includes versioned JSON, Eventhouse schema and twenty analytics queries, native dashboard assets, provisioning, [runnable examples for every adapter](examples), local integration tests, and an opt-in live check.
|
|
57
|
+
|
|
58
|
+
### Other SDKs
|
|
59
|
+
|
|
60
|
+
The source checkout also supports [OpenAI](docs/openai-adapter.md) Chat Completions
|
|
61
|
+
and Responses, and [Vercel AI SDK](docs/vercel-adapter.md) native telemetry.
|
|
62
|
+
These adapters share the same privacy controls, sampling, Fabric export, custom exporters,
|
|
63
|
+
and diagnostics; each SDK is an optional peer dependency. Install only the SDKs
|
|
64
|
+
you use. The new entry points are included in version 0.2.0; until it is
|
|
65
|
+
published, build or pack this checkout to use them.
|
|
66
|
+
|
|
67
|
+
OpenAI request instrumentation does not create agent or tool-execution spans
|
|
68
|
+
from model-generated tool calls. Vercel integrates with the SDK's existing
|
|
69
|
+
tracing rather than adding a second set of spans. See the adapter docs for
|
|
70
|
+
supported versions, streaming behavior, and complete lifecycle examples.
|
|
71
|
+
Runnable checkout samples are `pnpm example:openai` and `pnpm example:vercel`;
|
|
72
|
+
see [sample setup](examples/README.md#openai-and-vercel-ai-sdks).
|
|
73
|
+
|
|
74
|
+
For an existing OTLP destination, install OpenTelemetry's official exporter
|
|
75
|
+
separately and supply it through the standard `SpanExporter` interface:
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
npm install @opentelemetry/exporter-trace-otlp-http
|
|
79
|
+
```
|
|
53
80
|
|
|
54
81
|
```typescript
|
|
55
82
|
import { createObservability } from "@saguiitay/eventhouse-ai-observability";
|
|
83
|
+
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
|
|
56
84
|
|
|
57
85
|
const observer = createObservability({
|
|
58
|
-
|
|
59
|
-
|
|
86
|
+
exporter: new OTLPTraceExporter({
|
|
87
|
+
url: "https://your-existing-otlp-service.example/v1/traces",
|
|
88
|
+
}),
|
|
60
89
|
});
|
|
61
90
|
const span = observer.startSpan("invoke_agent my-framework", {
|
|
62
91
|
attributes: { "gen_ai.operation.name": "invoke_agent" },
|
|
@@ -66,7 +95,11 @@ await observer.flush();
|
|
|
66
95
|
await observer.shutdown();
|
|
67
96
|
```
|
|
68
97
|
|
|
69
|
-
|
|
98
|
+
Fabric is the only built-in transport. This package does not depend on or
|
|
99
|
+
re-export an OTLP exporter, or read `OTEL_EXPORTER_OTLP_*` configuration.
|
|
100
|
+
The supplied exporter owns its endpoint, headers, and environment settings.
|
|
101
|
+
Eventstream receives JSON events over the official Event Hubs AMQP producer
|
|
102
|
+
protocol, not OTLP.
|
|
70
103
|
|
|
71
104
|
Examples print their selected transport and final export counters, and fail after
|
|
72
105
|
cleanup if telemetry failed or was dropped. In applications, use
|
|
@@ -96,11 +129,72 @@ operator's 0.1.0 deployment on 2026-11-12**, based on the operator's reported
|
|
|
96
129
|
published-package installation, successful Copilot execution, three acknowledged
|
|
97
130
|
spans with no drops/failures, rows in `AIObservabilityTraces`, and dashboard
|
|
98
131
|
visibility. This does not establish support for all tenants, automated
|
|
99
|
-
provisioning, or a live run of 0.1.1. The separate [live validation
|
|
132
|
+
provisioning, or a live run of 0.1.1, 0.1.2, or the prepared 0.2.0. The separate [live validation
|
|
100
133
|
script](docs/quickstart.md#live-fabric-validation) checks producer acceptance,
|
|
101
134
|
Eventhouse ingestion, KQL lookup, and parent-child relationships; its execution
|
|
102
135
|
has not been reported.
|
|
103
136
|
|
|
137
|
+
## Fabric setup bundle and ingestion check
|
|
138
|
+
|
|
139
|
+
The public download channel is the **npm tarball**, not GitHub Releases or
|
|
140
|
+
Actions artifacts: the source repository stays private. Starting with 0.2.0,
|
|
141
|
+
install the package first, then locate its root `fabric-setup.zip`. For a local
|
|
142
|
+
application install in PowerShell:
|
|
143
|
+
|
|
144
|
+
```powershell
|
|
145
|
+
npm install @saguiitay/eventhouse-ai-observability
|
|
146
|
+
$npmRoot = (npm root).Trim()
|
|
147
|
+
$packageRoot = Join-Path $npmRoot '@saguiitay\eventhouse-ai-observability'
|
|
148
|
+
$archive = Join-Path $packageRoot 'fabric-setup.zip'
|
|
149
|
+
if (-not (Test-Path -LiteralPath $archive)) {
|
|
150
|
+
throw 'This installed version has no setup ZIP. Use a package containing the 0.2.0 bundle.'
|
|
151
|
+
}
|
|
152
|
+
$destination = Join-Path (Get-Location) 'fabric-setup'
|
|
153
|
+
Expand-Archive -LiteralPath $archive -DestinationPath $destination
|
|
154
|
+
Set-Location $destination
|
|
155
|
+
Get-Content .\README.md
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**0.2.0 is not yet published**; today's npmjs 0.1.2 install does not contain this
|
|
159
|
+
ZIP. To evaluate it before publication, collaborators can install the prepared
|
|
160
|
+
root tarball instead of the registry package. Existing published users can use
|
|
161
|
+
the [manual setup instructions](docs/fabric-setup.md#manual-setup--unsupported-tenant-fallback).
|
|
162
|
+
|
|
163
|
+
The archive root contains `README.md`, `manifest.json`, and `fabric\` with
|
|
164
|
+
schema, queries, dashboard, Eventstream template, provisioning/update scripts,
|
|
165
|
+
and synthetic samples. Keep that directory structure intact and follow the
|
|
166
|
+
extracted README. Its manifest's package version must match the installed
|
|
167
|
+
package version; schema version and SHA-256 hashes describe the generated bytes.
|
|
168
|
+
Hashes detect drift, not publisher authenticity.
|
|
169
|
+
|
|
170
|
+
Only this personal project's authored generic templates, public-API definitions,
|
|
171
|
+
and synthetic samples belong in the archive, not Microsoft-private code,
|
|
172
|
+
documentation, endpoints, registry configuration, tenant identifiers/bindings,
|
|
173
|
+
credentials, real telemetry, or copied external-repository files. Assets are
|
|
174
|
+
generated in isolation; tenant-neutral bindings alone are not a provenance check.
|
|
175
|
+
Raw checkout Fabric files are not added to the npm tarball.
|
|
176
|
+
|
|
177
|
+
For repository collaborators, `pnpm bundle:fabric` still creates
|
|
178
|
+
`release-artifacts/eventhouse-ai-observability-fabric-<version>.zip` without
|
|
179
|
+
overwriting an existing archive. Release/Actions ZIPs remain collaborator
|
|
180
|
+
channels, not public prerequisites.
|
|
181
|
+
|
|
182
|
+
After installing the SDK and configuring the Fabric route, set
|
|
183
|
+
`FABRIC_EVENTSTREAM_CONNECTION_STRING`, `FABRIC_KQL_QUERY_ENDPOINT`,
|
|
184
|
+
`FABRIC_KQL_DATABASE`, and `FABRIC_KQL_ACCESS_TOKEN` through your secret provider.
|
|
185
|
+
The producer needs source Send credentials; the query token needs separate
|
|
186
|
+
Kusto database read permission, not a Fabric management API token.
|
|
187
|
+
|
|
188
|
+
```sh
|
|
189
|
+
npx --no-install eventhouse-ai-observability-validate
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The installed CLI sends two metadata-only spans, reports producer acknowledgement,
|
|
193
|
+
polls Eventhouse, and verifies their trace and parent IDs. It makes no AI calls,
|
|
194
|
+
but writes real telemetry and can incur Fabric ingestion/query charges.
|
|
195
|
+
Use `--help` without credentials or network access. See
|
|
196
|
+
[validation configuration](docs/quickstart.md#live-fabric-validation).
|
|
197
|
+
|
|
104
198
|
## Installation from GitHub Packages
|
|
105
199
|
|
|
106
200
|
GitHub's npm registry requires authentication even for public packages. Your
|
|
@@ -129,7 +223,7 @@ This scope mapping does not change the registry for dependencies outside `@sagui
|
|
|
129
223
|
|
|
130
224
|
Run **Publish to GitHub Packages** from the repository's Actions tab on `main`,
|
|
131
225
|
or publish a GitHub Release whose tag matches the package version, such as
|
|
132
|
-
`v0.
|
|
226
|
+
`v0.2.0`. Update `package.json`, the instrumentation scope version in `src/engine.ts`,
|
|
133
227
|
and the basic example's dependency pin before releasing another version; published versions
|
|
134
228
|
cannot be overwritten. Prerelease versions use the `next` dist-tag instead of `latest`.
|
|
135
229
|
|
|
@@ -140,6 +234,16 @@ artifact with `--access public`, and checks its registry version. It uses the re
|
|
|
140
234
|
is needed for publishing. Repository/organization Actions policy must allow this
|
|
141
235
|
permission.
|
|
142
236
|
|
|
237
|
+
CI and both publication workflows also upload the matching Fabric ZIP as a
|
|
238
|
+
`fabric-setup` Actions artifact. The separate **Fabric setup assets** workflow
|
|
239
|
+
attaches it to published GitHub Releases after bundle tests pass and the release
|
|
240
|
+
tag matches the package version. Only its attachment job requests
|
|
241
|
+
`contents: write`; registry publication jobs retain read-only contents access.
|
|
242
|
+
Running that assets workflow manually on `main` builds a downloadable Actions
|
|
243
|
+
artifact without publishing a package or attaching anything to a release.
|
|
244
|
+
These private-repository assets require collaborator access; public consumers
|
|
245
|
+
obtain `fabric-setup.zip` from the installed npm package.
|
|
246
|
+
|
|
143
247
|
GitHub controls visibility separately from npm's access flag. Before the next
|
|
144
248
|
publication, open the existing package's **Package settings → Change visibility**
|
|
145
249
|
and select **Public**. This is a one-time, irreversible setting; all subsequent
|
|
@@ -148,36 +252,48 @@ the package is private or its visibility cannot be verified. New package names
|
|
|
148
252
|
must be bootstrapped and made public before using this workflow.
|
|
149
253
|
Public visibility still requires consumer authentication. See the [release notes](CHANGELOG.md).
|
|
150
254
|
|
|
151
|
-
##
|
|
255
|
+
## Publishing to npmjs
|
|
152
256
|
|
|
153
|
-
The separate **
|
|
257
|
+
The separate **Publish to npmjs** workflow runs manually on `main`. It uses
|
|
154
258
|
Node 24 and npm 12, validates the project, changes the registry only in its runner
|
|
155
|
-
checkout, packs, smoke-tests, and
|
|
259
|
+
checkout, packs, smoke-tests, and publishes the exact tested tarball.
|
|
260
|
+
It then verifies the published version against the public registry. The committed
|
|
156
261
|
GitHub Packages registry configuration and its publishing workflow are unchanged.
|
|
157
262
|
Packed metadata is checked against the selected publication settings.
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
`
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
263
|
+
OIDC works with this private source repository, but npm provenance attestations
|
|
264
|
+
require a public source repository and are not generated here.
|
|
265
|
+
Registry verification retries for up to five minutes while npm processes a
|
|
266
|
+
release. If publishing succeeded but verification failed, rerun with
|
|
267
|
+
**verify_only** enabled to check availability without publishing again.
|
|
268
|
+
|
|
269
|
+
Configure the npm package's **Settings > Trusted publishing** with:
|
|
270
|
+
|
|
271
|
+
| Field | Value |
|
|
272
|
+
| -------------------- | --------------------------- |
|
|
273
|
+
| Provider | GitHub Actions |
|
|
274
|
+
| Organization or user | `saguiitay` |
|
|
275
|
+
| Repository | `ai-observability` |
|
|
276
|
+
| Workflow filename | `publish-npmjs.yml` |
|
|
277
|
+
| Environment | Leave blank |
|
|
278
|
+
| Allowed actions | Enable direct `npm publish` |
|
|
279
|
+
|
|
280
|
+
The workflow grants `id-token: write` to its publishing job and does not use
|
|
281
|
+
`NPM_STAGING_TOKEN` or another stored npm credential. A new trusted publisher
|
|
282
|
+
must complete its first successful publication within two days. After that
|
|
283
|
+
publication succeeds, revoke the bootstrap staging token on npmjs and delete
|
|
284
|
+
the repository's `NPM_STAGING_TOKEN` secret. Enable npm's **Require two-factor
|
|
285
|
+
authentication and disallow tokens** publishing setting.
|
|
286
|
+
|
|
287
|
+
Update the release versions described above before running this workflow;
|
|
288
|
+
published versions cannot be overwritten. Running it publishes immediately,
|
|
289
|
+
without a separate npm approval. The first npmjs release was bootstrapped using
|
|
290
|
+
staged publishing and interactive 2FA approval. See
|
|
291
|
+
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
|
|
292
|
+
|
|
293
|
+
When installing from this source checkout, its `.npmrc` still maps `@saguiitay`
|
|
294
|
+
to GitHub Packages. Override that mapping in a consuming project to use npmjs
|
|
295
|
+
or your approved mirror instead; GitHub authentication is not needed for npmjs.
|
|
180
296
|
|
|
181
297
|
## Documentation
|
|
182
298
|
|
|
183
|
-
[Quickstart](docs/quickstart.md) · [Architecture](docs/architecture.md) · [Research](docs/research.md) · [Fabric setup](docs/fabric-setup.md) · [Transport](docs/eventstream-transport.md) · [Schema](docs/telemetry-schema.md) · [Copilot adapter](docs/copilot-adapter.md) · [Dashboards](docs/dashboards.md) · [Security](docs/security.md) · [Extending](docs/extending.md) · [Troubleshooting](docs/troubleshooting.md) · [Performance](docs/performance.md) · [Implementation report](docs/implementation-report.md).
|
|
299
|
+
[Quickstart](docs/quickstart.md) · [Architecture](docs/architecture.md) · [Research](docs/research.md) · [Fabric setup](docs/fabric-setup.md) · [Transport](docs/eventstream-transport.md) · [Schema](docs/telemetry-schema.md) · [Copilot adapter](docs/copilot-adapter.md) · [OpenAI adapter](docs/openai-adapter.md) · [Vercel AI adapter](docs/vercel-adapter.md) · [Dashboards](docs/dashboards.md) · [Security](docs/security.md) · [Extending](docs/extending.md) · [Troubleshooting](docs/troubleshooting.md) · [Performance](docs/performance.md) · [Implementation report](docs/implementation-report.md).
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type OpenAI from "openai";
|
|
2
|
+
import type { Observability } from "../engine.js";
|
|
3
|
+
export interface OpenAIAttachOptions {
|
|
4
|
+
/** Shared engines are externally owned by default. */
|
|
5
|
+
shutdownEngine?: boolean;
|
|
6
|
+
/** Maximum requests retained until consumption or observer shutdown. */
|
|
7
|
+
maxTrackedRequests?: number;
|
|
8
|
+
/** Text capture limit per input/output, when the engine allows content. */
|
|
9
|
+
maxContentChars?: number;
|
|
10
|
+
}
|
|
11
|
+
export interface OpenAIObserver<T extends OpenAI = OpenAI> {
|
|
12
|
+
readonly client: T;
|
|
13
|
+
flush(): Promise<void>;
|
|
14
|
+
shutdown(): Promise<void>;
|
|
15
|
+
getDiagnostics(): ReturnType<Observability["getDiagnostics"]> & {
|
|
16
|
+
trackedRequests: number;
|
|
17
|
+
requestsSkipped: number;
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
export declare function validateOpenAIAttachOptions(options: OpenAIAttachOptions): void;
|
|
21
|
+
/**
|
|
22
|
+
* Observe only direct Chat Completions/Responses create calls. The original SDK
|
|
23
|
+
* client, resources, promises, streams and application OTel globals are untouched.
|
|
24
|
+
*/
|
|
25
|
+
export declare function attachOpenAI<T extends OpenAI>(client: T, engine: Observability, options?: OpenAIAttachOptions): OpenAIObserver<T>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { type Tracer } from "@opentelemetry/api";
|
|
2
|
+
import type { TelemetryOptions, Telemetry } from "ai";
|
|
3
|
+
import { type Observability } from "../engine.js";
|
|
4
|
+
export type VercelTelemetrySettings = TelemetryOptions;
|
|
5
|
+
export interface VercelAdapterOptions {
|
|
6
|
+
/** Supply the SDK's native integration: tracer => new OpenTelemetry({ tracer }). */
|
|
7
|
+
integration: (tracer: Tracer) => Telemetry;
|
|
8
|
+
/** Also requires captureContent on the engine. Defaults to false. */
|
|
9
|
+
recordInputs?: boolean;
|
|
10
|
+
/** Also requires captureContent on the engine. Defaults to false. */
|
|
11
|
+
recordOutputs?: boolean;
|
|
12
|
+
/** Explicitly transfers engine shutdown ownership. Defaults to false. */
|
|
13
|
+
shutdownEngine?: boolean;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Native SDK instrumentation calls this tracer, not a global provider. Every
|
|
17
|
+
* mutation is filtered before reaching the private engine, including errors
|
|
18
|
+
* and attributes that the SDK's recording flags do not protect.
|
|
19
|
+
*/
|
|
20
|
+
export declare function attachVercelAI(engine: Observability, options: VercelAdapterOptions): {
|
|
21
|
+
telemetry: VercelTelemetrySettings;
|
|
22
|
+
flush: () => Promise<void>;
|
|
23
|
+
getDiagnostics: () => Readonly<import("../engine.js").Diagnostics>;
|
|
24
|
+
shutdown(): Promise<void>;
|
|
25
|
+
};
|
|
@@ -480,7 +480,7 @@ function createEngine(options) {
|
|
|
480
480
|
});
|
|
481
481
|
const tracer = provider.getTracer(
|
|
482
482
|
"@saguiitay/eventhouse-ai-observability",
|
|
483
|
-
"0.
|
|
483
|
+
"0.2.0"
|
|
484
484
|
);
|
|
485
485
|
const localContext = new AsyncLocalStorage();
|
|
486
486
|
const active = /* @__PURE__ */ new Set();
|
|
@@ -844,8 +844,6 @@ var EventstreamExporter = class {
|
|
|
844
844
|
};
|
|
845
845
|
|
|
846
846
|
// src/index.ts
|
|
847
|
-
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
|
|
848
|
-
import { OTLPTraceExporter as OTLPTraceExporter2 } from "@opentelemetry/exporter-trace-otlp-http";
|
|
849
847
|
function envNumber(name) {
|
|
850
848
|
const raw = process.env[name];
|
|
851
849
|
if (raw === void 0) return void 0;
|
|
@@ -854,33 +852,20 @@ function envNumber(name) {
|
|
|
854
852
|
}
|
|
855
853
|
return Number(raw);
|
|
856
854
|
}
|
|
857
|
-
function envHeaders() {
|
|
858
|
-
const raw = process.env.OTEL_EXPORTER_OTLP_TRACES_HEADERS ?? process.env.OTEL_EXPORTER_OTLP_HEADERS;
|
|
859
|
-
if (!raw) return void 0;
|
|
860
|
-
const result = {};
|
|
861
|
-
for (const entry of raw.split(",")) {
|
|
862
|
-
const equals = entry.indexOf("=");
|
|
863
|
-
if (equals < 1)
|
|
864
|
-
throw new Error("Invalid OTLP header environment configuration");
|
|
865
|
-
try {
|
|
866
|
-
result[entry.slice(0, equals).trim()] = decodeURIComponent(
|
|
867
|
-
entry.slice(equals + 1).trim()
|
|
868
|
-
);
|
|
869
|
-
} catch {
|
|
870
|
-
throw new Error("Invalid OTLP header environment configuration");
|
|
871
|
-
}
|
|
872
|
-
}
|
|
873
|
-
return result;
|
|
874
|
-
}
|
|
875
855
|
function createObservability(options = {}) {
|
|
856
|
+
if ("transport" in options || "endpoint" in options || "headers" in options)
|
|
857
|
+
throw new Error(
|
|
858
|
+
"Configure custom transports with exporter; transport, endpoint, and headers options are not supported."
|
|
859
|
+
);
|
|
876
860
|
const connectionString = options.connectionString ?? process.env.FABRIC_EVENTSTREAM_CONNECTION_STRING;
|
|
877
|
-
const selection = options.transport ?? (connectionString ? "eventstream" : "otlp");
|
|
878
861
|
let exporter;
|
|
879
862
|
if (options.exporter) {
|
|
880
863
|
exporter = options.exporter;
|
|
881
|
-
} else
|
|
864
|
+
} else {
|
|
882
865
|
if (!connectionString)
|
|
883
|
-
throw new Error(
|
|
866
|
+
throw new Error(
|
|
867
|
+
"Supply a Fabric Eventstream connectionString or a custom SpanExporter."
|
|
868
|
+
);
|
|
884
869
|
const entityName = options.entityName ?? process.env.FABRIC_EVENTSTREAM_ENTITY_NAME;
|
|
885
870
|
exporter = new EventstreamExporter({
|
|
886
871
|
connectionString,
|
|
@@ -890,32 +875,6 @@ function createObservability(options = {}) {
|
|
|
890
875
|
...options.shutdownTimeoutMs !== void 0 ? { shutdownTimeoutMs: options.shutdownTimeoutMs } : {},
|
|
891
876
|
...options.maxConcurrentExports !== void 0 ? { maxConcurrentExports: options.maxConcurrentExports } : {}
|
|
892
877
|
});
|
|
893
|
-
} else if (selection === "otlp") {
|
|
894
|
-
const base = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
|
|
895
|
-
const endpoint = options.endpoint ?? process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? (base ? `${base.replace(/\/$/, "")}/v1/traces` : void 0);
|
|
896
|
-
if (!endpoint)
|
|
897
|
-
throw new Error(
|
|
898
|
-
"Supply a Fabric connection string or an explicit OTLP traces endpoint"
|
|
899
|
-
);
|
|
900
|
-
const headers = options.headers ?? envHeaders();
|
|
901
|
-
try {
|
|
902
|
-
const url = new URL(endpoint);
|
|
903
|
-
if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
|
|
904
|
-
throw new Error();
|
|
905
|
-
} catch {
|
|
906
|
-
throw new Error("Invalid OTLP endpoint configuration.");
|
|
907
|
-
}
|
|
908
|
-
for (const [name, value] of Object.entries(headers ?? {})) {
|
|
909
|
-
if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name) || /[\r\n\0]/u.test(value)) {
|
|
910
|
-
throw new Error("Invalid OTLP headers configuration.");
|
|
911
|
-
}
|
|
912
|
-
}
|
|
913
|
-
exporter = new OTLPTraceExporter({
|
|
914
|
-
url: endpoint,
|
|
915
|
-
...headers ? { headers } : {}
|
|
916
|
-
});
|
|
917
|
-
} else {
|
|
918
|
-
throw new Error("Unsupported telemetry transport");
|
|
919
878
|
}
|
|
920
879
|
const serviceName = options.serviceName ?? process.env.OTEL_SERVICE_NAME;
|
|
921
880
|
const serviceVersion = options.serviceVersion ?? process.env.OTEL_SERVICE_VERSION;
|
|
@@ -937,10 +896,7 @@ function createObservability(options = {}) {
|
|
|
937
896
|
|
|
938
897
|
export {
|
|
939
898
|
redactSecrets,
|
|
940
|
-
createEngine,
|
|
941
|
-
serializeSpan,
|
|
942
899
|
EventstreamExporter,
|
|
943
|
-
createObservability
|
|
944
|
-
OTLPTraceExporter2 as OTLPTraceExporter
|
|
900
|
+
createObservability
|
|
945
901
|
};
|
|
946
|
-
//# sourceMappingURL=chunk-
|
|
902
|
+
//# sourceMappingURL=chunk-XGCHW72B.js.map
|