Logging basics

Log streams are the core building blocks used for evaluations. Log streams belong to a project, with one project containing one or more log streams. The way you structure this varies depending on your organizational preferences or standards, but a typical model would be:

• A project represents a distinct application. For example - a customer facing chatbot and an internal HR chatbot would be 2 separate projects.
• A log stream represents a distinct environment in that project that you want to monitor. For example, a dev log stream for your development work, a staging log stream for your staging environment, and a production log stream for your production application.

This allows you to evaluate each separate deployment of each application separately, such as to compare changed in your staging environment to production before a rollout, or to add different metrics to a dev environment to reflect new capabilities.

​

Structure of log streams

When logging applications, log streams are made up of zero or more sessions, which are in turn made up of traces, which contain spans. Experiments can be thought of as a single session, containing multiple traces made up of spans.

• Sessions represent logical groupings of traces for actions involving an AI that may contain multiple steps. For example, in a chatbot, the entire conversation with a single user would be a session.
• Traces represent one complete interaction with an AI that may contain multiple calls and interactions. For example, inside a chatbot app sending a single message, having the AI handle it using tool calls or RAG, then returning a response, would be a single trace.
• Spans represent distinct operations inside a trace. Each LLM call, tool call, or step in an agentic workflow would be an individual span. For example, in a chatbot app the initial message sent to the LLM, calls to tools based off the LLM response, follow and up LLM calls would all be separate spans.

Metrics are configured at the log stream level, allowing different metrics for different log streams.

To log to Galileo using the SDK, you use a GalileoLogger object that is configured to point to a specific project and log stream, then from there you can create sessions and traces, and add log spans to a trace. This logger can be created manually, or automatically using a range of wrappers, decorators and integrations with third party SDKs.

​

Initial setup

To log to Galileo, you need to configure a connection to Galileo using an API key and optionally a URL for a custom deployment, as well as setting the project and log stream you want to log to.

​

API key

To get started building with Galileo, you need to configure your API key, and optionally the URL of your Galileo deployment if you are using a custom hosted, or self deployed version. These are set as environment variables. In development you can use a .env file for these, for a production deployment make sure you configure these correctly for your deployment platform.

​

Project and log stream

Both the project and log stream can be configured as environment variables, or directly in code.

​

Set the project and log stream using environment variables

The advantage of using environment variables to set your project and log stream is that you can share code across deployments and configure those deployments separately, for example to share the same project but log to different log streams.

​

Set the project and log stream in code

The advantage of setting in code is you have more granular control, for example logging different parts of your application to different log streams. You can set these in code in two ways - set it at the context level so that it is shared by all logging calls, or set it at an individual logger level.

To set at the context level, use this code. After running this code, every trace will go to the specified log stream for the specified project.

from galileo import galileo_context

galileo_context.init(project="my-project",log_stream="my-log-stream")

To set the project and log stream for a single logger, you can pass it to the logger constructor.

from galileo import GalileoLogger

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

You can also use the current context to get a logger for a particular project and log stream.

from galileo import galileo_context

logger = galileo_context.get_logger_instance(project="my-project", log_stream="my-log-stream")

If you are using experiments, you can set the project name in the call to run the experiment, and the log stream name is generated for you. Learn more in our experiment SDK docs.

​

Logging flow

The typical logging flow follows these steps:

Starting sessions is optional - if you don’t start a session, then all traces are automatically each logged to new autogenerated sessions.

Using the Galileo SDK you can either do all these steps manually, or you can use a range of wrappers, decorators and integrations with third-party SDKs, where most of this is handled for you.

​

Logging components

Galileo provides 3 ways to log your application code:

• The Galileo Logger - You can create a logger, and manually manage sessions, traces, spans and more. This logger can be passed around your application to create traces and add spans as needed.
• log decorator - You can decorate or wrap functions with the log decorator to have spans created automatically. If you don’t have an active session or trace, one will be created. You can also access the logger used by the decorator for manual control.
• Third-party integrations - Galileo integrates SDKs like the OpenAI SDK, the OpenAI Agents SDK, and LangChain/LangGraph. These integrations manage logging for you, automatically creating sessions, traces and spans as needed.

In addition, there is a Galileo context manager that provides top level control over logging, such as setting the project and log stream, flushing all loggers, and managing sessions.

All the logging methods can be mixed and matched, and combined with the Galileo Context.

For example:

• In a chatbot app using LangGraph, you can start sessions for each distinct user conversation with the Galileo context, then have the Galileo LangGraph callback log each chat message as a separate trace automatically.
• In an agentic app, you can wrap top level calls with the log decorator to start a trace, access the log that was created by the decorator to add workflow spans, then have spans added automatically under these workflow spans using the OpenAI Agents SDK integration.

​

Next steps

​

Basic logging components

​

Integrations with third-party SDKs