The GalileoLogger class provides the most granular control over logging in Galileo. You can create a logger yourself, or use one from the current context from inside a decorated or wrapped function or when using a third-party SDK integration.

​
Overview

The GalileoLogger class allows you to:

  • Start sessions
  • Manually create and manage traces
  • Add spans of different types to your traces
  • Control exactly what data gets logged
  • Explicitly manage when traces are flushed to Galileo

This approach requires more code than using wrappers or decorators but gives you the most control over the logging process.

Python SDK reference

The full SDK reference for the GalileoLogger Python class.

TypeScript SDK reference

The full SDK reference for the GalileoLogger TypeScript class.

​
Basic Usage

Here’s a simple example of using the GalileoLogger to log an LLM call:

from galileo import GalileoLogger

# Create a logger instance
logger = GalileoLogger()

# Start a session
session_id = logger.start_session(name="Test session")

# Start a new trace
trace = logger.start_trace("Say this is a test")

# Add an LLM span to the trace
logger.add_llm_span(
    input="Say this is a test",
    output="Hello, this is a test",
    model="gpt-4o",
    num_input_tokens=10,
    num_output_tokens=3,
    total_tokens=13,
    duration_ns=1000,
)

# Conclude the trace with the final output
logger.conclude(output="Hello, this is a test", duration_ns=1000)

# Flush the trace to Galileo
logger.flush()

This example:

  1. Starts a new session
  2. Starts a trace inside the session
  3. Adds an LLM span to the trace
  4. Concludes the trace
  5. Flushes the logger to send the session to Galileo

​
Detailed API

​
Initialization

from galileo import GalileoLogger

# Initialize with default settings (uses environment variables)
logger = GalileoLogger()

# Or specify project and log stream
logger = GalileoLogger(
    project="my-project",
    log_stream="my-log-stream"
)

See the GalileoLogger Python SDK docs or TypeScript SDK docs for more details.

​
Get the current logger from the current context

The Galileo context management keeps track of loggers. You can get the current logger, which will create a new one if there isn’t an existing logger.

from galileo import galileo_context

# Get the current logger
logger = galileo_context.get_logger_instance()

If you are using any of the decorators, wrappers, or third-party integrations then this allows you to get the logger created by those components. For example, if you are adding a call inside a method decorated by the Python @log decorator, wrapped in the TypeScript log wrapper, or created automatically by an experiment, then this will return that logger instance so you can manually add additional spans.

from galileo import log, galileo_context

@log(span_type="llm")
def logged_function(input_text):
    # Get the current logger
    logger = galileo_context.get_logger_instance()

    # Add a span
    workflow_span = logger.add_workflow_span(
        input="My workflow"
    )

See the galileo_context Python SDK docs or getLogger TypeScript SDK docs for more details.

​
Manage Sessions

All traces live inside a session. If you don’t create a session, then one is created automatically with a generated name.

​
Start a Session

You can start a new session, providing a name and an external ID.

session_id = logger.start_session(name="My session"
                                  external_id="chat-1")

The name and external ID fields are optional. If you want to connect a session to another ID that you are using internally, for example a unique id for a chatbot conversation, then you can set this in the external ID field.

See the start_session Python SDK docs or startSession TypeScript SDK docs for more details.

​
Continue an Existing Session

If you want to add a trace to an existing session, you can set the current session for the logger, passing the session Id. This is useful if you want to persist a session, for example saving a chatbot conversation with a user mid conversation, then resuming the next time a user connects.

logger.set_session(session_id=my_session_id)

See the set_session Python SDK docs or setSession TypeScript SDK docs for more details.

You can also continue a conversation using an external ID using the start session function.

session_id = logger.start_session(external_id=conversation_id)

​
End a Session

To stop logging to a session, you can clear the current session.

logger.clear_session()

See the clear_session Python SDK docs or clearSession TypeScript SDK docs for more details.

​
Start a Trace

Once a trace is started, all spans added to that logger will be added to that trace.

# Start a basic trace
trace = logger.start_trace(input="User query")

