Class ObservabilityAPI

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

Hierarchy

BasePaymentsAPI
- ObservabilityAPI

Constructors

constructor

new ObservabilityAPI(options: PaymentOptions): ObservabilityAPI
Parameters
- options: PaymentOptions
Returns ObservabilityAPI
Overrides BasePaymentsAPI.constructor
- Defined in src/api/observability-api/observability-api.ts:372

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`scheme

scheme: PaymentScheme

`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;
}
- Defined in src/api/observability-api/observability-api.ts:561

calculateImageUsage

calculateImageUsage(
    pixels: number,
): {
    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;
}
- Defined in src/api/observability-api/observability-api.ts:540

calculateSongUsage

calculateSongUsage(
    tokens: number,
): {
    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;
}
- Defined in src/api/observability-api/observability-api.ts:554

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;
}
- Defined in src/api/observability-api/observability-api.ts:547

createHeliconePayload

createHeliconePayload(
    config: HeliconePayloadConfig,
): {
    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;
}
- Defined in src/api/observability-api/observability-api.ts:568

createHeliconeResponse

createHeliconeResponse(
    config: HeliconeResponseConfig,
): {
    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;
    };
}
- Defined in src/api/observability-api/observability-api.ts:575

getAccountAddress

getAccountAddress(): string | undefined
It returns the account address associated with the NVM API Key used to initialize the Payments Library instance.

Returns string | undefined
The account address extracted from the NVM API Key
Inherited from BasePaymentsAPI.getAccountAddress
- Defined in src/api/base-payments.ts:73

`Protected`getBackendHTTPOptions

getBackendHTTPOptions(method: string, body?: any): any
Internal
Returns the HTTP options required to query the backend.
Parameters
- method: string
  HTTP method.
- Optionalbody: any
  Optional request body.
Returns any
HTTP options object.
Inherited from BasePaymentsAPI.getBackendHTTPOptions
- Defined in src/api/base-payments.ts:84

getEnvironmentName

getEnvironmentName(): EnvironmentName
Returns the environment name used to initialize the Payments instance.

Returns EnvironmentName
The environment name (e.g. 'sandbox', 'live')
Inherited from BasePaymentsAPI.getEnvironmentName
- Defined in src/api/base-payments.ts:65

`Protected`getPublicHTTPOptions

getPublicHTTPOptions(
    method: string,
    body?: any,
): {
    body?: string;
    headers: { Accept: string; "Content-Type": string };
    method: string;
}
Internal
Get HTTP options for public backend requests (no authorization header). Converts body keys from snake_case to camelCase for consistency.
Parameters
- method: string
  HTTP method
- Optionalbody: any
  Optional request body (keys will be converted to camelCase)
Returns {
    body?: string;
    headers: { Accept: string; "Content-Type": string };
    method: string;
}
HTTP options object
Inherited from BasePaymentsAPI.getPublicHTTPOptions
- Defined in src/api/base-payments.ts:105

`Protected`parseNvmApiKey

parseNvmApiKey(): { accountAddress: string; heliconeApiKey: string }
Parses the NVM API Key to extract the account address.

Returns { accountAddress: string; heliconeApiKey: string }
Throws
PaymentsError if the API key is invalid.
Inherited from BasePaymentsAPI.parseNvmApiKey
- Defined in src/api/base-payments.ts:47

withAsyncLogger

withAsyncLogger(
    providers: AsyncLoggerProviders,
    agentRequest: StartAgentRequest,
    customProperties?: 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
- OptionalcustomProperties: CustomProperties
  Custom properties to add as Helicone headers
Returns { init: () => void }
The async logger instance with init() method
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({ ... });
```
- Defined in src/api/observability-api/observability-api.ts:522

withHeliconeLogging

withHeliconeLogging<TInternal = any, TExtracted = any>(
    agentName: string,
    payloadConfig: HeliconePayloadConfig,
    operation: () => Promise<TInternal>,
    resultExtractor: (internalResult: TInternal) => TExtracted,
    usageCalculator: (
        internalResult: TInternal,
    ) => {
        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;
    },
    responseIdPrefix: string,
    startAgentRequest: StartAgentRequest,
    customProperties: 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: TInternal) => TExtracted
  Function to extract the user-facing result from internal result
- usageCalculator: (
      internalResult: TInternal,
  ) => {
      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
- 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
- Defined in src/api/observability-api/observability-api.ts:417

withLangchain

withLangchain(
    model: string,
    apiKey: string,
    startAgentRequest: StartAgentRequest,
    customProperties: 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
- Defined in src/api/observability-api/observability-api.ts:454

withOpenAI

withOpenAI(
    apiKey: string,
    agentRequest: StartAgentRequest,
    customProperties: 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
- Defined in src/api/observability-api/observability-api.ts:482

`Static`getInstance

getInstance(options: PaymentOptions): ObservabilityAPI
This method is used to create a singleton instance of the ObservabilityAPI class.
Parameters
- options: PaymentOptions
  The options to initialize the payments class.
Returns ObservabilityAPI
The instance of the ObservabilityAPI class.
- Defined in src/api/observability-api/observability-api.ts:400

Class ObservabilityAPI

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns ObservabilityAPI

Properties

ProtectedaccountAddress

Protected OptionalappId

Protectedenvironment

ProtectedenvironmentName

ProtectedheliconeApiKey

Protected ReadonlyheliconeAsyncLoggingUrl

Protected ReadonlyheliconeBaseLoggingUrl

Protected ReadonlyheliconeManualLoggingUrl

isBrowserInstance

ProtectednvmApiKey

ProtectedreturnUrl

Protectedscheme

Protected Optionalversion

Methods

calculateDummySongUsage

calculateImageUsage

Parameters

calculateSongUsage

Parameters

calculateVideoUsage

createHeliconePayload

Parameters

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

createHeliconeResponse

Parameters

getAccountAddress

Returns string | undefined

ProtectedgetBackendHTTPOptions

Parameters

Returns any

getEnvironmentName

Returns EnvironmentName

ProtectedgetPublicHTTPOptions

Parameters

Returns { body?: string; headers: { Accept: string; "Content-Type": string }; method: string;}

ProtectedparseNvmApiKey

Returns { accountAddress: string; heliconeApiKey: string }

Throws

withAsyncLogger

Parameters

Returns { init: () => void }

Example

withHeliconeLogging

Type Parameters

Parameters

Returns Promise<TExtracted>

withLangchain

Parameters

Returns ChatOpenAIConfiguration

withOpenAI

Parameters

Returns OpenAIConfiguration

StaticgetInstance

Parameters

Returns ObservabilityAPI

Settings

On This Page

`Protected`accountAddress

`Protected` `Optional`appId

`Protected`environment

`Protected`environmentName

`Protected`heliconeApiKey

`Protected` `Readonly`heliconeAsyncLoggingUrl

`Protected` `Readonly`heliconeBaseLoggingUrl

`Protected` `Readonly`heliconeManualLoggingUrl

`Protected`nvmApiKey

`Protected`returnUrl

`Protected`scheme

`Protected` `Optional`version

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

`Protected`getBackendHTTPOptions

`Protected`getPublicHTTPOptions

Returns {
body?: string;
headers: { Accept: string; "Content-Type": string };
method: string;
}

`Protected`parseNvmApiKey

`Static`getInstance