Class: MaximLogger
Defined in: src/lib/logger/logger.ts:39 Main logger class for the Maxim SDK providing comprehensive observability capabilities. Manages the entire lifecycle of capturing, storing, and sending logs to the Maxim backend. Supports distributed logging and provides methods for logging sessions, traces, generations, tool calls, retrievals, and other observability events. Essential for monitoring AI applications and understanding system behavior. MaximLoggerExample
Constructors
Constructor
new MaximLogger(Defined in: src/lib/logger/logger.ts:65 Creates a new MaximLogger instance.params):MaximLogger
Parameters
params
Configuration parameters for the loggerapiKey
string
API key for authenticating with Maxim backend
baseUrl
string
Base URL for the Maxim API
cache
MaximCache
Cache implementation for distributed logging
config
LoggerConfig
Logger configuration including ID and flush settings
isDebug?
boolean
Enable debug mode for additional logging
raiseExceptions
boolean
Whether to raise exceptions or log them
Returns
MaximLogger
Throws
When logger ID is not provided in the configurationExample
Accessors
id
Get Signature
get id(): string
Defined in: src/lib/logger/logger.ts:145
Gets the unique identifier for this logger instance.
Returns
string
The logger’s unique ID
Methods
cleanup()
cleanup():Defined in: src/lib/logger/logger.ts:164 Cleans up resources and ensures all pending logs are flushed. Should be called before application shutdown to ensure no logs are lost. Waits for all pending write operations to complete.Promise<void>
Returns
Promise<void>
Promise that resolves when cleanup is complete
Async
Example
flush()
flush(): void
Defined in: src/lib/logger/logger.ts:998
Flushes all pending logs to the backend immediately.
Forces the log writer to send all queued logs to the Maxim backend
without waiting for the automatic flush interval.
Returns
void
void
Example
generationAddMessage()
generationAddMessage(Defined in: src/lib/logger/logger.ts:532 Adds additional messages to a generation’s conversation.generationId,messages):void
Parameters
generationId
string
The unique identifier of the generation
messages
(ChatCompletionMessage | CompletionRequest)[]
Array of messages to add
Returns
void
void
Example
generationAddTag()
generationAddTag(Defined in: src/lib/logger/logger.ts:517 Adds a tag to a generation for categorization and filtering.generationId,key,value):void
Parameters
generationId
string
The unique identifier of the generation
key
string
The tag key
value
string
The tag value
Returns
void
void
Example
generationEnd()
generationEnd(Defined in: src/lib/logger/logger.ts:634 Ends a generation and records the end timestamp.generationId,data?):void
Parameters
generationId
string
The unique identifier of the generation
data?
any
Returns
void
void
Example
generationError()
generationError(Defined in: src/lib/logger/logger.ts:591 Records an error that occurred during a generation.generationId,error):void
Parameters
generationId
string
The unique identifier of the generation
error
GenerationError
Error information including message, code, and type
Returns
void
void
Example
generationEvaluate()
generationEvaluate(Defined in: src/lib/logger/logger.ts:622 Gets the evaluation methods for a generation.generationId):EvaluateContainer
Parameters
generationId
string
The unique identifier of the generation
Returns
EvaluateContainer
Evaluation methods for configuring and triggering evaluations on the generation
Example
generationMetadata()
generationMetadata(Defined in: src/lib/logger/logger.ts:608 Adds metadata to a generation for additional context and debugging.generationId,metadata):void
Parameters
generationId
string
The unique identifier of the generation
metadata
Record<string, unknown>
Key-value pairs of metadata
Returns
void
void
Example
generationResult()
generationResult(Defined in: src/lib/logger/logger.ts:574 Records the successful result of a generation and ends it.generationId,result):void
Parameters
generationId
string
The unique identifier of the generation
result
The completion result from the LLMChatCompletionResult | TextCompletionResult
Returns
void
void
Example
generationSetModel()
generationSetModel(Defined in: src/lib/logger/logger.ts:502 Updates the model being used for a generation.generationId,model):void
Parameters
generationId
string
The unique identifier of the generation
model
string
The new model name or identifier
Returns
void
void
Example
generationSetModelParameters()
generationSetModelParameters(Defined in: src/lib/logger/logger.ts:549 Updates the model parameters for a generation.generationId,modelParameters):void
Parameters
generationId
string
The unique identifier of the generation
modelParameters
Record<string, any>
Object containing model-specific parameters
Returns
void
void
Example
retrievalAddTag()
retrievalAddTag(Defined in: src/lib/logger/logger.ts:850 Adds a tag to a retrieval for categorization and filtering.retrievalId,key,value):void
Parameters
retrievalId
string
The unique identifier of the retrieval
key
string
The tag key
value
string
The tag value
Returns
void
void
Example
retrievalEnd()
retrievalEnd(Defined in: src/lib/logger/logger.ts:835 Ends a retrieval and records the end timestamp.retrievalId):void
Parameters
retrievalId
string
The unique identifier of the retrieval
Returns
void
void
Example
retrievalEvaluate()
retrievalEvaluate(Defined in: src/lib/logger/logger.ts:915 Gets the evaluation methods for a retrieval.retrievalId):EvaluateContainer
Parameters
retrievalId
string
The unique identifier of the retrieval
Returns
EvaluateContainer
Evaluation methods for configuring and triggering evaluations on the retrieval
Example
retrievalInput()
retrievalInput(Defined in: src/lib/logger/logger.ts:863 Sets the input query for a retrieval operation.retrievalId,input):void
Parameters
retrievalId
string
The unique identifier of the retrieval
input
string
The search query or input text
Returns
void
void
Example
retrievalMetadata()
retrievalMetadata(Defined in: src/lib/logger/logger.ts:901 Adds metadata to a retrieval for additional context and debugging.retrievalId,metadata):void
Parameters
retrievalId
string
The unique identifier of the retrieval
metadata
Record<string, unknown>
Key-value pairs of metadata
Returns
void
void
Example
retrievalOutput()
retrievalOutput(Defined in: src/lib/logger/logger.ts:884 Sets the output results for a retrieval operation and ends it.retrievalId,output):void
Parameters
retrievalId
string
The unique identifier of the retrieval
output
string
Retrieved documents as a single string or array
Returns
void
void
Examples
session()
session(Defined in: src/lib/logger/logger.ts:110 Creates a new session. Sessions represent high-level mutli-turn user interactions, containing multiple traces that represent individual turn interaction within that session. Useful for tracking user journeys.config):Session
Parameters
config
SessionConfig
Configuration for the session
Returns
Session
A new session instance for logging activities
Example
sessionEnd()
sessionEnd(Defined in: src/lib/logger/logger.ts:193 Ends a session and records the end timestamp.sessionId,data?):void
Parameters
sessionId
string
The unique identifier of the session
data?
any
Returns
void
void
Example
sessionEvaluate()
sessionEvaluate(Defined in: src/lib/logger/logger.ts:241 Gets the evaluation methods for a session.sessionId):EvaluateContainer
Parameters
sessionId
string
The unique identifier of the session
Returns
EvaluateContainer
Evaluation methods for configuring and triggering evaluations on the session
Example
sessionFeedback()
sessionFeedback(Defined in: src/lib/logger/logger.ts:211 Adds feedback to a session from users.sessionId,feedback):void
Parameters
sessionId
string
The unique identifier of the session
feedback
Feedback object containing score and optional commentcomment?
string
Optional textual feedback
score
number
Numerical score for the session
Returns
void
void
Example
sessionTag()
sessionTag(Defined in: src/lib/logger/logger.ts:181 Adds a tag to a session for categorization and filtering.sessionId,key,value):void
Parameters
sessionId
string
The unique identifier of the session
key
string
The tag key
value
string
The tag value
Returns
void
void
Example
sessionTrace()
sessionTrace(Defined in: src/lib/logger/logger.ts:227 Creates a new trace associated with a session.sessionId,config):Trace
Parameters
sessionId
string
The unique identifier of the session
config
TraceConfig
Configuration for the new trace
Returns
Trace
A new trace instance associated with the session
Example
spanEnd()
spanEnd(Defined in: src/lib/logger/logger.ts:821 Ends a span and records the end timestamp.spanId,data?):void
Parameters
spanId
string
The unique identifier of the span
data?
any
Returns
void
void
Example
spanError()
spanError(Defined in: src/lib/logger/logger.ts:738 Creates an error associated with a span.spanId,config):Error
Parameters
spanId
string
The unique identifier of the span
config
ErrorConfig
Configuration for the error
Returns
Error
A new error instance associated with the span
Example
spanEvaluate()
spanEvaluate(Defined in: src/lib/logger/logger.ts:809 Gets the evaluation methods for a span.spanId):EvaluateContainer
Parameters
spanId
string
The unique identifier of the span
Returns
EvaluateContainer
Evaluation methods for configuring and triggering evaluations on the span
Example
spanEvent()
Call Signature
spanEvent(Defined in: src/lib/logger/logger.ts:760 Emits a custom event within a span.spanId,eventId,eventName,tags?,metadata?):void
Parameters
spanId
string
The unique identifier of the span
eventId
string
Unique identifier for the event
eventName
string
Human-readable name for the event
tags?
Record<string, string>
Optional tags for categorizing the event
metadata?
Record<string, unknown>
Optional metadata for additional context
Returns
void
void
Example
Call Signature
spanEvent(Defined in: src/lib/logger/logger.ts:768spanId,eventName,tags?,metadata?):void
Parameters
spanId
string
eventName
string
tags?
Record<string, string>
metadata?
Record<string, unknown>
Returns
void
Deprecated
Use the method with explicit eventId and eventName insteadspanGeneration()
spanGeneration(Defined in: src/lib/logger/logger.ts:655 Creates a new generation (LLM call) associated with a span.spanId,config):Generation
Parameters
spanId
string
The unique identifier of the span
config
GenerationConfig
Configuration for the generation
Returns
Generation
A new generation instance associated with the span
Example
spanMetadata()
spanMetadata(Defined in: src/lib/logger/logger.ts:795 Adds metadata to a span for additional context and debugging.spanId,metadata):void
Parameters
spanId
string
The unique identifier of the span
metadata
Record<string, unknown>
Key-value pairs of metadata
Returns
void
void
Example
spanRetrieval()
spanRetrieval(Defined in: src/lib/logger/logger.ts:671 Creates a new retrieval associated with a span.spanId,config):Retrieval
Parameters
spanId
string
The unique identifier of the span
config
RetrievalConfig
Configuration for the retrieval
Returns
Retrieval
A new retrieval instance associated with the span
Example
spanSpan()
spanSpan(Defined in: src/lib/logger/logger.ts:705 Creates a nested span within a span for hierarchical organization.spanId,config):Span
Parameters
spanId
string
The unique identifier of the parent span
config
SpanConfig
Configuration for the nested span
Returns
Span
A new nested span instance
Example
spanTag()
spanTag(Defined in: src/lib/logger/logger.ts:720 Adds a tag to a span for categorization and filtering.spanId,key,value):void
Parameters
spanId
string
The unique identifier of the span
key
string
The tag key
value
string
The tag value
Returns
void
void
Example
spanToolCall()
spanToolCall(Defined in: src/lib/logger/logger.ts:689 Creates a new tool call associated with a span.spanId,config):ToolCall
Parameters
spanId
string
The unique identifier of the span
config
ToolCallConfig
Configuration for the tool call
Returns
ToolCall
A new tool call instance associated with the span
Example
toolCallAddTag()
toolCallAddTag(Defined in: src/lib/logger/logger.ts:966 Adds a tag to a tool call for categorization and filtering.toolCallId,key,value):void
Parameters
toolCallId
string
The unique identifier of the tool call
key
string
The tag key
value
string
The tag value
Returns
void
void
Example
toolCallError()
toolCallError(Defined in: src/lib/logger/logger.ts:951 Records an error that occurred during a tool call and ends it.toolCallId,error):void
Parameters
toolCallId
string
The unique identifier of the tool call
error
ToolCallError
Error information including message, code, and type
Returns
void
void
Example
toolCallMetadata()
toolCallMetadata(Defined in: src/lib/logger/logger.ts:983 Adds metadata to a tool call for additional context and debugging.toolCallId,metadata):void
Parameters
toolCallId
string
The unique identifier of the tool call
metadata
Record<string, unknown>
Key-value pairs of metadata
Returns
void
void
Example
toolCallResult()
toolCallResult(Defined in: src/lib/logger/logger.ts:934 Records the successful result of a tool call and ends it.toolCallId,result):void
Parameters
toolCallId
string
The unique identifier of the tool call
result
string
The result returned by the tool as a string
Returns
void
void
Example
trace()
trace(Defined in: src/lib/logger/logger.ts:136 Creates a new trace. Traces represent individual workflows or processes, containing generations, tool calls, retrievals, and other components. They provide detailed information about operations in a single conversation turn with the user.config):Trace
Parameters
config
TraceConfig
Configuration for the trace
Returns
Trace
A new trace instance for logging operations
Example
traceAddToSession()
traceAddToSession(Defined in: src/lib/logger/logger.ts:369 Associates a trace with a session.traceId,sessionId):void
Parameters
traceId
string
The unique identifier of the trace
sessionId
string
The unique identifier of the session
Returns
void
void
Example
traceEnd()
traceEnd(Defined in: src/lib/logger/logger.ts:487 Ends a trace and records the end timestamp.traceId,data?):void
Parameters
traceId
string
The unique identifier of the trace
data?
any
Returns
void
void
Example
traceError()
traceError(Defined in: src/lib/logger/logger.ts:327 Creates an error associated with a trace.traceId,config):Error
Parameters
traceId
string
The unique identifier of the trace
config
ErrorConfig
Configuration for the error
Returns
Error
A new error instance associated with the trace
Example
traceEvaluate()
traceEvaluate(Defined in: src/lib/logger/logger.ts:475 Gets the evaluation methods for a trace.traceId):EvaluateContainer
Parameters
traceId
string
The unique identifier of the trace
Returns
EvaluateContainer
Evaluation methods for configuring and triggering evaluations on the trace
Example
traceEvent()
Call Signature
traceEvent(Defined in: src/lib/logger/logger.ts:406 Emits a custom event within a trace.traceId,eventId,eventName,tags?,metadata?):void
Parameters
traceId
string
The unique identifier of the trace
eventId
string
Unique identifier for the event
eventName
string
Human-readable name for the event
tags?
Record<string, string>
Optional tags for categorizing the event
metadata?
Record<string, unknown>
Optional metadata for additional context
Returns
void
void
Example
Call Signature
traceEvent(Defined in: src/lib/logger/logger.ts:414traceId,eventName,tags?,metadata?):void
Parameters
traceId
string
eventName
string
tags?
Record<string, string>
metadata?
Record<string, unknown>
Returns
void
Deprecated
Use the method with explicit eventId and eventName insteadtraceFeedback()
traceFeedback(Defined in: src/lib/logger/logger.ts:444 Adds feedback to a trace from users.traceId,feedback):void
Parameters
traceId
string
The unique identifier of the trace
feedback
Feedback object containing score and optional commentcomment?
string
Optional textual feedback
score
number
Numerical score for the trace
Returns
void
void
Example
traceGeneration()
traceGeneration(Defined in: src/lib/logger/logger.ts:262 Creates a new generation (LLM call) associated with a trace.traceId,config):Generation
Parameters
traceId
string
The unique identifier of the trace
config
GenerationConfig
Configuration for the generation
Returns
Generation
A new generation instance associated with the trace
Example
traceInput()
traceInput(Defined in: src/lib/logger/logger.ts:340 Sets the input for a trace.traceId,input):void
Parameters
traceId
string
The unique identifier of the trace
input
string
The input that triggered this trace
Returns
void
void
Example
traceMetadata()
traceMetadata(Defined in: src/lib/logger/logger.ts:461 Adds metadata to a trace for additional context and debugging.traceId,metadata):void
Parameters
traceId
string
The unique identifier of the trace
metadata
Record<string, unknown>
Key-value pairs of metadata
Returns
void
void
Example
traceOutput()
traceOutput(Defined in: src/lib/logger/logger.ts:309 Sets the output for a trace.traceId,output):void
Parameters
traceId
string
The unique identifier of the trace
output
string
The final output or result of the trace execution
Returns
void
void
Example
traceRetrieval()
traceRetrieval(Defined in: src/lib/logger/logger.ts:296 Creates a new retrieval associated with a trace.traceId,config):Retrieval
Parameters
traceId
string
The unique identifier of the trace
config
RetrievalConfig
Configuration for the retrieval
Returns
Retrieval
A new retrieval instance associated with the trace
Example
traceSpan()
traceSpan(Defined in: src/lib/logger/logger.ts:356 Creates a new span associated with a trace.traceId,config):Span
Parameters
traceId
string
The unique identifier of the trace
config
SpanConfig
Configuration for the span
Returns
Span
A new span instance associated with the trace
Example
traceTag()
traceTag(Defined in: src/lib/logger/logger.ts:384 Adds a tag to a trace for categorization and filtering.traceId,key,value):void
Parameters
traceId
string
The unique identifier of the trace
key
string
The tag key
value
string
The tag value
Returns
void
void
Example
traceToolCall()
traceToolCall(Defined in: src/lib/logger/logger.ts:280 Creates a new tool call associated with a trace.traceId,config):ToolCall
Parameters
traceId
string
The unique identifier of the trace
config
ToolCallConfig
Configuration for the tool call
Returns
ToolCall
A new tool call instance associated with the trace