Class ObservabilityAPI

The ObservabilityAPI class provides methods to wrap API calls with Helicone logging

Hierarchy

  • BasePaymentsAPI
    • ObservabilityAPI

Constructors

constructor

Properties

accountAddress appId? environment environmentName heliconeApiKey heliconeAsyncLoggingUrl heliconeBaseLoggingUrl heliconeManualLoggingUrl isBrowserInstance nvmApiKey returnUrl version?

Methods

calculateDummySongUsage calculateImageUsage calculateSongUsage calculateVideoUsage createHeliconePayload createHeliconeResponse getAccountAddress getBackendHTTPOptions parseNvmApiKey withAsyncLogger withHeliconeLogging withLangchain withOpenAI getInstance

Constructors

constructor

Properties

Protected accountAddress

accountAddress: string

Protected Optional appId

appId?: string

Protected environment

environment: EnvironmentInfo

Protected environmentName

environmentName: EnvironmentName

Protected heliconeApiKey

heliconeApiKey: string

Protected Readonly heliconeAsyncLoggingUrl

heliconeAsyncLoggingUrl: string

Protected Readonly heliconeBaseLoggingUrl

heliconeBaseLoggingUrl: string

Protected Readonly heliconeManualLoggingUrl

heliconeManualLoggingUrl: string

isBrowserInstance

isBrowserInstance: boolean = true

Protected nvmApiKey

nvmApiKey: string

Protected returnUrl

returnUrl: string

Protected Optional version

version?: string

Methods