# Start a trace with additional metadata
trace = logger.start_trace(
    input="User query",
    name="User Interaction",
    tags=["production", "user-123"],
    metadata={"session_id": "abc123", "user_id": "user-456"},
    duration_ns=1000000,  # Optional duration in nanoseconds
    created_at=datetime.now()  # Optional creation timestamp
)

See the start_trace Python SDK docs or startTrace TypeScript SDK docs for more details.

​
Add Spans

The GalileoLogger supports adding different types of spans to your traces. All spans take the input and output, as well as a name, duration, tags, and other metadata.

Span TypeDescription
AgentA span for logging agent actions. You can specify the agent type, for example a supervisor, planner, router, or judge.
LLMA span for logging calls to an LLM. You can specify the number of tokens, time to first token, temperature, model, and any tools.
RetrieverA span for logging RAG actions. In the output for this span you can provide all the data returned from the RAG platform for evaluating your RAG processing,
ToolA span for logging calls to tools. You can specify the tool call ID to tie to an LLM tool call.
WorkflowWorkflow spans are for creating logical groupings of spans based on different flows in your app.

You can read more about spans including how and when to use the different types in out Spans documentation.

​
Agent Spans

Agent spans are for logging the input and output to agents of different types. The type of agent can be set when creating the span, such as supervisor or planner.

from galileo_core.schemas.logging.agent import AgentType

logger.add_agent_span(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    name="Capital Query",  # Optional name
    duration_ns=1000000,  # Optional duration in nanoseconds
    metadata={"temperature": "0.7"},  # Optional metadata
    tags=["geography"],  # Optional tags
    agent_type=AgentType.planner
)

See the add_agent_span Python SDK docs or addAgentSpan TypeScript SDK docs for more details.

​
LLM Spans

LLM spans are for logging calls to LLMs. You can log the input and output, tools, and details like input and output tokens.

logger.add_llm_span(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    model="gpt-4o",
    tools=None,  # Optional list of tools used
    name="Capital Query",  # Optional name
    duration_ns=1000000,  # Optional duration in nanoseconds
    metadata={"temperature": "0.7"},  # Optional metadata
    tags=["geography"],  # Optional tags
    num_input_tokens=10,  # Optional token counts
    num_output_tokens=5,
    total_tokens=15,
    temperature=0.7,  # Optional model parameters
    status_code=200,  # Optional status code
    time_to_first_token_ns=500000  # Optional time to first token
)

See the add_llm_span Python SDK docs or addLlmSpan TypeScript SDK docs for more details.

​
Retriever Spans

Retriever spans are for logging calls to RAG systems. You can log the output from the RAG system to evaluate metrics like Context Adherence.

logger.add_retriever_span(
    input="Query about Roman history",
    output=["Rome was founded in 753 BC...", "The Roman Empire reached its peak..."],
    name="History Retrieval",  # Optional
    duration_ns=500000,  # Optional
    metadata={"source": "history_db"},  # Optional
    tags=["history"],  # Optional
    status_code=200  # Optional
)

See the add_retriever_span Python SDK docs or addRetrieverSpan TypeScript SDK docs for more details.

​
Tool Spans

Tool spans log calls to tools.

logger.add_tool_span(
    input=json.dumps({"operation": "add", "numbers": [1, 2, 3]}),
    output=json.dumps({"result": 6}),
    name="Calculator",  # Optional
    duration_ns=100000,  # Optional
    metadata={"tool_version": "1.0"},  # Optional
    tags=["math"],  # Optional
    status_code=200,  # Optional
    tool_call_id="tool-123"  # Optional
)

See the add_tool_span Python SDK docs or addToolSpan TypeScript SDK docs for more details.

​
Workflow Spans

Workflow spans allow you to group spans into separate workflows for easier monitoring.

# Start a workflow span
workflow_span = logger.add_workflow_span(
    input="Process user request",
    output=None,  # Can be set later
    name="Main Process",  # Optional
    duration_ns=None,  # Optional, can be set later
    metadata={"workflow_type": "user_request"},  # Optional
    tags=["workflow"]  # Optional
)

