feat(client): improve debug logs

chore: unknown commit message

Author: stainless-bot

README.md

@@ -596,7 +596,7 @@ const client = new OpenAI({
 });
 ```
 
-Note that if given a `DEBUG=true` environment variable, this library will log all requests and responses automatically.
+Note that if given a `OPENAI_LOG=debug` environment variable, this library will log all requests and responses automatically.
 This is intended for debugging purposes only and may change in the future without notice.
 
 ### Configuring an HTTP(S) Agent (e.g., for proxies)

src/api-promise.ts

@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { type OpenAI } from './client';
+
 import { type PromiseOrValue } from './internal/types';
 import {
   type APIResponseProps,
@@ -14,10 +16,13 @@ import {
  */
 export class APIPromise<T> extends Promise<WithRequestID<T>> {
   private parsedPromise: Promise<WithRequestID<T>> | undefined;
+  #client: OpenAI;
 
   constructor(
+    client: OpenAI,
     private responsePromise: Promise<APIResponseProps>,
     private parseResponse: (
+      client: OpenAI,
       props: APIResponseProps,
     ) => PromiseOrValue<WithRequestID<T>> = defaultParseResponse,
   ) {
@@ -27,11 +32,12 @@ export class APIPromise<T> extends Promise<WithRequestID<T>> {
       // to parse the response
       resolve(null as any);
     });
+    this.#client = client;
   }
 
   _thenUnwrap<U>(transform: (data: T, props: APIResponseProps) => U): APIPromise<U> {
-    return new APIPromise(this.responsePromise, async (props) =>
-      addRequestID(transform(await this.parseResponse(props), props), props.response),
+    return new APIPromise(this.#client, this.responsePromise, async (client, props) =>
+      addRequestID(transform(await this.parseResponse(client, props), props), props.response),
     );
   }
 
@@ -69,7 +75,9 @@ export class APIPromise<T> extends Promise<WithRequestID<T>> {
 
   private parse(): Promise<WithRequestID<T>> {
     if (!this.parsedPromise) {
-      this.parsedPromise = this.responsePromise.then(this.parseResponse) as any as Promise<WithRequestID<T>>;
+      this.parsedPromise = this.responsePromise.then((data) =>
+        this.parseResponse(this.#client, data),
+      ) as any as Promise<WithRequestID<T>>;
     }
     return this.parsedPromise;
   }

src/client.ts

@@ -2,7 +2,6 @@
 
 import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
 import type { HTTPMethod, PromiseOrValue } from './internal/types';
-import { debug } from './internal/utils/log';
 import { uuid4 } from './internal/utils/uuid';
 import { validatePositiveInteger, isAbsoluteURL } from './internal/utils/values';
 import { sleep } from './internal/utils/sleep';
@@ -81,6 +80,7 @@ import {
   Moderations,
 } from './resources/moderations';
 import { readEnv } from './internal/utils/env';
+import { logger } from './internal/utils/log';
 import { isEmptyObj } from './internal/utils/values';
 import { Audio, AudioModel, AudioResponseFormat } from './resources/audio/audio';
 import { Beta } from './resources/beta/beta';
@@ -134,6 +134,25 @@ const safeJSON = (text: string) => {
   }
 };
 
+type LogFn = (message: string, ...rest: unknown[]) => void;
+export type Logger = {
+  error: LogFn;
+  warn: LogFn;
+  info: LogFn;
+  debug: LogFn;
+};
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
+const isLogLevel = (key: string | undefined): key is LogLevel => {
+  const levels: Record<LogLevel, true> = {
+    off: true,
+    error: true,
+    warn: true,
+    info: true,
+    debug: true,
+  };
+  return key! in levels;
+};
+
 export interface ClientOptions {
   /**
    * Defaults to process.env['OPENAI_API_KEY'].
@@ -210,6 +229,20 @@ export interface ClientOptions {
    * Only set this option to `true` if you understand the risks and have appropriate mitigations in place.
    */
   dangerouslyAllowBrowser?: boolean;
+
+  /**
+   * Set the log level.
+   *
+   * Defaults to process.env['OPENAI_LOG'].
+   */
+  logLevel?: LogLevel | undefined | null;
+
+  /**
+   * Set the logger.
+   *
+   * Defaults to globalThis.console.
+   */
+  logger?: Logger | undefined | null;
 }
 
 type FinalizedRequestInit = RequestInit & { headers: Headers };
@@ -225,6 +258,8 @@ export class OpenAI {
   baseURL: string;
   maxRetries: number;
   timeout: number;
+  logger: Logger | undefined;
+  logLevel: LogLevel | undefined;
   httpAgent: Shims.Agent | undefined;
 
   private fetch: Fetch;
@@ -276,6 +311,15 @@ export class OpenAI {
 
     this.baseURL = options.baseURL!;
     this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT /* 10 minutes */;
+    this.logger = options.logger ?? console;
+    if (options.logLevel != null) {
+      this.logLevel = options.logLevel;
+    } else {
+      const envLevel = readEnv('OPENAI_LOG');
+      if (isLogLevel(envLevel)) {
+        this.logLevel = envLevel;
+      }
+    }
     this.httpAgent = options.httpAgent;
     this.maxRetries = options.maxRetries ?? 2;
     this.fetch = options.fetch ?? Shims.getDefaultFetch();
@@ -415,7 +459,7 @@ export class OpenAI {
     options: PromiseOrValue<FinalRequestOptions>,
     remainingRetries: number | null = null,
   ): APIPromise<Rsp> {
-    return new APIPromise(this.makeRequest(options, remainingRetries));
+    return new APIPromise(this, this.makeRequest(options, remainingRetries));
   }
 
   private async makeRequest(
@@ -434,7 +478,7 @@ export class OpenAI {
 
     await this.prepareRequest(req, { url, options });
 
-    debug('request', url, options, req.headers);
+    logger(this).debug('request', url, options, req.headers);
 
     if (options.signal?.aborted) {
       throw new Errors.APIUserAbortError();
@@ -459,7 +503,7 @@ export class OpenAI {
     if (!response.ok) {
       if (retriesRemaining && this.shouldRetry(response)) {
         const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
-        debug(`response (error; ${retryMessage})`, response.status, url, response.headers);
+        logger(this).debug(`response (error; ${retryMessage})`, response.status, url, response.headers);
         return this.retryRequest(options, retriesRemaining, response.headers);
       }
 
@@ -468,7 +512,13 @@ export class OpenAI {
       const errMessage = errJSON ? undefined : errText;
       const retryMessage = retriesRemaining ? `(error; no more retries left)` : `(error; not retryable)`;
 
-      debug(`response (error; ${retryMessage})`, response.status, url, response.headers, errMessage);
+      logger(this).debug(
+        `response (error; ${retryMessage})`,
+        response.status,
+        url,
+        response.headers,
+        errMessage,
+      );
 
       const err = this.makeStatusError(response.status, errJSON, errMessage, response.headers);
       throw err;

src/internal/parse.ts

@@ -1,8 +1,9 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { debug } from './utils/log';
-import { FinalRequestOptions } from './request-options';
+import type { FinalRequestOptions } from './request-options';
 import { Stream } from '../streaming';
+import { type OpenAI } from '../client';
+import { logger } from './utils/log';
 import type { AbstractPage } from '../pagination';
 
 export type APIResponseProps = {
@@ -11,10 +12,13 @@ export type APIResponseProps = {
   controller: AbortController;
 };
 
-export async function defaultParseResponse<T>(props: APIResponseProps): Promise<WithRequestID<T>> {
+export async function defaultParseResponse<T>(
+  client: OpenAI,
+  props: APIResponseProps,
+): Promise<WithRequestID<T>> {
   const { response } = props;
   if (props.options.stream) {
-    debug('response', response.status, response.url, response.headers, response.body);
+    logger(client).debug('response', response.status, response.url, response.headers, response.body);
 
     // Note: there is an invariant here that isn't represented in the type system
     // that if you set `stream: true` the response type must also be `Stream<T>`
@@ -41,13 +45,13 @@ export async function defaultParseResponse<T>(props: APIResponseProps): Promise<
   if (isJSON) {
     const json = await response.json();
 
-    debug('response', response.status, response.url, response.headers, json);
+    logger(client).debug('response', response.status, response.url, response.headers, json);
 
     return addRequestID(json as T, response);
   }
 
   const text = await response.text();
-  debug('response', response.status, response.url, response.headers, text);
+  logger(client).debug('response', response.status, response.url, response.headers, text);
 
   // TODO handle blob, arraybuffer, other content types, etc.
   return text as unknown as WithRequestID<T>;

src/internal/utils/log.ts

@@ -1,9 +1,49 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { readEnv } from './env';
+import type { LogLevel, Logger } from '../../client';
+import { type OpenAI } from '../../client';
 
-export function debug(action: string, ...args: any[]) {
-  if (readEnv('DEBUG') === 'true') {
-    console.log(`OpenAI:DEBUG:${action}`, ...args);
+const levelNumbers = {
+  off: 0,
+  error: 200,
+  warn: 300,
+  info: 400,
+  debug: 500,
+};
+
+function noop() {}
+
+function logFn(logger: Logger | undefined, clientLevel: LogLevel | undefined, level: keyof Logger) {
+  if (!logger || levelNumbers[level] > levelNumbers[clientLevel!]!) {
+    return noop;
+  } else {
+    // Don't wrap logger functions, we want the stacktrace intact!
+    return logger[level].bind(logger);
+  }
+}
+
+let lastLogger: { deref(): Logger } | undefined;
+let lastLevel: LogLevel | undefined;
+let lastLevelLogger: Logger;
+
+export function logger(client: OpenAI): Logger {
+  let { logger, logLevel: clientLevel } = client;
+  if (lastLevel === clientLevel && (logger === lastLogger || logger === lastLogger?.deref())) {
+    return lastLevelLogger;
   }
+  const levelLogger = {
+    error: logFn(logger, clientLevel, 'error'),
+    warn: logFn(logger, clientLevel, 'warn'),
+    info: logFn(logger, clientLevel, 'info'),
+    debug: logFn(logger, clientLevel, 'debug'),
+  };
+  const { WeakRef } = globalThis as any;
+  lastLogger =
+    logger ?
+      WeakRef ? new WeakRef(logger)
+      : { deref: () => logger }
+    : undefined;
+  lastLevel = clientLevel;
+  lastLevelLogger = levelLogger;
+  return levelLogger;
 }

src/pagination.ts

@@ -1,10 +1,10 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import type { OpenAI } from './client';
 import { OpenAIError } from './error';
 import { FinalRequestOptions } from './internal/request-options';
 import { defaultParseResponse, WithRequestID } from './internal/parse';
 import { APIPromise } from './api-promise';
+import { type OpenAI } from './client';
 import { type APIResponseProps } from './internal/parse';
 import { maybeObj } from './internal/utils/values';
 
@@ -86,12 +86,13 @@ export class PagePromise<
     Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
   ) {
     super(
+      client,
       request,
-      async (props) =>
+      async (client, props) =>
         new Page(
           client,
           props.response,
-          await defaultParseResponse(props),
+          await defaultParseResponse(client, props),
           props.options,
         ) as WithRequestID<PageClass>,
     );