@raindrop-ai/eve 0.0.22 → 0.0.24
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/README.md +22 -0
- package/dist/index.d.mts +154 -2
- package/dist/index.d.ts +154 -2
- package/dist/index.js +1042 -348
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1042 -349
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -303,3 +303,25 @@ Raindrop UI and Workshop with full nesting + AI SDK attributes.
|
|
|
303
303
|
|
|
304
304
|
- [`examples/eve-basic`](../../examples/eve-basic) — single-agent example with one tool (`get_weather`) and an end-to-end dashboard verifier.
|
|
305
305
|
- [`examples/eve-subagents`](../../examples/eve-subagents) — parent agent dispatching `weatherResearcher` + `attractionsFinder` sub-agents, verifying cross-sandbox nesting against the production dashboard.
|
|
306
|
+
|
|
307
|
+
## Application Git identity
|
|
308
|
+
|
|
309
|
+
Set `appGit` on `defineRaindropInstrumentation` (or `RaindropEveSpanExporter`) to override `commitSha`, `commitDirty`, and optional ordinary `branch`, or pass `false` to opt out. The revision is unknown by default because ambient deploy/CI and observer working-directory metadata are ignored. Local discovery requires an explicit `sourceDirectory` (or `RAINDROP_GIT_SOURCE_DIRECTORY`); explicit `RAINDROP_COMMIT_SHA` values are honored. Automatic branch discovery requires `detectBranch: true`. Eve's event feed and independent OTLP exporter share one application Git context.
|
|
310
|
+
|
|
311
|
+
For advanced direct exporter wiring, install the start processor to freeze automatic metadata when each span begins. Keep `"auto"` to preserve Vercel's default processors; `traceExporter` retains its normal batch exporter:
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
import { registerOTel } from "@vercel/otel";
|
|
315
|
+
import { RaindropEveSpanExporter, createEveAppGitSpanProcessor } from "@raindrop-ai/eve";
|
|
316
|
+
|
|
317
|
+
const exporter = new RaindropEveSpanExporter({
|
|
318
|
+
writeKey: process.env.RAINDROP_WRITE_KEY,
|
|
319
|
+
appGit: { sourceDirectory: "/path/to/application" },
|
|
320
|
+
});
|
|
321
|
+
registerOTel({
|
|
322
|
+
traceExporter: exporter,
|
|
323
|
+
spanProcessors: ["auto", createEveAppGitSpanProcessor(exporter)],
|
|
324
|
+
});
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Without this processor, direct exporters attach only explicit client, environment, operation, or span values. Automatic discovery never fills in metadata for a span whose start was not observed. `defineRaindropInstrumentation` installs the processor automatically.
|
package/dist/index.d.mts
CHANGED
|
@@ -1,6 +1,141 @@
|
|
|
1
1
|
import * as _vercel_otel from '@vercel/otel';
|
|
2
2
|
import { RaindropAISDKClient } from '@raindrop-ai/ai-sdk';
|
|
3
3
|
|
|
4
|
+
/** Kept structural so public integration declarations do not depend on private schemas. */
|
|
5
|
+
type AppGitOptions = {
|
|
6
|
+
commitSha?: string | null;
|
|
7
|
+
commitDirty?: boolean | null;
|
|
8
|
+
branch?: string | null;
|
|
9
|
+
detectBranch?: boolean;
|
|
10
|
+
sourceDirectory?: string;
|
|
11
|
+
autoDetect?: boolean;
|
|
12
|
+
};
|
|
13
|
+
type AppGitSnapshot = Readonly<Record<string, unknown>>;
|
|
14
|
+
type AppGitEnvironment = Readonly<Record<string, string | undefined>>;
|
|
15
|
+
type AppGitLocalResult = {
|
|
16
|
+
commitSha?: string;
|
|
17
|
+
commitDirty?: boolean;
|
|
18
|
+
branch?: string;
|
|
19
|
+
};
|
|
20
|
+
type AppGitOperationOwner = string;
|
|
21
|
+
type AppGitLocalResolver = (sourceDirectory: string | undefined, detectBranch: boolean, completed: (result: AppGitLocalResult) => void) => () => void;
|
|
22
|
+
/** One client owns its defaults; operation snapshots never wait for discovery. */
|
|
23
|
+
declare class AppGitContextImpl {
|
|
24
|
+
private defaults;
|
|
25
|
+
private explicit;
|
|
26
|
+
private explicitKeys;
|
|
27
|
+
private cancel;
|
|
28
|
+
private disposed;
|
|
29
|
+
private operations;
|
|
30
|
+
private operationOverflow;
|
|
31
|
+
private detectBranch;
|
|
32
|
+
private replayBranch;
|
|
33
|
+
private disabled;
|
|
34
|
+
constructor(options: AppGitOptions | false | undefined, runtime?: {
|
|
35
|
+
allowLocalGit?: boolean;
|
|
36
|
+
resolveLocal?: AppGitLocalResolver;
|
|
37
|
+
env?: AppGitEnvironment;
|
|
38
|
+
captureLegacyReplayBranch?: boolean;
|
|
39
|
+
allowDiscovery?: boolean;
|
|
40
|
+
});
|
|
41
|
+
private accept;
|
|
42
|
+
snapshot(properties?: Readonly<Record<string, unknown>>): AppGitSnapshot;
|
|
43
|
+
/** Safe defaults when no operation/span start was observed; never infer identity. */
|
|
44
|
+
snapshotExplicit(properties?: Readonly<Record<string, unknown>>, eventId?: string): AppGitSnapshot;
|
|
45
|
+
/** Existing replay branch reporting stays separate from opt-in event properties. */
|
|
46
|
+
snapshotForReplay(): AppGitSnapshot;
|
|
47
|
+
/** Merge a frozen span snapshot without losing client-authored provenance. */
|
|
48
|
+
mergeSnapshot(base: AppGitSnapshot, properties?: Readonly<Record<string, unknown>>, explicitKeys?: ReadonlySet<string>): AppGitSnapshot;
|
|
49
|
+
/** Shippers belonging to one client share this bounded operation registry. */
|
|
50
|
+
forOperation(eventId: string | undefined, properties?: Readonly<Record<string, unknown>>, owner?: AppGitOperationOwner): AppGitSnapshot;
|
|
51
|
+
releaseOperation(eventId: string, owner: AppGitOperationOwner): void;
|
|
52
|
+
finishOperation(eventId: string): void;
|
|
53
|
+
dispose(): void;
|
|
54
|
+
}
|
|
55
|
+
/** Structural at package boundaries: public SDK bundles contain independent copies of core. */
|
|
56
|
+
type AppGitContext = Pick<AppGitContextImpl, "snapshot" | "snapshotForReplay" | "forOperation" | "finishOperation" | "dispose"> & {
|
|
57
|
+
snapshotExplicit?: AppGitContextImpl["snapshotExplicit"];
|
|
58
|
+
mergeSnapshot?: AppGitContextImpl["mergeSnapshot"];
|
|
59
|
+
releaseOperation?: (eventId: string, owner: AppGitOperationOwner) => void;
|
|
60
|
+
};
|
|
61
|
+
declare const AppGitContext: typeof AppGitContextImpl;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Run telemetry egress with OpenTelemetry tracing suppressed.
|
|
65
|
+
*
|
|
66
|
+
* Why this exists
|
|
67
|
+
* ---------------
|
|
68
|
+
* Raindrop integrations ship spans/events over HTTP with the global `fetch`
|
|
69
|
+
* (see {@link ../http.ts `postJson`}). When the host app also runs an OTel
|
|
70
|
+
* fetch/undici instrumentation — e.g. `@vercel/otel`'s `registerOTel`, which
|
|
71
|
+
* every Eve agent installs — that instrumentation wraps *our own* telemetry
|
|
72
|
+
* POSTs in a `fetch POST <endpoint>` span. Those spans are then handed to the
|
|
73
|
+
* very exporter that issued the request, so they get shipped right back to
|
|
74
|
+
* Raindrop and Workshop as standalone "runs" (and, because each export issues
|
|
75
|
+
* another fetch, they feed back on themselves). The result is a run list
|
|
76
|
+
* flooded with `fetch POST .../v1/traces`, `.../events/track_partial` and
|
|
77
|
+
* `.../live` entries that drown out the real agent turns — especially with
|
|
78
|
+
* sub-agents, where every sandbox runs its own instrumentation.
|
|
79
|
+
*
|
|
80
|
+
* The OTel-blessed fix is to mark the active context as "tracing suppressed"
|
|
81
|
+
* around the request; instrumentations check `isTracingSuppressed` and return
|
|
82
|
+
* a no-op span instead of recording one. We do this through a hook stashed on
|
|
83
|
+
* `globalThis` by the Node entrypoint ({@link ../index.node.ts}) so that:
|
|
84
|
+
* - `@opentelemetry/api` / `@opentelemetry/core` stay *optional* — core never
|
|
85
|
+
* hard-depends on them, and the hook is simply absent when they (and thus
|
|
86
|
+
* any instrumentation to suppress) are not installed; and
|
|
87
|
+
* - the browser bundle never pulls in `node:module`, mirroring how core
|
|
88
|
+
* injects `AsyncLocalStorage` via `RAINDROP_ASYNC_LOCAL_STORAGE`.
|
|
89
|
+
*
|
|
90
|
+
* When no hook is present the callback runs unchanged, so suppression is a
|
|
91
|
+
* best-effort no-op rather than a hard requirement.
|
|
92
|
+
*/
|
|
93
|
+
/** Hook signature: run `fn` with OTel tracing suppressed, returning its value. */
|
|
94
|
+
type SuppressTracingHook = <T>(fn: () => T) => T;
|
|
95
|
+
declare global {
|
|
96
|
+
var RAINDROP_SUPPRESS_TRACING: SuppressTracingHook | undefined;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
type ParentSpanContext = {
|
|
100
|
+
traceIdB64: string;
|
|
101
|
+
spanIdB64: string;
|
|
102
|
+
eventId: string;
|
|
103
|
+
};
|
|
104
|
+
interface ContextSpan {
|
|
105
|
+
readonly traceIdB64: string;
|
|
106
|
+
readonly spanIdB64: string;
|
|
107
|
+
readonly eventId: string;
|
|
108
|
+
log?(data: Record<string, unknown>): void;
|
|
109
|
+
}
|
|
110
|
+
interface AsyncLocalStorageLike<T> {
|
|
111
|
+
getStore(): T | undefined;
|
|
112
|
+
run<R>(store: T, callback: () => R): R;
|
|
113
|
+
enterWith?(store: T): void;
|
|
114
|
+
}
|
|
115
|
+
declare abstract class ContextManager {
|
|
116
|
+
abstract getParentSpanIds(): ParentSpanContext | undefined;
|
|
117
|
+
abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
|
|
118
|
+
abstract getCurrentSpan(): ContextSpan | undefined;
|
|
119
|
+
abstract isReady(): boolean;
|
|
120
|
+
}
|
|
121
|
+
declare global {
|
|
122
|
+
var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
|
|
123
|
+
var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* RaindropEveSpanExporter — a tiny OTel SpanExporter that:
|
|
128
|
+
*
|
|
129
|
+
* 1. Ships OTLP/HTTP JSON traces to Raindrop (`<endpoint>/traces`) using a
|
|
130
|
+
* Bearer write key, and
|
|
131
|
+
* 2. Mirrors the same export to a local Workshop daemon when one is
|
|
132
|
+
* reachable (explicit URL, env vars, or auto-detect during development).
|
|
133
|
+
*
|
|
134
|
+
* It deliberately does NOT depend on the OpenTelemetry SDK at runtime beyond
|
|
135
|
+
* the structural `ReadableSpan` / `SpanExporter` shapes — those are typed via
|
|
136
|
+
* peer dependencies so consumers don't pay a second copy of `@opentelemetry/*`.
|
|
137
|
+
*/
|
|
138
|
+
|
|
4
139
|
type HrTime = [number, number];
|
|
5
140
|
type AttributeValue = string | number | boolean | Array<string | number | boolean | null | undefined> | null | undefined;
|
|
6
141
|
interface Attributes {
|
|
@@ -36,11 +171,19 @@ interface ReadableSpan {
|
|
|
36
171
|
readonly parentSpanId?: string;
|
|
37
172
|
readonly parentSpanContext?: SpanContext;
|
|
38
173
|
}
|
|
174
|
+
interface EveAppGitSpanProcessor {
|
|
175
|
+
onStart(span: ReadableSpan, parentContext?: unknown): void;
|
|
176
|
+
onEnd(span: ReadableSpan): void;
|
|
177
|
+
forceFlush(): Promise<void>;
|
|
178
|
+
shutdown(): Promise<void>;
|
|
179
|
+
}
|
|
39
180
|
interface ExportResult {
|
|
40
181
|
code: number;
|
|
41
182
|
error?: Error;
|
|
42
183
|
}
|
|
43
184
|
interface RaindropEveExporterOptions {
|
|
185
|
+
/** Application Git identity. Local discovery requires an explicit sourceDirectory; false disables enrichment. */
|
|
186
|
+
appGit?: AppGitOptions | false;
|
|
44
187
|
/**
|
|
45
188
|
* Raindrop write key. Required to ship to Raindrop's hosted endpoint; when
|
|
46
189
|
* omitted, the exporter still mirrors to Workshop (when one is reachable).
|
|
@@ -98,12 +241,18 @@ declare class RaindropEveSpanExporter {
|
|
|
98
241
|
private readonly debug;
|
|
99
242
|
private readonly prefix;
|
|
100
243
|
private readonly maxTextFieldChars;
|
|
244
|
+
private readonly appGitContext;
|
|
245
|
+
private readonly startedAppGitSpans;
|
|
246
|
+
private readonly activeAppGitEvents;
|
|
247
|
+
private readonly appGitOwner;
|
|
101
248
|
private inFlight;
|
|
102
249
|
private shuttingDown;
|
|
103
250
|
private auxShutdowns;
|
|
104
|
-
constructor(opts?: RaindropEveExporterOptions);
|
|
251
|
+
constructor(opts?: RaindropEveExporterOptions, appGitContext?: AppGitContext);
|
|
105
252
|
/** True when we have at least one destination (Raindrop or Workshop). */
|
|
106
253
|
hasDestinations(): boolean;
|
|
254
|
+
captureSpanStart(span: ReadableSpan): void;
|
|
255
|
+
private releaseStartedAppGitSpan;
|
|
107
256
|
/**
|
|
108
257
|
* Update the OTLP `service.name` attribute. Called by Eve's
|
|
109
258
|
* `setup({ agentName })` so the resource attribute reflects the actual
|
|
@@ -122,6 +271,7 @@ declare class RaindropEveSpanExporter {
|
|
|
122
271
|
*/
|
|
123
272
|
attachAuxShutdown(fn: () => Promise<void>): void;
|
|
124
273
|
}
|
|
274
|
+
declare function createEveAppGitSpanProcessor(exporter: RaindropEveSpanExporter): EveAppGitSpanProcessor;
|
|
125
275
|
|
|
126
276
|
declare const RAINDROP_EVE_SDK_NAME: string;
|
|
127
277
|
declare const RAINDROP_EVE_SDK_VERSION: string;
|
|
@@ -240,6 +390,8 @@ interface RaindropEveInstrumentationEventsConfig {
|
|
|
240
390
|
* Options for {@link defineRaindropInstrumentation}.
|
|
241
391
|
*/
|
|
242
392
|
interface RaindropEveInstrumentationOptions {
|
|
393
|
+
/** Application Git identity. Local discovery requires an explicit sourceDirectory; false disables enrichment. */
|
|
394
|
+
appGit?: AppGitOptions | false;
|
|
243
395
|
/**
|
|
244
396
|
* `registerOTel` from `@vercel/otel`. Pass the function directly so the
|
|
245
397
|
* SDK doesn't have to dynamically import a peer dep at runtime.
|
|
@@ -452,4 +604,4 @@ interface RaindropInstrumentationDefinition {
|
|
|
452
604
|
*/
|
|
453
605
|
declare function defineRaindropInstrumentation(opts?: RaindropEveInstrumentationOptions): RaindropInstrumentationDefinition;
|
|
454
606
|
|
|
455
|
-
export { RAINDROP_EVE_SDK_NAME, RAINDROP_EVE_SDK_VERSION, type RaindropEveExporterOptions, type RaindropEveInstrumentationChannel, type RaindropEveInstrumentationEventsConfig, type RaindropEveInstrumentationMetadata, type RaindropEveInstrumentationMetadataConfig, type RaindropEveInstrumentationModelInput, type RaindropEveInstrumentationOptions, type RaindropEveInstrumentationSession, type RaindropEveInstrumentationStep, type RaindropEveInstrumentationTurn, RaindropEveSpanExporter, type RaindropEveStepStartedEventInput, type RaindropEveStepStartedEventResult, type RaindropEveStepStartedMetadataInput, type RaindropInstrumentationDefinition, type RegisterOTelFn, _resetCanonicalTurnIds, defineRaindropInstrumentation as default, defineRaindropInstrumentation };
|
|
607
|
+
export { RAINDROP_EVE_SDK_NAME, RAINDROP_EVE_SDK_VERSION, type RaindropEveExporterOptions, type RaindropEveInstrumentationChannel, type RaindropEveInstrumentationEventsConfig, type RaindropEveInstrumentationMetadata, type RaindropEveInstrumentationMetadataConfig, type RaindropEveInstrumentationModelInput, type RaindropEveInstrumentationOptions, type RaindropEveInstrumentationSession, type RaindropEveInstrumentationStep, type RaindropEveInstrumentationTurn, RaindropEveSpanExporter, type RaindropEveStepStartedEventInput, type RaindropEveStepStartedEventResult, type RaindropEveStepStartedMetadataInput, type RaindropInstrumentationDefinition, type RegisterOTelFn, _resetCanonicalTurnIds, createEveAppGitSpanProcessor, defineRaindropInstrumentation as default, defineRaindropInstrumentation };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,141 @@
|
|
|
1
1
|
import * as _vercel_otel from '@vercel/otel';
|
|
2
2
|
import { RaindropAISDKClient } from '@raindrop-ai/ai-sdk';
|
|
3
3
|
|
|
4
|
+
/** Kept structural so public integration declarations do not depend on private schemas. */
|
|
5
|
+
type AppGitOptions = {
|
|
6
|
+
commitSha?: string | null;
|
|
7
|
+
commitDirty?: boolean | null;
|
|
8
|
+
branch?: string | null;
|
|
9
|
+
detectBranch?: boolean;
|
|
10
|
+
sourceDirectory?: string;
|
|
11
|
+
autoDetect?: boolean;
|
|
12
|
+
};
|
|
13
|
+
type AppGitSnapshot = Readonly<Record<string, unknown>>;
|
|
14
|
+
type AppGitEnvironment = Readonly<Record<string, string | undefined>>;
|
|
15
|
+
type AppGitLocalResult = {
|
|
16
|
+
commitSha?: string;
|
|
17
|
+
commitDirty?: boolean;
|
|
18
|
+
branch?: string;
|
|
19
|
+
};
|
|
20
|
+
type AppGitOperationOwner = string;
|
|
21
|
+
type AppGitLocalResolver = (sourceDirectory: string | undefined, detectBranch: boolean, completed: (result: AppGitLocalResult) => void) => () => void;
|
|
22
|
+
/** One client owns its defaults; operation snapshots never wait for discovery. */
|
|
23
|
+
declare class AppGitContextImpl {
|
|
24
|
+
private defaults;
|
|
25
|
+
private explicit;
|
|
26
|
+
private explicitKeys;
|
|
27
|
+
private cancel;
|
|
28
|
+
private disposed;
|
|
29
|
+
private operations;
|
|
30
|
+
private operationOverflow;
|
|
31
|
+
private detectBranch;
|
|
32
|
+
private replayBranch;
|
|
33
|
+
private disabled;
|
|
34
|
+
constructor(options: AppGitOptions | false | undefined, runtime?: {
|
|
35
|
+
allowLocalGit?: boolean;
|
|
36
|
+
resolveLocal?: AppGitLocalResolver;
|
|
37
|
+
env?: AppGitEnvironment;
|
|
38
|
+
captureLegacyReplayBranch?: boolean;
|
|
39
|
+
allowDiscovery?: boolean;
|
|
40
|
+
});
|
|
41
|
+
private accept;
|
|
42
|
+
snapshot(properties?: Readonly<Record<string, unknown>>): AppGitSnapshot;
|
|
43
|
+
/** Safe defaults when no operation/span start was observed; never infer identity. */
|
|
44
|
+
snapshotExplicit(properties?: Readonly<Record<string, unknown>>, eventId?: string): AppGitSnapshot;
|
|
45
|
+
/** Existing replay branch reporting stays separate from opt-in event properties. */
|
|
46
|
+
snapshotForReplay(): AppGitSnapshot;
|
|
47
|
+
/** Merge a frozen span snapshot without losing client-authored provenance. */
|
|
48
|
+
mergeSnapshot(base: AppGitSnapshot, properties?: Readonly<Record<string, unknown>>, explicitKeys?: ReadonlySet<string>): AppGitSnapshot;
|
|
49
|
+
/** Shippers belonging to one client share this bounded operation registry. */
|
|
50
|
+
forOperation(eventId: string | undefined, properties?: Readonly<Record<string, unknown>>, owner?: AppGitOperationOwner): AppGitSnapshot;
|
|
51
|
+
releaseOperation(eventId: string, owner: AppGitOperationOwner): void;
|
|
52
|
+
finishOperation(eventId: string): void;
|
|
53
|
+
dispose(): void;
|
|
54
|
+
}
|
|
55
|
+
/** Structural at package boundaries: public SDK bundles contain independent copies of core. */
|
|
56
|
+
type AppGitContext = Pick<AppGitContextImpl, "snapshot" | "snapshotForReplay" | "forOperation" | "finishOperation" | "dispose"> & {
|
|
57
|
+
snapshotExplicit?: AppGitContextImpl["snapshotExplicit"];
|
|
58
|
+
mergeSnapshot?: AppGitContextImpl["mergeSnapshot"];
|
|
59
|
+
releaseOperation?: (eventId: string, owner: AppGitOperationOwner) => void;
|
|
60
|
+
};
|
|
61
|
+
declare const AppGitContext: typeof AppGitContextImpl;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Run telemetry egress with OpenTelemetry tracing suppressed.
|
|
65
|
+
*
|
|
66
|
+
* Why this exists
|
|
67
|
+
* ---------------
|
|
68
|
+
* Raindrop integrations ship spans/events over HTTP with the global `fetch`
|
|
69
|
+
* (see {@link ../http.ts `postJson`}). When the host app also runs an OTel
|
|
70
|
+
* fetch/undici instrumentation — e.g. `@vercel/otel`'s `registerOTel`, which
|
|
71
|
+
* every Eve agent installs — that instrumentation wraps *our own* telemetry
|
|
72
|
+
* POSTs in a `fetch POST <endpoint>` span. Those spans are then handed to the
|
|
73
|
+
* very exporter that issued the request, so they get shipped right back to
|
|
74
|
+
* Raindrop and Workshop as standalone "runs" (and, because each export issues
|
|
75
|
+
* another fetch, they feed back on themselves). The result is a run list
|
|
76
|
+
* flooded with `fetch POST .../v1/traces`, `.../events/track_partial` and
|
|
77
|
+
* `.../live` entries that drown out the real agent turns — especially with
|
|
78
|
+
* sub-agents, where every sandbox runs its own instrumentation.
|
|
79
|
+
*
|
|
80
|
+
* The OTel-blessed fix is to mark the active context as "tracing suppressed"
|
|
81
|
+
* around the request; instrumentations check `isTracingSuppressed` and return
|
|
82
|
+
* a no-op span instead of recording one. We do this through a hook stashed on
|
|
83
|
+
* `globalThis` by the Node entrypoint ({@link ../index.node.ts}) so that:
|
|
84
|
+
* - `@opentelemetry/api` / `@opentelemetry/core` stay *optional* — core never
|
|
85
|
+
* hard-depends on them, and the hook is simply absent when they (and thus
|
|
86
|
+
* any instrumentation to suppress) are not installed; and
|
|
87
|
+
* - the browser bundle never pulls in `node:module`, mirroring how core
|
|
88
|
+
* injects `AsyncLocalStorage` via `RAINDROP_ASYNC_LOCAL_STORAGE`.
|
|
89
|
+
*
|
|
90
|
+
* When no hook is present the callback runs unchanged, so suppression is a
|
|
91
|
+
* best-effort no-op rather than a hard requirement.
|
|
92
|
+
*/
|
|
93
|
+
/** Hook signature: run `fn` with OTel tracing suppressed, returning its value. */
|
|
94
|
+
type SuppressTracingHook = <T>(fn: () => T) => T;
|
|
95
|
+
declare global {
|
|
96
|
+
var RAINDROP_SUPPRESS_TRACING: SuppressTracingHook | undefined;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
type ParentSpanContext = {
|
|
100
|
+
traceIdB64: string;
|
|
101
|
+
spanIdB64: string;
|
|
102
|
+
eventId: string;
|
|
103
|
+
};
|
|
104
|
+
interface ContextSpan {
|
|
105
|
+
readonly traceIdB64: string;
|
|
106
|
+
readonly spanIdB64: string;
|
|
107
|
+
readonly eventId: string;
|
|
108
|
+
log?(data: Record<string, unknown>): void;
|
|
109
|
+
}
|
|
110
|
+
interface AsyncLocalStorageLike<T> {
|
|
111
|
+
getStore(): T | undefined;
|
|
112
|
+
run<R>(store: T, callback: () => R): R;
|
|
113
|
+
enterWith?(store: T): void;
|
|
114
|
+
}
|
|
115
|
+
declare abstract class ContextManager {
|
|
116
|
+
abstract getParentSpanIds(): ParentSpanContext | undefined;
|
|
117
|
+
abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
|
|
118
|
+
abstract getCurrentSpan(): ContextSpan | undefined;
|
|
119
|
+
abstract isReady(): boolean;
|
|
120
|
+
}
|
|
121
|
+
declare global {
|
|
122
|
+
var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
|
|
123
|
+
var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* RaindropEveSpanExporter — a tiny OTel SpanExporter that:
|
|
128
|
+
*
|
|
129
|
+
* 1. Ships OTLP/HTTP JSON traces to Raindrop (`<endpoint>/traces`) using a
|
|
130
|
+
* Bearer write key, and
|
|
131
|
+
* 2. Mirrors the same export to a local Workshop daemon when one is
|
|
132
|
+
* reachable (explicit URL, env vars, or auto-detect during development).
|
|
133
|
+
*
|
|
134
|
+
* It deliberately does NOT depend on the OpenTelemetry SDK at runtime beyond
|
|
135
|
+
* the structural `ReadableSpan` / `SpanExporter` shapes — those are typed via
|
|
136
|
+
* peer dependencies so consumers don't pay a second copy of `@opentelemetry/*`.
|
|
137
|
+
*/
|
|
138
|
+
|
|
4
139
|
type HrTime = [number, number];
|
|
5
140
|
type AttributeValue = string | number | boolean | Array<string | number | boolean | null | undefined> | null | undefined;
|
|
6
141
|
interface Attributes {
|
|
@@ -36,11 +171,19 @@ interface ReadableSpan {
|
|
|
36
171
|
readonly parentSpanId?: string;
|
|
37
172
|
readonly parentSpanContext?: SpanContext;
|
|
38
173
|
}
|
|
174
|
+
interface EveAppGitSpanProcessor {
|
|
175
|
+
onStart(span: ReadableSpan, parentContext?: unknown): void;
|
|
176
|
+
onEnd(span: ReadableSpan): void;
|
|
177
|
+
forceFlush(): Promise<void>;
|
|
178
|
+
shutdown(): Promise<void>;
|
|
179
|
+
}
|
|
39
180
|
interface ExportResult {
|
|
40
181
|
code: number;
|
|
41
182
|
error?: Error;
|
|
42
183
|
}
|
|
43
184
|
interface RaindropEveExporterOptions {
|
|
185
|
+
/** Application Git identity. Local discovery requires an explicit sourceDirectory; false disables enrichment. */
|
|
186
|
+
appGit?: AppGitOptions | false;
|
|
44
187
|
/**
|
|
45
188
|
* Raindrop write key. Required to ship to Raindrop's hosted endpoint; when
|
|
46
189
|
* omitted, the exporter still mirrors to Workshop (when one is reachable).
|
|
@@ -98,12 +241,18 @@ declare class RaindropEveSpanExporter {
|
|
|
98
241
|
private readonly debug;
|
|
99
242
|
private readonly prefix;
|
|
100
243
|
private readonly maxTextFieldChars;
|
|
244
|
+
private readonly appGitContext;
|
|
245
|
+
private readonly startedAppGitSpans;
|
|
246
|
+
private readonly activeAppGitEvents;
|
|
247
|
+
private readonly appGitOwner;
|
|
101
248
|
private inFlight;
|
|
102
249
|
private shuttingDown;
|
|
103
250
|
private auxShutdowns;
|
|
104
|
-
constructor(opts?: RaindropEveExporterOptions);
|
|
251
|
+
constructor(opts?: RaindropEveExporterOptions, appGitContext?: AppGitContext);
|
|
105
252
|
/** True when we have at least one destination (Raindrop or Workshop). */
|
|
106
253
|
hasDestinations(): boolean;
|
|
254
|
+
captureSpanStart(span: ReadableSpan): void;
|
|
255
|
+
private releaseStartedAppGitSpan;
|
|
107
256
|
/**
|
|
108
257
|
* Update the OTLP `service.name` attribute. Called by Eve's
|
|
109
258
|
* `setup({ agentName })` so the resource attribute reflects the actual
|
|
@@ -122,6 +271,7 @@ declare class RaindropEveSpanExporter {
|
|
|
122
271
|
*/
|
|
123
272
|
attachAuxShutdown(fn: () => Promise<void>): void;
|
|
124
273
|
}
|
|
274
|
+
declare function createEveAppGitSpanProcessor(exporter: RaindropEveSpanExporter): EveAppGitSpanProcessor;
|
|
125
275
|
|
|
126
276
|
declare const RAINDROP_EVE_SDK_NAME: string;
|
|
127
277
|
declare const RAINDROP_EVE_SDK_VERSION: string;
|
|
@@ -240,6 +390,8 @@ interface RaindropEveInstrumentationEventsConfig {
|
|
|
240
390
|
* Options for {@link defineRaindropInstrumentation}.
|
|
241
391
|
*/
|
|
242
392
|
interface RaindropEveInstrumentationOptions {
|
|
393
|
+
/** Application Git identity. Local discovery requires an explicit sourceDirectory; false disables enrichment. */
|
|
394
|
+
appGit?: AppGitOptions | false;
|
|
243
395
|
/**
|
|
244
396
|
* `registerOTel` from `@vercel/otel`. Pass the function directly so the
|
|
245
397
|
* SDK doesn't have to dynamically import a peer dep at runtime.
|
|
@@ -452,4 +604,4 @@ interface RaindropInstrumentationDefinition {
|
|
|
452
604
|
*/
|
|
453
605
|
declare function defineRaindropInstrumentation(opts?: RaindropEveInstrumentationOptions): RaindropInstrumentationDefinition;
|
|
454
606
|
|
|
455
|
-
export { RAINDROP_EVE_SDK_NAME, RAINDROP_EVE_SDK_VERSION, type RaindropEveExporterOptions, type RaindropEveInstrumentationChannel, type RaindropEveInstrumentationEventsConfig, type RaindropEveInstrumentationMetadata, type RaindropEveInstrumentationMetadataConfig, type RaindropEveInstrumentationModelInput, type RaindropEveInstrumentationOptions, type RaindropEveInstrumentationSession, type RaindropEveInstrumentationStep, type RaindropEveInstrumentationTurn, RaindropEveSpanExporter, type RaindropEveStepStartedEventInput, type RaindropEveStepStartedEventResult, type RaindropEveStepStartedMetadataInput, type RaindropInstrumentationDefinition, type RegisterOTelFn, _resetCanonicalTurnIds, defineRaindropInstrumentation as default, defineRaindropInstrumentation };
|
|
607
|
+
export { RAINDROP_EVE_SDK_NAME, RAINDROP_EVE_SDK_VERSION, type RaindropEveExporterOptions, type RaindropEveInstrumentationChannel, type RaindropEveInstrumentationEventsConfig, type RaindropEveInstrumentationMetadata, type RaindropEveInstrumentationMetadataConfig, type RaindropEveInstrumentationModelInput, type RaindropEveInstrumentationOptions, type RaindropEveInstrumentationSession, type RaindropEveInstrumentationStep, type RaindropEveInstrumentationTurn, RaindropEveSpanExporter, type RaindropEveStepStartedEventInput, type RaindropEveStepStartedEventResult, type RaindropEveStepStartedMetadataInput, type RaindropInstrumentationDefinition, type RegisterOTelFn, _resetCanonicalTurnIds, createEveAppGitSpanProcessor, defineRaindropInstrumentation as default, defineRaindropInstrumentation };
|