@prisma/instrumentation-contract 0.0.1 → 7.1.0-dev.39

package/README.md

@@ -0,0 +1,113 @@
+# @prisma/instrumentation-contract
+
+This package provides the contract types and utilities for Prisma's instrumentation system. It defines the `TracingHelper` interface and provides functions to access the global tracing helper.
+
+> **Note:** This is an internal package with no API stability guarantees primarily intended for Prisma's own packages. However, it may be useful for third-party observability vendors whose solutions are not built on OpenTelemetry and who want to integrate with Prisma's tracing system.
+
+## Installation
+
+```sh
+npm install @prisma/instrumentation-contract
+```
+
+## Usage
+
+### Accessing the Global Tracing Helper
+
+If you're building an observability integration that needs to read tracing information from Prisma:
+
+```ts
+import { getGlobalTracingHelper } from '@prisma/instrumentation-contract'
+
+const helper = getGlobalTracingHelper()
+
+if (helper && helper.isEnabled()) {
+  const traceParent = helper.getTraceParent()
+  // Use traceParent for correlation
+}
+```
+
+### Implementing a Custom Tracing Helper
+
+If you're building a custom instrumentation solution (not based on OpenTelemetry), you can implement the `TracingHelper` interface and register it globally:
+
+```ts
+import { setGlobalTracingHelper, clearGlobalTracingHelper, type TracingHelper } from '@prisma/instrumentation-contract'
+
+const myTracingHelper: TracingHelper = {
+  isEnabled() {
+    return true
+  },
+
+  getTraceParent(context) {
+    // Return W3C Trace Context traceparent header
+    return '00-traceId-spanId-01'
+  },
+
+  dispatchEngineSpans(spans) {
+    // Handle emulated remote spans. In Prisma 7, this is only used for Accelerate spans.
+  },
+
+  getActiveContext() {
+    // Return the active context, if any
+    return undefined
+  },
+
+  runInChildSpan(nameOrOptions, callback) {
+    // Execute callback within a child span
+    return callback()
+  },
+}
+
+// Register your tracing helper
+setGlobalTracingHelper(myTracingHelper)
+
+// Later, when shutting down
+clearGlobalTracingHelper()
+```
+
+## API Reference
+
+### Functions
+
+#### `getGlobalTracingHelper(): TracingHelper | undefined`
+
+Returns the currently registered global tracing helper, or `undefined` if none is set.
+
+#### `setGlobalTracingHelper(helper: TracingHelper): void`
+
+Registers a tracing helper globally. This is typically called by instrumentation packages when they are enabled.
+
+#### `clearGlobalTracingHelper(): void`
+
+Clears the global tracing helper. This is typically called when instrumentation is disabled.
+
+### Types
+
+#### `TracingHelper`
+
+The main interface for tracing integration:
+
+```ts
+interface TracingHelper {
+  isEnabled(): boolean
+  getTraceParent(context?: Context): string
+  dispatchEngineSpans(spans: EngineSpan[]): void
+  getActiveContext(): Context | undefined
+  runInChildSpan<R>(nameOrOptions: string | ExtendedSpanOptions, callback: SpanCallback<R>): R
+}
+```
+
+See the TypeScript definitions for additional types like `EngineSpan`, `ExtendedSpanOptions`, and `SpanCallback`.
+
+## For OpenTelemetry Users
+
+If you're using OpenTelemetry, you should use [`@prisma/instrumentation`](https://www.npmjs.com/package/@prisma/instrumentation) instead. It provides a complete OpenTelemetry-based instrumentation that automatically registers the appropriate tracing helper.
+
+```ts
+import { PrismaInstrumentation, registerInstrumentations } from '@prisma/instrumentation'
+
+registerInstrumentations({
+  instrumentations: [new PrismaInstrumentation()],
+})
+```

package/dist/index.d.mts

@@ -1,18 +1,6 @@
-/**
- * Attributes is a map from string to attribute values.
- *
- * Note: only the own enumerable keys are counted as valid attribute keys.
- */
-declare interface Attributes {
-    [attributeKey: string]: AttributeValue | undefined;
-}
-
-/**
- * Attribute values may be any non-nullish primitive value except an object.
- *
- * null or undefined attribute values are invalid and will result in undefined behavior.
- */
-declare type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+import type { Context } from '@opentelemetry/api';
+import type { Span } from '@opentelemetry/api';
+import type { SpanOptions } from '@opentelemetry/api';
 
 /**
  * Clears the global tracing helper. This is called by @prisma/instrumentation
@@ -20,30 +8,6 @@ declare type AttributeValue = string | number | boolean | Array<null | undefined
  */
 export declare function clearGlobalTracingHelper(): void;
 