calculateDummySongUsage

  • calculateDummySongUsage(): {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

  • Helper function to calculate usage for dummy song operations

    Returns {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

    • completion_tokens: number
    • Optional completion_tokens_details?: {
          accepted_prediction_tokens: number;
          audio_tokens: number;
          reasoning_tokens: number;
          rejected_prediction_tokens: number;
      }
      • accepted_prediction_tokens: number
      • audio_tokens: number
      • reasoning_tokens: number
      • rejected_prediction_tokens: number
    • prompt_tokens: number
    • Optional prompt_tokens_details?: {
          audio_tokens: number;
          cached_tokens: number;
      }
      • audio_tokens: number
      • cached_tokens: number
    • total_tokens: number

calculateImageUsage

  • calculateImageUsage(pixels): {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

  • Helper function to calculate usage for image operations based on pixels

    Parameters

    • pixels: number

    Returns {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

    • completion_tokens: number
    • Optional completion_tokens_details?: {
          accepted_prediction_tokens: number;
          audio_tokens: number;
          reasoning_tokens: number;
          rejected_prediction_tokens: number;
      }
      • accepted_prediction_tokens: number
      • audio_tokens: number
      • reasoning_tokens: number
      • rejected_prediction_tokens: number
    • prompt_tokens: number
    • Optional prompt_tokens_details?: {
          audio_tokens: number;
          cached_tokens: number;
      }
      • audio_tokens: number
      • cached_tokens: number
    • total_tokens: number

calculateSongUsage

  • calculateSongUsage(tokens): {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

  • Helper function to calculate usage for song operations based on tokens/quota

    Parameters

    • tokens: number

    Returns {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

    • completion_tokens: number
    • Optional completion_tokens_details?: {
          accepted_prediction_tokens: number;
          audio_tokens: number;
          reasoning_tokens: number;
          rejected_prediction_tokens: number;
      }
      • accepted_prediction_tokens: number
      • audio_tokens: number
      • reasoning_tokens: number
      • rejected_prediction_tokens: number
    • prompt_tokens: number
    • Optional prompt_tokens_details?: {
          audio_tokens: number;
          cached_tokens: number;
      }
      • audio_tokens: number
      • cached_tokens: number
    • total_tokens: number

calculateVideoUsage

  • calculateVideoUsage(): {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

  • Helper function to calculate usage for video operations (typically 1 token)

    Returns {
        completion_tokens: number;
        completion_tokens_details?: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        };
        prompt_tokens: number;
        prompt_tokens_details?: {
            audio_tokens: number;
            cached_tokens: number;
        };
        total_tokens: number;
    }

    • completion_tokens: number
    • Optional completion_tokens_details?: {
          accepted_prediction_tokens: number;
          audio_tokens: number;
          reasoning_tokens: number;
          rejected_prediction_tokens: number;
      }
      • accepted_prediction_tokens: number
      • audio_tokens: number
      • reasoning_tokens: number
      • rejected_prediction_tokens: number
    • prompt_tokens: number
    • Optional prompt_tokens_details?: {
          audio_tokens: number;
          cached_tokens: number;
      }
      • audio_tokens: number
      • cached_tokens: number
    • total_tokens: number

createHeliconePayload

  • createHeliconePayload(config): {
        frequency_penalty: number;
        messages: {
            content: string;
            role: string;
        }[];
        model: string;
        n: number;
        presence_penalty: number;
        stream: boolean;
        temperature: number;
        top_p: number;
    }

  • Creates a standardized Helicone payload for API logging

    Parameters

    • config: HeliconePayloadConfig

    Returns {
        frequency_penalty: number;
        messages: {
            content: string;
            role: string;
        }[];
        model: string;
        n: number;
        presence_penalty: number;
        stream: boolean;
        temperature: number;
        top_p: number;
    }

    • frequency_penalty: number
    • messages: {
          content: string;
          role: string;
      }[]
    • model: string
    • n: number
    • presence_penalty: number
    • stream: boolean
    • temperature: number
    • top_p: number

createHeliconeResponse

  • createHeliconeResponse(config): {
        choices: {
            finish_reason: string;
            index: number;
            logprobs: null;
            message: {
                annotations: never[];
                content: string;
                refusal: null;
                role: string;
            };
        }[];
        created: number;
        id: string;
        model: string;
        object: string;
        service_tier: string;
        system_fingerprint: string;
        usage: {
            completion_tokens: number;
            completion_tokens_details: {
                accepted_prediction_tokens: number;
                audio_tokens: number;
                reasoning_tokens: number;
                rejected_prediction_tokens: number;
            };
            prompt_tokens: number;
            prompt_tokens_details: {
                audio_tokens: number;
                cached_tokens: number;
            };
            total_tokens: number;
        };
    }

  • Creates a standardized Helicone response for API logging

    Parameters

    • config: HeliconeResponseConfig

    Returns {
        choices: {
            finish_reason: string;
            index: number;
            logprobs: null;
            message: {
                annotations: never[];
                content: string;
                refusal: null;
                role: string;
            };
        }[];
        created: number;
        id: string;
        model: string;
        object: string;
        service_tier: string;
        system_fingerprint: string;
        usage: {
            completion_tokens: number;
            completion_tokens_details: {
                accepted_prediction_tokens: number;
                audio_tokens: number;
                reasoning_tokens: number;
                rejected_prediction_tokens: number;
            };
            prompt_tokens: number;
            prompt_tokens_details: {
                audio_tokens: number;
                cached_tokens: number;
            };
            total_tokens: number;
        };
    }

    • choices: {
          finish_reason: string;
          index: number;
          logprobs: null;
          message: {
              annotations: never[];
              content: string;
              refusal: null;
              role: string;
          };
      }[]
    • created: number
    • id: string
    • model: string
    • object: string
    • service_tier: string
    • system_fingerprint: string
    • usage: {
          completion_tokens: number;
          completion_tokens_details: {
              accepted_prediction_tokens: number;
              audio_tokens: number;
              reasoning_tokens: number;
              rejected_prediction_tokens: number;
          };
          prompt_tokens: number;
          prompt_tokens_details: {
              audio_tokens: number;
              cached_tokens: number;
          };
          total_tokens: number;
      }
      • completion_tokens: number
      • completion_tokens_details: {
            accepted_prediction_tokens: number;
            audio_tokens: number;
            reasoning_tokens: number;
            rejected_prediction_tokens: number;
        }
        • accepted_prediction_tokens: number
        • audio_tokens: number
        • reasoning_tokens: number
        • rejected_prediction_tokens: number
      • prompt_tokens: number
      • prompt_tokens_details: {
            audio_tokens: number;
            cached_tokens: number;
        }
        • audio_tokens: number
        • cached_tokens: number
      • total_tokens: number

getAccountAddress

  • getAccountAddress(): undefined | string

  • It returns the account address associated with the NVM API Key used to initialize the Payments Library instance.

    Returns undefined | string

    The account address extracted from the NVM API Key

Protected getBackendHTTPOptions

  • getBackendHTTPOptions(method, body?): any
  • Internal

    Returns the HTTP options required to query the backend.

    Parameters

    • method: string

      HTTP method.

    • Optional body: any

      Optional request body.

    Returns any

    HTTP options object.

Protected parseNvmApiKey

  • parseNvmApiKey(): {
        accountAddress: string;
        heliconeApiKey: string;
    }

  • Parses the NVM API Key to extract the account address.

    Returns {
        accountAddress: string;
        heliconeApiKey: string;
    }

    • accountAddress: string
    • heliconeApiKey: string

    Throws

    PaymentsError if the API key is invalid.

withAsyncLogger

  • withAsyncLogger(providers, agentRequest, customProperties?): {
        init: (() => void);
    }

  • Creates an async logger with Nevermined logging enabled and automatic property injection

    This method wraps the OpenTelemetry SpanProcessor to automatically add all Helicone properties to every span. This mimics Python's Traceloop.set_association_properties() - no wrapping of individual LLM calls needed!

    Parameters

    • providers: AsyncLoggerProviders

      AI SDK modules to instrument (OpenAI, Anthropic, etc.)

    • agentRequest: StartAgentRequest

      The agent request for logging purposes

    • Optional customProperties: CustomProperties

      Custom properties to add as Helicone headers

    Returns {
        init: (() => void);
    }

    The async logger instance with init() method

    • init: (() => void)
        • (): void

        • Returns void

    Example

    import OpenAI from 'openai';

    const logger = observability.withAsyncLogger({ openAI: OpenAI }, agentRequest);
    logger.init();

    // Make LLM calls normally - properties are automatically added to all spans!
    const openai = new OpenAI({ apiKey });
    const result = await openai.chat.completions.create({ ... });

withHeliconeLogging

  • withHeliconeLogging<TInternal, TExtracted>(agentName, payloadConfig, operation, resultExtractor, usageCalculator, responseIdPrefix, startAgentRequest, customProperties): Promise<TExtracted>

  • Wraps an async operation with Helicone logging

    Type Parameters

    • TInternal = any
    • TExtracted = any

    Parameters

    • agentName: string

      Name of the agent for logging purposes

    • payloadConfig: HeliconePayloadConfig

      Configuration for the Helicone payload

    • operation: (() => Promise<TInternal>)

      The async operation to execute (returns internal result with extra data)

    • resultExtractor: ((internalResult) => TExtracted)

      Function to extract the user-facing result from internal result

    • usageCalculator: ((internalResult) => {
          completion_tokens: number;
          completion_tokens_details?: {
              accepted_prediction_tokens: number;
              audio_tokens: number;
              reasoning_tokens: number;
              rejected_prediction_tokens: number;
          };
          prompt_tokens: number;
          prompt_tokens_details?: {
              audio_tokens: number;
              cached_tokens: number;
          };
          total_tokens: number;
      })

      Function to calculate usage metrics from the internal result

        • (internalResult): {
              completion_tokens: number;
              completion_tokens_details?: {
                  accepted_prediction_tokens: number;
                  audio_tokens: number;
                  reasoning_tokens: number;
                  rejected_prediction_tokens: number;
              };
              prompt_tokens: number;
              prompt_tokens_details?: {
                  audio_tokens: number;
                  cached_tokens: number;
              };
              total_tokens: number;
          }

        • Parameters

          Returns {
              completion_tokens: number;
              completion_tokens_details?: {
                  accepted_prediction_tokens: number;
                  audio_tokens: number;
                  reasoning_tokens: number;
                  rejected_prediction_tokens: number;
              };
              prompt_tokens: number;
              prompt_tokens_details?: {
                  audio_tokens: number;
                  cached_tokens: number;
              };
              total_tokens: number;
          }

          • completion_tokens: number
          • Optional completion_tokens_details?: {
                accepted_prediction_tokens: number;
                audio_tokens: number;
                reasoning_tokens: number;
                rejected_prediction_tokens: number;
            }
            • accepted_prediction_tokens: number
            • audio_tokens: number
            • reasoning_tokens: number
            • rejected_prediction_tokens: number
          • prompt_tokens: number
          • Optional prompt_tokens_details?: {
                audio_tokens: number;
                cached_tokens: number;
            }
            • audio_tokens: number
            • cached_tokens: number
          • total_tokens: number
    • responseIdPrefix: string

      Prefix for the response ID

    • startAgentRequest: StartAgentRequest

      The agent request for logging purposes

    • customProperties: CustomProperties

      Custom properties to add as Helicone headers (should include agentid and sessionid)

    Returns Promise<TExtracted>

    Promise that resolves to the extracted user result

withLangchain

  • withLangchain(model, apiKey, startAgentRequest, customProperties): ChatOpenAIConfiguration

  • Creates a ChatOpenAI configuration with logging enabled

    Usage: const llm = new ChatOpenAI(observability.withLangchain("gpt-4o-mini", apiKey, agentRequest, customProperties));

    Parameters

    • model: string

      The OpenAI model to use (e.g., "gpt-4o-mini", "gpt-4")

    • apiKey: string

      The OpenAI API key

    • startAgentRequest: StartAgentRequest
    • customProperties: CustomProperties

      Custom properties to add as Helicone headers (should include agentid and sessionid)

    Returns ChatOpenAIConfiguration

    Configuration object for ChatOpenAI constructor with logging enabled

withOpenAI

  • withOpenAI(apiKey, agentRequest, customProperties): OpenAIConfiguration

  • Creates an OpenAI client configuration with logging enabled

    Usage: const openai = new OpenAI(observability.withOpenAI(apiKey, heliconeApiKey, agentRequest, customProperties));

    Parameters

    • apiKey: string

      The OpenAI API key

    • agentRequest: StartAgentRequest

      The agent request for logging purposes

    • customProperties: CustomProperties

      Custom properties to add as Helicone headers (should include agentid and sessionid)

    Returns OpenAIConfiguration

    Configuration object for OpenAI constructor with logging enabled

Static getInstance

Settings

Member Visibility

Theme

On This Page

constructoraccountAddressappIdenvironmentenvironmentNameheliconeApiKeyheliconeAsyncLoggingUrlheliconeBaseLoggingUrlheliconeManualLoggingUrlisBrowserInstancenvmApiKeyreturnUrlversioncalculateDummySongUsagecalculateImageUsagecalculateSongUsagecalculateVideoUsagecreateHeliconePayloadcreateHeliconeResponsegetAccountAddressgetBackendHTTPOptionsparseNvmApiKeywithAsyncLoggerwithHeliconeLoggingwithLangchainwithOpenAIgetInstance