@prisma/instrumentation-contract 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,481 @@
+/**
+ * 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>;
+
+/**
+ * Clears the global tracing helper. This is called by @prisma/instrumentation
+ * when instrumentation is disabled.
+ */
+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;
+    name: string;
+    startTime: HrTime;
+    endTime: HrTime;
+    kind: EngineSpanKind;
+    attributes?: Record<string, unknown>;
+    links?: EngineSpanId[];
+};
+
+export declare type EngineSpanId = string;
+
+export declare type EngineSpanKind = 'client' | 'internal';
+
+export declare interface EngineTrace {
+    spans: EngineSpan[];
+    events: EngineTraceEvent[];
+}
+
+export declare interface EngineTraceEvent {
+    spanId: EngineSpanId;
+    target?: string;
+    level: LogLevel;
+    timestamp: HrTime;
+    attributes: Record<string, unknown> & {
+        message?: string;
+        query?: string;
+        duration_ms?: number;
+        params?: string;
+    };
+}
+
+/**
+ * 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;
+    internal?: boolean;
+    /** Whether it propagates context (?=true) */
+    active?: boolean;
+    /** The context to append the span to */
+    context?: Context;
+}
+
+/**
+ * Returns the TracingHelper from the global instrumentation if available,
+ * preferring the versioned global over the fallback global for compatibility.
+ */
+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 {
+    helper?: TracingHelper;
+}
+
+/**
+ * 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 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;
+    dispatchEngineSpans(spans: EngineSpan[]): void;
+    getActiveContext(): Context | undefined;
+    runInChildSpan<R>(nameOrOptions: string | ExtendedSpanOptions, callback: SpanCallback<R>): R;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,99 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  clearGlobalTracingHelper: () => clearGlobalTracingHelper,
+  getGlobalTracingHelper: () => getGlobalTracingHelper,
+  setGlobalTracingHelper: () => setGlobalTracingHelper
+});
+module.exports = __toCommonJS(index_exports);
+
+// package.json
+var package_default = {
+  name: "@prisma/instrumentation-contract",
+  version: "0.0.1",
+  description: "Shared types and utilities for Prisma instrumentation",
+  main: "dist/index.js",
+  module: "dist/index.mjs",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      require: {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      },
+      import: {
+        types: "./dist/index.d.mts",
+        default: "./dist/index.mjs"
+      }
+    }
+  },
+  license: "Apache-2.0",
+  homepage: "https://www.prisma.io",
+  repository: {
+    type: "git",
+    url: "https://github.com/prisma/prisma.git",
+    directory: "packages/instrumentation-contract"
+  },
+  bugs: "https://github.com/prisma/prisma/issues",
+  scripts: {
+    dev: "DEV=true tsx helpers/build.ts",
+    build: "tsx helpers/build.ts",
+    prepublishOnly: "pnpm run build",
+    test: "vitest run"
+  },
+  files: [
+    "dist"
+  ],
+  sideEffects: false,
+  devDependencies: {
+    "@opentelemetry/api": "1.9.0",
+    vitest: "3.2.4"
+  }
+};
+
+// src/global.ts
+var majorVersion = package_default.version.split(".")[0];
+var GLOBAL_INSTRUMENTATION_KEY = "PRISMA_INSTRUMENTATION";
+var GLOBAL_VERSIONED_INSTRUMENTATION_KEY = `V${majorVersion}_PRISMA_INSTRUMENTATION`;
+function getGlobalTracingHelper() {
+  const versionedGlobal = globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  if (versionedGlobal?.helper) {
+    return versionedGlobal.helper;
+  }
+  const fallbackGlobal = globalThis[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;
+}
+function clearGlobalTracingHelper() {
+  delete globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  delete globalThis[GLOBAL_INSTRUMENTATION_KEY];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearGlobalTracingHelper,
+  getGlobalTracingHelper,
+  setGlobalTracingHelper
+});

package/dist/index.mjs

@@ -0,0 +1,70 @@
+// package.json
+var package_default = {
+  name: "@prisma/instrumentation-contract",
+  version: "0.0.1",
+  description: "Shared types and utilities for Prisma instrumentation",
+  main: "dist/index.js",
+  module: "dist/index.mjs",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      require: {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      },
+      import: {
+        types: "./dist/index.d.mts",
+        default: "./dist/index.mjs"
+      }
+    }
+  },
+  license: "Apache-2.0",
+  homepage: "https://www.prisma.io",
+  repository: {
+    type: "git",
+    url: "https://github.com/prisma/prisma.git",
+    directory: "packages/instrumentation-contract"
+  },
+  bugs: "https://github.com/prisma/prisma/issues",
+  scripts: {
+    dev: "DEV=true tsx helpers/build.ts",
+    build: "tsx helpers/build.ts",
+    prepublishOnly: "pnpm run build",
+    test: "vitest run"
+  },
+  files: [
+    "dist"
+  ],
+  sideEffects: false,
+  devDependencies: {
+    "@opentelemetry/api": "1.9.0",
+    vitest: "3.2.4"
+  }
+};
+
+// src/global.ts
+var majorVersion = package_default.version.split(".")[0];
+var GLOBAL_INSTRUMENTATION_KEY = "PRISMA_INSTRUMENTATION";
+var GLOBAL_VERSIONED_INSTRUMENTATION_KEY = `V${majorVersion}_PRISMA_INSTRUMENTATION`;
+function getGlobalTracingHelper() {
+  const versionedGlobal = globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  if (versionedGlobal?.helper) {
+    return versionedGlobal.helper;
+  }
+  const fallbackGlobal = globalThis[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;
+}
+function clearGlobalTracingHelper() {
+  delete globalThis[GLOBAL_VERSIONED_INSTRUMENTATION_KEY];
+  delete globalThis[GLOBAL_INSTRUMENTATION_KEY];
+}
+export {
+  clearGlobalTracingHelper,
+  getGlobalTracingHelper,
+  setGlobalTracingHelper
+};

package/dist/src/global.d.ts

@@ -0,0 +1,18 @@
+import type { TracingHelper } from './types';
+/**
+ * Returns the TracingHelper from the global instrumentation if available,
+ * preferring the versioned global over the fallback global for compatibility.
+ */
+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;
+/**
+ * Clears the global tracing helper. This is called by @prisma/instrumentation
+ * when instrumentation is disabled.
+ */
+export declare function clearGlobalTracingHelper(): void;

package/dist/src/index.d.ts

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