-declare interface Context {
-    /**
-     * Get a value from the context.
-     *
-     * @param key key which identifies a context value
-     */
-    getValue(key: symbol): unknown;
-    /**
-     * Create a new context which inherits from this context and has
-     * the given key set to the given value.
-     *
-     * @param key context key for which to set the value
-     * @param value value to set for the given key
-     */
-    setValue(key: symbol, value: unknown): Context;
-    /**
-     * Return a new context which inherits from this context but does
-     * not contain a value for the given key.
-     *
-     * @param key context key for which to clear a value
-     */
-    deleteValue(key: symbol): Context;
-}
-
 export declare type EngineSpan = {
     id: EngineSpanId;
     parentId: string | null;
@@ -77,34 +41,6 @@ export declare interface EngineTraceEvent {
     };
 }
 
-/**
- * Defines Exception.
- *
- * string or an object with one of (message or name or code) and optional stack
- */
-declare type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
-
-declare interface ExceptionWithCode {
-    code: string | number;
-    name?: string;
-    message?: string;
-    stack?: string;
-}
-
-declare interface ExceptionWithMessage {
-    code?: string | number;
-    message: string;
-    name?: string;
-    stack?: string;
-}
-
-declare interface ExceptionWithName {
-    code?: string | number;
-    message?: string;
-    name: string;
-    stack?: string;
-}
-
 export declare interface ExtendedSpanOptions extends SpanOptions {
     /** The name of the span */
     name: string;
@@ -123,44 +59,6 @@ export declare function getGlobalTracingHelper(): TracingHelper | undefined;
 
 export declare type HrTime = [number, number];
 
-/**
- * Defines High-Resolution Time.
- *
- * The first number, HrTime[0], is UNIX Epoch time in seconds since 00:00:00 UTC on 1 January 1970.
- * The second number, HrTime[1], represents the partial second elapsed since Unix Epoch time represented by first number in nanoseconds.
- * For example, 2021-01-01T12:30:10.150Z in UNIX Epoch time in milliseconds is represented as 1609504210150.
- * The first number is calculated by converting and truncating the Epoch time in milliseconds to seconds:
- * HrTime[0] = Math.trunc(1609504210150 / 1000) = 1609504210.
- * The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds:
- * HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000.
- * This is represented in HrTime format as [1609504210, 150000000].
- */
-declare type HrTime_2 = [number, number];
-
-/**
- * A pointer from the current {@link Span} to another span in the same trace or
- * in a different trace.
- * Few examples of Link usage.
- * 1. Batch Processing: A batch of elements may contain elements associated
- *    with one or more traces/spans. Since there can only be one parent
- *    SpanContext, Link is used to keep reference to SpanContext of all
- *    elements in the batch.
- * 2. Public Endpoint: A SpanContext in incoming client request on a public
- *    endpoint is untrusted from service provider perspective. In such case it
- *    is advisable to start a new trace with appropriate sampling decision.
- *    However, it is desirable to associate incoming SpanContext to new trace
- *    initiated on service provider side so two traces (from Client and from
- *    Service Provider) can be correlated.
- */
-declare interface Link {
-    /** The {@link SpanContext} of a linked span. */
-    context: SpanContext;
-    /** A set of {@link SpanAttributes} on the link. */
-    attributes?: SpanAttributes;
-    /** Count of attributes of the link that were dropped due to collection limits */
-    droppedAttributesCount?: number;
-}
-
 export declare type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'query';
 
 export declare interface PrismaInstrumentationGlobalValue {
@@ -170,306 +68,11 @@ export declare interface PrismaInstrumentationGlobalValue {
 /**
  * Sets the global tracing helper. This is called by @prisma/instrumentation
  * when instrumentation is enabled.
- *
- * @param helper - The tracing helper to set, or undefined to clear it
- */
-export declare function setGlobalTracingHelper(helper: TracingHelper | undefined): void;
-
-/**
- * An interface that represents a span. A span represents a single operation
- * within a trace. Examples of span might include remote procedure calls or a
- * in-process function calls to sub-components. A Trace has a single, top-level
- * "root" Span that in turn may have zero or more child Spans, which in turn
- * may have children.
- *
- * Spans are created by the {@link Tracer.startSpan} method.
  */
-declare interface Span {
-    /**
-     * Returns the {@link SpanContext} object associated with this Span.
-     *
-     * Get an immutable, serializable identifier for this span that can be used
-     * to create new child spans. Returned SpanContext is usable even after the
-     * span ends.
-     *
-     * @returns the SpanContext object associated with this Span.
-     */
-    spanContext(): SpanContext;
-    /**
-     * Sets an attribute to the span.
-     *
-     * Sets a single Attribute with the key and value passed as arguments.
-     *
-     * @param key the key for this attribute.
-     * @param value the value for this attribute. Setting a value null or
-     *              undefined is invalid and will result in undefined behavior.
-     */
-    setAttribute(key: string, value: SpanAttributeValue): this;
-    /**
-     * Sets attributes to the span.
-     *
-     * @param attributes the attributes that will be added.
-     *                   null or undefined attribute values
-     *                   are invalid and will result in undefined behavior.
-     */
-    setAttributes(attributes: SpanAttributes): this;
-    /**
-     * Adds an event to the Span.
-     *
-     * @param name the name of the event.
-     * @param [attributesOrStartTime] the attributes that will be added; these are
-     *     associated with this event. Can be also a start time
-     *     if type is {@type TimeInput} and 3rd param is undefined
-     * @param [startTime] start time of the event.
-     */
-    addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput, startTime?: TimeInput): this;
-    /**
-     * Adds a single link to the span.
-     *
-     * Links added after the creation will not affect the sampling decision.
-     * It is preferred span links be added at span creation.
-     *
-     * @param link the link to add.
-     */
-    addLink(link: Link): this;
-    /**
-     * Adds multiple links to the span.
-     *
-     * Links added after the creation will not affect the sampling decision.
-     * It is preferred span links be added at span creation.
-     *
-     * @param links the links to add.
-     */
-    addLinks(links: Link[]): this;
-    /**
-     * Sets a status to the span. If used, this will override the default Span
-     * status. Default is {@link SpanStatusCode.UNSET}. SetStatus overrides the value
-     * of previous calls to SetStatus on the Span.
-     *
-     * @param status the SpanStatus to set.
-     */
-    setStatus(status: SpanStatus): this;
-    /**
-     * Updates the Span name.
-     *
-     * This will override the name provided via {@link Tracer.startSpan}.
-     *
-     * Upon this update, any sampling behavior based on Span name will depend on
-     * the implementation.
-     *
-     * @param name the Span name.
-     */
-    updateName(name: string): this;
-    /**
-     * Marks the end of Span execution.
-     *
-     * Call to End of a Span MUST not have any effects on child spans. Those may
-     * still be running and can be ended later.
-     *
-     * Do not return `this`. The Span generally should not be used after it
-     * is ended so chaining is not desired in this context.
-     *
-     * @param [endTime] the time to set as Span's end time. If not provided,
-     *     use the current time as the span's end time.
-     */
-    end(endTime?: TimeInput): void;
-    /**
-     * Returns the flag whether this span will be recorded.
-     *
-     * @returns true if this Span is active and recording information like events
-     *     with the `AddEvent` operation and attributes using `setAttributes`.
-     */
-    isRecording(): boolean;
-    /**
-     * Sets exception as a span event
-     * @param exception the exception the only accepted values are string or Error
-     * @param [time] the time to set as Span's event time. If not provided,
-     *     use the current time.
-     */
-    recordException(exception: Exception, time?: TimeInput): void;
-}
-
-/**
- * @deprecated please use {@link Attributes}
- */
-declare type SpanAttributes = Attributes;
-
-/**
- * @deprecated please use {@link AttributeValue}
- */
-declare type SpanAttributeValue = AttributeValue;
+export declare function setGlobalTracingHelper(helper: TracingHelper): void;
 
 export declare type SpanCallback<R> = (span?: Span, context?: Context) => R;
 
-/**
- * A SpanContext represents the portion of a {@link Span} which must be
- * serialized and propagated along side of a {@link Baggage}.
- */
-declare interface SpanContext {
-    /**
-     * The ID of the trace that this span belongs to. It is worldwide unique
-     * with practically sufficient probability by being made as 16 randomly
-     * generated bytes, encoded as a 32 lowercase hex characters corresponding to
-     * 128 bits.
-     */
-    traceId: string;
-    /**
-     * The ID of the Span. It is globally unique with practically sufficient
-     * probability by being made as 8 randomly generated bytes, encoded as a 16
-     * lowercase hex characters corresponding to 64 bits.
-     */
-    spanId: string;
-    /**
-     * Only true if the SpanContext was propagated from a remote parent.
-     */
-    isRemote?: boolean;
-    /**
-     * Trace flags to propagate.
-     *
-     * It is represented as 1 byte (bitmap). Bit to represent whether trace is
-     * sampled or not. When set, the least significant bit documents that the
-     * caller may have recorded trace data. A caller who does not record trace
-     * data out-of-band leaves this flag unset.
-     *
-     * see {@link TraceFlags} for valid flag values.
-     */
-    traceFlags: number;
-    /**
-     * Tracing-system-specific info to propagate.
-     *
-     * The tracestate field value is a `list` as defined below. The `list` is a
-     * series of `list-members` separated by commas `,`, and a list-member is a
-     * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
-     * surrounding `list-members` are ignored. There can be a maximum of 32
-     * `list-members` in a `list`.
-     * More Info: https://www.w3.org/TR/trace-context/#tracestate-field
-     *
-     * Examples:
-     *     Single tracing system (generic format):
-     *         tracestate: rojo=00f067aa0ba902b7
-     *     Multiple tracing systems (with different formatting):
-     *         tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
-     */
-    traceState?: TraceState;
-}
-
-declare enum SpanKind {
-    /** Default value. Indicates that the span is used internally. */
-    INTERNAL = 0,
-    /**
-     * Indicates that the span covers server-side handling of an RPC or other
-     * remote request.
-     */
-    SERVER = 1,
-    /**
-     * Indicates that the span covers the client-side wrapper around an RPC or
-     * other remote request.
-     */
-    CLIENT = 2,
-    /**
-     * Indicates that the span describes producer sending a message to a
-     * broker. Unlike client and server, there is no direct critical path latency
-     * relationship between producer and consumer spans.
-     */
-    PRODUCER = 3,
-    /**
-     * Indicates that the span describes consumer receiving a message from a
-     * broker. Unlike client and server, there is no direct critical path latency
-     * relationship between producer and consumer spans.
-     */
-    CONSUMER = 4
-}
-
-/**
- * Options needed for span creation
- */
-declare interface SpanOptions {
-    /**
-     * The SpanKind of a span
-     * @default {@link SpanKind.INTERNAL}
-     */
-    kind?: SpanKind;
-    /** A span's attributes */
-    attributes?: SpanAttributes;
-    /** {@link Link}s span to other spans */
-    links?: Link[];
-    /** A manually specified start time for the created `Span` object. */
-    startTime?: TimeInput;
-    /** The new span should be a root span. (Ignore parent from context). */
-    root?: boolean;
-}
-
-declare interface SpanStatus {
-    /** The status code of this message. */
-    code: SpanStatusCode;
-    /** A developer-facing error message. */
-    message?: string;
-}
-
-/**
- * An enumeration of status codes.
- */
-declare enum SpanStatusCode {
-    /**
-     * The default status.
-     */
-    UNSET = 0,
-    /**
-     * The operation has been validated by an Application developer or
-     * Operator to have completed successfully.
-     */
-    OK = 1,
-    /**
-     * The operation contains an error.
-     */
-    ERROR = 2
-}
-
-/**
- * Defines TimeInput.
- *
- * hrtime, epoch milliseconds, performance.now() or Date
- */
-declare type TimeInput = HrTime_2 | number | Date;
-
-declare interface TraceState {
-    /**
-     * Create a new TraceState which inherits from this TraceState and has the
-     * given key set.
-     * The new entry will always be added in the front of the list of states.
-     *
-     * @param key key of the TraceState entry.
-     * @param value value of the TraceState entry.
-     */
-    set(key: string, value: string): TraceState;
-    /**
-     * Return a new TraceState which inherits from this TraceState but does not
-     * contain the given key.
-     *
-     * @param key the key for the TraceState entry to be removed.
-     */
-    unset(key: string): TraceState;
-    /**
-     * Returns the value to which the specified key is mapped, or `undefined` if
-     * this map contains no mapping for the key.
-     *
-     * @param key with which the specified value is to be associated.
-     * @returns the value to which the specified key is mapped, or `undefined` if
-     *     this map contains no mapping for the key.
-     */
-    get(key: string): string | undefined;
-    /**
-     * Serializes the TraceState to a `list` as defined below. The `list` is a
-     * series of `list-members` separated by commas `,`, and a list-member is a
-     * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
-     * surrounding `list-members` are ignored. There can be a maximum of 32
-     * `list-members` in a `list`.
-     *
-     * @returns the serialized string.
-     */
-    serialize(): string;
-}
-
 export declare interface TracingHelper {
     isEnabled(): boolean;
     getTraceParent(context?: Context): string;

package/dist/index.d.ts

@@ -1,18 +1,6 @@
-/**
- * Attributes is a map from string to attribute values.
- *
- * Note: only the own enumerable keys are counted as valid attribute keys.
- */
-declare interface Attributes {
-    [attributeKey: string]: AttributeValue | undefined;
-}
-
-/**
- * Attribute values may be any non-nullish primitive value except an object.
- *
- * null or undefined attribute values are invalid and will result in undefined behavior.
- */
-declare type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+import type { Context } from '@opentelemetry/api';
+import type { Span } from '@opentelemetry/api';
+import type { SpanOptions } from '@opentelemetry/api';
 
 /**
  * Clears the global tracing helper. This is called by @prisma/instrumentation
@@ -20,30 +8,6 @@ declare type AttributeValue = string | number | boolean | Array<null | undefined
  */
 export declare function clearGlobalTracingHelper(): void;
 
-declare interface Context {
-    /**
-     * Get a value from the context.
-     *
-     * @param key key which identifies a context value
-     */
-    getValue(key: symbol): unknown;
-    /**
-     * Create a new context which inherits from this context and has
-     * the given key set to the given value.
-     *
-     * @param key context key for which to set the value
-     * @param value value to set for the given key
-     */
-    setValue(key: symbol, value: unknown): Context;
-    /**
-     * Return a new context which inherits from this context but does
-     * not contain a value for the given key.
-     *
-     * @param key context key for which to clear a value
-     */
-    deleteValue(key: symbol): Context;
-}
-
 export declare type EngineSpan = {
     id: EngineSpanId;
     parentId: string | null;
@@ -77,34 +41,6 @@ export declare interface EngineTraceEvent {
     };
 }
 
-/**
- * Defines Exception.
- *
- * string or an object with one of (message or name or code) and optional stack
- */
-declare type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
-
-declare interface ExceptionWithCode {
-    code: string | number;
-    name?: string;
-    message?: string;
-    stack?: string;
-}
-
-declare interface ExceptionWithMessage {
-    code?: string | number;
-    message: string;
-    name?: string;
-    stack?: string;
-}
-
-declare interface ExceptionWithName {
-    code?: string | number;
-    message?: string;
-    name: string;
-    stack?: string;
-}
-
 export declare interface ExtendedSpanOptions extends SpanOptions {
     /** The name of the span */
     name: string;
@@ -123,44 +59,6 @@ export declare function getGlobalTracingHelper(): TracingHelper | undefined;
 
 export declare type HrTime = [number, number];
 
-/**
- * Defines High-Resolution Time.
- *
- * The first number, HrTime[0], is UNIX Epoch time in seconds since 00:00:00 UTC on 1 January 1970.
- * The second number, HrTime[1], represents the partial second elapsed since Unix Epoch time represented by first number in nanoseconds.
- * For example, 2021-01-01T12:30:10.150Z in UNIX Epoch time in milliseconds is represented as 1609504210150.
- * The first number is calculated by converting and truncating the Epoch time in milliseconds to seconds:
- * HrTime[0] = Math.trunc(1609504210150 / 1000) = 1609504210.
- * The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds:
- * HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000.
- * This is represented in HrTime format as [1609504210, 150000000].
- */
-declare type HrTime_2 = [number, number];
-
-/**
- * A pointer from the current {@link Span} to another span in the same trace or
- * in a different trace.
- * Few examples of Link usage.
- * 1. Batch Processing: A batch of elements may contain elements associated
- *    with one or more traces/spans. Since there can only be one parent
- *    SpanContext, Link is used to keep reference to SpanContext of all
- *    elements in the batch.
- * 2. Public Endpoint: A SpanContext in incoming client request on a public
- *    endpoint is untrusted from service provider perspective. In such case it
- *    is advisable to start a new trace with appropriate sampling decision.
- *    However, it is desirable to associate incoming SpanContext to new trace
- *    initiated on service provider side so two traces (from Client and from
- *    Service Provider) can be correlated.
- */
-declare interface Link {
-    /** The {@link SpanContext} of a linked span. */
-    context: SpanContext;
-    /** A set of {@link SpanAttributes} on the link. */
-    attributes?: SpanAttributes;
-    /** Count of attributes of the link that were dropped due to collection limits */
-    droppedAttributesCount?: number;
-}
-
 export declare type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'query';
 
 export declare interface PrismaInstrumentationGlobalValue {
@@ -170,306 +68,11 @@ export declare interface PrismaInstrumentationGlobalValue {
 /**
  * Sets the global tracing helper. This is called by @prisma/instrumentation
  * when instrumentation is enabled.
- *
- * @param helper - The tracing helper to set, or undefined to clear it
- */
-export declare function setGlobalTracingHelper(helper: TracingHelper | undefined): void;
-
-/**
- * An interface that represents a span. A span represents a single operation
- * within a trace. Examples of span might include remote procedure calls or a
- * in-process function calls to sub-components. A Trace has a single, top-level
- * "root" Span that in turn may have zero or more child Spans, which in turn
- * may have children.
- *
- * Spans are created by the {@link Tracer.startSpan} method.
  */
-declare interface Span {
-    /**
-     * Returns the {@link SpanContext} object associated with this Span.
-     *
-     * Get an immutable, serializable identifier for this span that can be used
-     * to create new child spans. Returned SpanContext is usable even after the
-     * span ends.
-     *
-     * @returns the SpanContext object associated with this Span.
-     */
-    spanContext(): SpanContext;
-    /**
-     * Sets an attribute to the span.
-     *
-     * Sets a single Attribute with the key and value passed as arguments.
-     *
-     * @param key the key for this attribute.
-     * @param value the value for this attribute. Setting a value null or
-     *              undefined is invalid and will result in undefined behavior.
-     */
-    setAttribute(key: string, value: SpanAttributeValue): this;
-    /**
-     * Sets attributes to the span.
-     *
-     * @param attributes the attributes that will be added.
-     *                   null or undefined attribute values
-     *                   are invalid and will result in undefined behavior.
-     */
-    setAttributes(attributes: SpanAttributes): this;
-    /**
-     * Adds an event to the Span.
-     *
-     * @param name the name of the event.
-     * @param [attributesOrStartTime] the attributes that will be added; these are
-     *     associated with this event. Can be also a start time
-     *     if type is {@type TimeInput} and 3rd param is undefined
-     * @param [startTime] start time of the event.
-     */
-    addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput, startTime?: TimeInput): this;
-    /**
-     * Adds a single link to the span.
-     *
-     * Links added after the creation will not affect the sampling decision.
-     * It is preferred span links be added at span creation.
-     *
-     * @param link the link to add.
-     */
-    addLink(link: Link): this;
-    /**
-     * Adds multiple links to the span.
-     *
-     * Links added after the creation will not affect the sampling decision.
-     * It is preferred span links be added at span creation.
-     *
-     * @param links the links to add.
-     */
-    addLinks(links: Link[]): this;
-    /**
-     * Sets a status to the span. If used, this will override the default Span
-     * status. Default is {@link SpanStatusCode.UNSET}. SetStatus overrides the value
-     * of previous calls to SetStatus on the Span.
-     *
-     * @param status the SpanStatus to set.
-     */
-    setStatus(status: SpanStatus): this;
-    /**
-     * Updates the Span name.
-     *
-     * This will override the name provided via {@link Tracer.startSpan}.
-     *
-     * Upon this update, any sampling behavior based on Span name will depend on
-     * the implementation.
-     *
-     * @param name the Span name.
-     */
-    updateName(name: string): this;
-    /**
-     * Marks the end of Span execution.
-     *
-     * Call to End of a Span MUST not have any effects on child spans. Those may
-     * still be running and can be ended later.
-     *
-     * Do not return `this`. The Span generally should not be used after it
-     * is ended so chaining is not desired in this context.
-     *
-     * @param [endTime] the time to set as Span's end time. If not provided,
-     *     use the current time as the span's end time.
-     */
-    end(endTime?: TimeInput): void;
-    /**
-     * Returns the flag whether this span will be recorded.
-     *
-     * @returns true if this Span is active and recording information like events
-     *     with the `AddEvent` operation and attributes using `setAttributes`.
-     */
-    isRecording(): boolean;
-    /**
-     * Sets exception as a span event
-     * @param exception the exception the only accepted values are string or Error
-     * @param [time] the time to set as Span's event time. If not provided,
-     *     use the current time.
-     */
-    recordException(exception: Exception, time?: TimeInput): void;
-}
-
-/**
- * @deprecated please use {@link Attributes}
- */
-declare type SpanAttributes = Attributes;
-
-/**
- * @deprecated please use {@link AttributeValue}
- */
-declare type SpanAttributeValue = AttributeValue;
+export declare function setGlobalTracingHelper(helper: TracingHelper): void;
 
 export declare type SpanCallback<R> = (span?: Span, context?: Context) => R;
 
-/**
- * A SpanContext represents the portion of a {@link Span} which must be
- * serialized and propagated along side of a {@link Baggage}.
- */
-declare interface SpanContext {
-    /**
-     * The ID of the trace that this span belongs to. It is worldwide unique
-     * with practically sufficient probability by being made as 16 randomly
-     * generated bytes, encoded as a 32 lowercase hex characters corresponding to
-     * 128 bits.
-     */
-    traceId: string;
-    /**
-     * The ID of the Span. It is globally unique with practically sufficient
-     * probability by being made as 8 randomly generated bytes, encoded as a 16
-     * lowercase hex characters corresponding to 64 bits.
-     */
-    spanId: string;
-    /**
-     * Only true if the SpanContext was propagated from a remote parent.
-     */
-    isRemote?: boolean;
-    /**
-     * Trace flags to propagate.
-     *
-     * It is represented as 1 byte (bitmap). Bit to represent whether trace is
-     * sampled or not. When set, the least significant bit documents that the
-     * caller may have recorded trace data. A caller who does not record trace
-     * data out-of-band leaves this flag unset.
-     *
-     * see {@link TraceFlags} for valid flag values.
-     */
-    traceFlags: number;
-    /**
-     * Tracing-system-specific info to propagate.
-     *
-     * The tracestate field value is a `list` as defined below. The `list` is a
-     * series of `list-members` separated by commas `,`, and a list-member is a
-     * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
-     * surrounding `list-members` are ignored. There can be a maximum of 32
-     * `list-members` in a `list`.
-     * More Info: https://www.w3.org/TR/trace-context/#tracestate-field
-     *
-     * Examples:
-     *     Single tracing system (generic format):
-     *         tracestate: rojo=00f067aa0ba902b7
-     *     Multiple tracing systems (with different formatting):
-     *         tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
-     */
-    traceState?: TraceState;
-}
-
-declare enum SpanKind {
-    /** Default value. Indicates that the span is used internally. */
-    INTERNAL = 0,
-    /**
-     * Indicates that the span covers server-side handling of an RPC or other
-     * remote request.
-     */
-    SERVER = 1,
-    /**
-     * Indicates that the span covers the client-side wrapper around an RPC or
-     * other remote request.
-     */
-    CLIENT = 2,
-    /**
-     * Indicates that the span describes producer sending a message to a
-     * broker. Unlike client and server, there is no direct critical path latency
-     * relationship between producer and consumer spans.
-     */
-    PRODUCER = 3,
-    /**
-     * Indicates that the span describes consumer receiving a message from a
-     * broker. Unlike client and server, there is no direct critical path latency
-     * relationship between producer and consumer spans.
-     */
-    CONSUMER = 4
-}
-
-/**
- * Options needed for span creation
- */
-declare interface SpanOptions {
-    /**
-     * The SpanKind of a span
-     * @default {@link SpanKind.INTERNAL}
-     */
-    kind?: SpanKind;
-    /** A span's attributes */
-    attributes?: SpanAttributes;
-    /** {@link Link}s span to other spans */
-    links?: Link[];
-    /** A manually specified start time for the created `Span` object. */
-    startTime?: TimeInput;
-    /** The new span should be a root span. (Ignore parent from context). */
-    root?: boolean;
-}
-
-declare interface SpanStatus {
-    /** The status code of this message. */
-    code: SpanStatusCode;
-    /** A developer-facing error message. */
-    message?: string;
-}
-
-/**
- * An enumeration of status codes.
- */
-declare enum SpanStatusCode {
-    /**
-     * The default status.
-     */
-    UNSET = 0,
-    /**
-     * The operation has been validated by an Application developer or
-     * Operator to have completed successfully.
-     */
-    OK = 1,
-    /**
-     * The operation contains an error.
-     */
-    ERROR = 2
-}
-
-/**
- * Defines TimeInput.
- *
- * hrtime, epoch milliseconds, performance.now() or Date
- */
-declare type TimeInput = HrTime_2 | number | Date;
-
-declare interface TraceState {
-    /**
-     * Create a new TraceState which inherits from this TraceState and has the
-     * given key set.
-     * The new entry will always be added in the front of the list of states.
-     *
-     * @param key key of the TraceState entry.
-     * @param value value of the TraceState entry.
-     */
-    set(key: string, value: string): TraceState;
-    /**
-     * Return a new TraceState which inherits from this TraceState but does not
-     * contain the given key.
-     *
-     * @param key the key for the TraceState entry to be removed.
-     */
-    unset(key: string): TraceState;
-    /**
-     * Returns the value to which the specified key is mapped, or `undefined` if
-     * this map contains no mapping for the key.
-     *
-     * @param key with which the specified value is to be associated.
-     * @returns the value to which the specified key is mapped, or `undefined` if
-     *     this map contains no mapping for the key.
-     */
-    get(key: string): string | undefined;
-    /**
-     * Serializes the TraceState to a `list` as defined below. The `list` is a
-     * series of `list-members` separated by commas `,`, and a list-member is a
-     * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
-     * surrounding `list-members` are ignored. There can be a maximum of 32
-     * `list-members` in a `list`.
-     *
-     * @returns the serialized string.
-     */
-    serialize(): string;
-}
-
 export declare interface TracingHelper {
     isEnabled(): boolean;
     getTraceParent(context?: Context): string;

package/dist/index.js

@@ -29,7 +29,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@prisma/instrumentation-contract",
-  version: "0.0.1",
+  version: "7.1.0-dev.39",
   description: "Shared types and utilities for Prisma instrumentation",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -65,8 +65,10 @@ var package_default = {
   ],
   sideEffects: false,
   devDependencies: {
-    "@opentelemetry/api": "1.9.0",
-    vitest: "3.2.4"
+    "@opentelemetry/api": "1.9.0"
+  },
+  peerDependencies: {
+    "@opentelemetry/api": "^1.8"
   }
 };
 
@@ -74,22 +76,23 @@ var package_default = {
 var majorVersion = package_default.version.split(".")[0];
 var GLOBAL_INSTRUMENTATION_KEY = "PRISMA_INSTRUMENTATION";
 var GLOBAL_VERSIONED_INSTRUMENTATION_KEY = `V${majorVersion}_PRISMA_INSTRUMENTATION`;
+var globalThisWithPrismaInstrumentation = globalThis;
 function getGlobalTracingHelper() {
-  const versionedGlobal = globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  const versionedGlobal = globalThisWithPrismaInstrumentation[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
   if (versionedGlobal?.helper) {
     return versionedGlobal.helper;
   }
-  const fallbackGlobal = globalThis[GLOBAL_INSTRUMENTATION_KEY];
+  const fallbackGlobal = globalThisWithPrismaInstrumentation[GLOBAL_INSTRUMENTATION_KEY];
   return fallbackGlobal?.helper;
 }
 function setGlobalTracingHelper(helper) {
-  const globalValue = helper ? { helper } : void 0;
-  globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY] = globalValue;
-  globalThis[GLOBAL_INSTRUMENTATION_KEY] = globalValue;
+  const globalValue = { helper };
+  globalThisWithPrismaInstrumentation[GLOBAL_VERSIONED_INSTRUMENTATION_KEY] = globalValue;
+  globalThisWithPrismaInstrumentation[GLOBAL_INSTRUMENTATION_KEY] = globalValue;
 }
 function clearGlobalTracingHelper() {
-  delete globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
-  delete globalThis[GLOBAL_INSTRUMENTATION_KEY];
+  delete globalThisWithPrismaInstrumentation[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  delete globalThisWithPrismaInstrumentation[GLOBAL_INSTRUMENTATION_KEY];
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@prisma/instrumentation-contract",
-  version: "0.0.1",
+  version: "7.1.0-dev.39",
   description: "Shared types and utilities for Prisma instrumentation",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -37,8 +37,10 @@ var package_default = {
   ],
   sideEffects: false,
   devDependencies: {
-    "@opentelemetry/api": "1.9.0",
-    vitest: "3.2.4"
+    "@opentelemetry/api": "1.9.0"
+  },
+  peerDependencies: {
+    "@opentelemetry/api": "^1.8"
   }
 };
 
@@ -46,22 +48,23 @@ var package_default = {
 var majorVersion = package_default.version.split(".")[0];
 var GLOBAL_INSTRUMENTATION_KEY = "PRISMA_INSTRUMENTATION";
 var GLOBAL_VERSIONED_INSTRUMENTATION_KEY = `V${majorVersion}_PRISMA_INSTRUMENTATION`;
+var globalThisWithPrismaInstrumentation = globalThis;
 function getGlobalTracingHelper() {
-  const versionedGlobal = globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  const versionedGlobal = globalThisWithPrismaInstrumentation[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
   if (versionedGlobal?.helper) {
     return versionedGlobal.helper;
   }
-  const fallbackGlobal = globalThis[GLOBAL_INSTRUMENTATION_KEY];
+  const fallbackGlobal = globalThisWithPrismaInstrumentation[GLOBAL_INSTRUMENTATION_KEY];
   return fallbackGlobal?.helper;
 }
 function setGlobalTracingHelper(helper) {
-  const globalValue = helper ? { helper } : void 0;
-  globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY] = globalValue;
-  globalThis[GLOBAL_INSTRUMENTATION_KEY] = globalValue;
+  const globalValue = { helper };
+  globalThisWithPrismaInstrumentation[GLOBAL_VERSIONED_INSTRUMENTATION_KEY] = globalValue;
+  globalThisWithPrismaInstrumentation[GLOBAL_INSTRUMENTATION_KEY] = globalValue;
 }
 function clearGlobalTracingHelper() {
-  delete globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
-  delete globalThis[GLOBAL_INSTRUMENTATION_KEY];
+  delete globalThisWithPrismaInstrumentation[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  delete globalThisWithPrismaInstrumentation[GLOBAL_INSTRUMENTATION_KEY];
 }
 export {
   clearGlobalTracingHelper,

package/dist/src/global.d.ts

@@ -7,10 +7,8 @@ export declare function getGlobalTracingHelper(): TracingHelper | undefined;
 /**
  * Sets the global tracing helper. This is called by @prisma/instrumentation
  * when instrumentation is enabled.
- *
- * @param helper - The tracing helper to set, or undefined to clear it
  */
-export declare function setGlobalTracingHelper(helper: TracingHelper | undefined): void;
+export declare function setGlobalTracingHelper(helper: TracingHelper): void;
 /**
  * Clears the global tracing helper. This is called by @prisma/instrumentation
  * when instrumentation is disabled.

package/dist/src/index.d.ts

@@ -1,2 +1,2 @@
-export * from './types';
 export * from './global';
+export * from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/instrumentation-contract",
-  "version": "0.0.1",
+  "version": "7.1.0-dev.39",
   "description": "Shared types and utilities for Prisma instrumentation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -30,8 +30,10 @@
   ],
   "sideEffects": false,
   "devDependencies": {
-    "@opentelemetry/api": "1.9.0",
-    "vitest": "3.2.4"
+    "@opentelemetry/api": "1.9.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.8"
   },
   "scripts": {
     "dev": "DEV=true tsx helpers/build.ts",