# Later, you can conclude the workflow span when concluding the trace

See the add_workflow_span Python SDK docs or addWorkflowSpan TypeScript SDK docs for more details.

​
Conclude

When you have finished logging a trace, you can conclude it with the final output. This ends the trace, and a new trace needs to be created to continue logging. The wrappers and third-party integrations will conclude traces for you.

# Conclude the trace with the final output
logger.conclude(
    output="Final response to the user",
    duration_ns=2000000,  # Optional duration in nanoseconds
    status_code=200,  # Optional status code
    conclude_all=False  # Whether to conclude all open spans
)

See the conclude Python SDK docs or conclude TypeScript SDK docs for more details.

​
Flush

Logs are not continuously sent to Galileo to help your application stay performant. You can flush logs when you are ready. The wrappers and third-party integrations will flush logs for you at the end of each trace.

# Flush the trace to Galileo
logger.flush()

See the flush Python SDK docs or flush TypeScript SDK docs for more details.

The flush call on the logger will just flush that specific logger. To flush all loggers, you can flush at the context level.

from galileo import galileo_context

# Flush the logger for the current project and log stream
galileo_context.flush()

# Flush all loggers across all projects and log streams
galileo_context.flush_all()

​
Advanced Usage

​
Create a Single LLM Span Trace

For simple LLM calls, you can create a trace with a single LLM span in one step:

logger.add_single_llm_span_trace(
    input="What is the capital of France?",
    output="The capital of France is Paris.",
    model="gpt-4o",
    tools=None,
    name="Capital Query",
    duration_ns=1000000,
    metadata={"temperature": "0.7"},
    tags=["geography"],
    num_input_tokens=10,
    num_output_tokens=5,
    total_tokens=15
)

See the add_single_llm_span_trace Python SDK docs or addSingleLlmSpanTrace TypeScript SDK docs for more details.

​
Complex Trace Example

Here’s an example of creating a more complex trace with multiple spans:

from galileo import GalileoLogger
from datetime import datetime

logger = GalileoLogger(project="my-project", log_stream="my-log-stream")

# Start a trace for a user query
trace = logger.start_trace(
    input="Who's a good bot?",
    name="User Query",
    tags=["bot-interaction"]
)

# Add a retriever span for document retrieval
logger.add_retriever_span(
    input="Who's a good bot?",
    output=["Research shows that I am a good bot."],
    name="Document Retrieval",
    duration_ns=1000000
)

# Add an LLM span for generating a response
logger.add_llm_span(
    input="Who's a good bot?",
    output="I am!",
    model="gpt-4o",
    name="Response Generation",
    num_input_tokens=25,
    num_output_tokens=3,
    total_tokens=28,
    duration_ns=1000000
)

# Conclude the trace
logger.conclude(output="I am!", duration_ns=2000000)

# Flush the trace to Galileo
logger.flush()

​
Best Practices

  1. Use higher-level abstractions when possible: The @log decorator and wrappers are easier to use and less error-prone.
  2. Flush traces when appropriate: Call flush() at the end of a request or user interaction to ensure data is sent to Galileo.
  3. Include relevant metadata: Add tags and metadata to make it easier to filter and analyze your traces.
  4. Structure spans logically: Create a span hierarchy that reflects the logical structure of your application.
  5. Handle errors gracefully: Include status codes and error information in your spans to help with debugging.

​
Next steps

​
Basic logging components

Log decorator

Quickly add logging to your code with the log decorator and wrapper.

Galileo context

Manage logging using the Galileo context manager.

​
Integrations with third-party SDKs

OpenAI wrapper

Automatically log calls to the OpenAI SDK with a wrapper.

OpenAI Agents trace processor

Automatically log all the steps in your OpenAI agent SDK apps using the Galileo trace processor.

LangChain callback

Automatically log all the steps in your LangChain or LangGraph application with the Galileo callback.