The @log decorator provides a simple way to capture the inputs and outputs of a function as a span within a trace. This is particularly useful for tracking the execution of your AI application without having to manually create and manage spans.

​
Overview

When you decorate a function with @log, Galileo automatically:

  • Captures the function’s input arguments
  • Tracks the function’s execution
  • Records the function’s return value
  • Creates an appropriate span in the current trace

This approach is less automatic than using wrappers but more flexible, as you can decorate any function in your codebase, not just LLM calls.

​
Basic Usage

To use the @log decorator, simply import it from the Galileo package and apply it to your functions:

from galileo import log

@log
def my_function(input_text):
    # Your function logic here
    result = process_data(input_text)
    return result

# When called, this function will be automatically logged
response = my_function("Some input text")

​
Span Types

By default, the @log decorator creates a workflow span, but you can specify different span types depending on what your function does:

from galileo import log

# Create a workflow span (default)
@log
def my_workflow_function(input):
    # This can contain multiple steps and child spans
    return result

# Create an LLM span
@log(span_type="llm")
def my_llm_function(input):
    # This should be for direct LLM calls
    return result

# Create a retriever span
@log(span_type="retriever")
def my_retriever_function(query):
    # For functions that retrieve documents
    # If the output is an array, it will be captured as documents
    return ["doc1", "doc2"]

# Create a tool span
@log(span_type="tool")
def my_tool_function(input="tool call input"):
    # For functions that act as tools in an agent system
    return "tool call output"

​
Span Type Descriptions

  • Workflow: A span that can have child spans, useful for nesting several child spans to denote a thread within a trace. If you add the @log decorator to a parent method, calls that are made within that scope are automatically logged in the same trace.
  • Llm: Captures the input, output, and settings of an LLM call. This span gets automatically created when our client library wrappers (OpenAI and Anthropic) are used. Cannot have nested children.
  • Retriever: Contains the output documents of a retrieval operation. Useful for tracking what documents were retrieved in RAG applications.
  • Tool: Captures the input and output of a tool call. Used to decorate functions that are invoked as tools in agent-based systems.

​
Nested Spans Example

One of the most powerful features of the @log decorator is its ability to create nested spans, which helps visualize the flow of your application:

import os
from galileo import log
from galileo.openai import openai

client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def call_openai(prompt):
    # This will be automatically logged as a child span
    chat_completion = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return chat_completion.choices[0].message.content

@log
def make_nested_call():
    # This creates a parent workflow span
    first_result = call_openai("Tell me about the Roman Empire")
    second_result = call_openai(f"Summarize this: {first_result}")
    return second_result

# When called, this will create a trace with a workflow span and two nested LLM spans
response = make_nested_call()
print(response)

​
Additional Parameters

The @log decorator accepts several optional parameters to customize the logging behavior:

@log(
    span_type="workflow",  # The type of span to create
    name="Custom Name",    # A custom name for the span
    project="my-project",  # The project to log to
    log_stream="my-log-stream",  # The log stream to log to
    params={"key": "value"}  # Additional parameters to include in the span
)
def my_function(input):
    return result

​
Context Management

You can also use the galileo_context to set the project and log stream for all decorated functions within its scope:

from galileo import log, galileo_context

@log
def my_function(input):
    return f"Processed: {input}"

# This will log to the specified project and log stream
with galileo_context(project="my-project", log_stream="my-log-stream"):
    result = my_function("test input")
    print(result)

​
Handling Generators

The @log decorator also works with generator functions, both synchronous and asynchronous:

from galileo import log

@log
def generate_numbers(count):
    for i in range(count):
        yield i

# The generator will be logged as a workflow span
for num in generate_numbers(5):
    print(num)

​
Best Practices

  1. Decorate high-level functions: For the clearest traces, decorate the highest-level functions that encompass meaningful units of work.

  2. Use appropriate span types: Choose the span type that best represents what your function does.

  3. Combine with wrappers: The @log decorator works seamlessly with Galileo’s wrappers, allowing you to create rich, nested traces.

  4. Add meaningful tags: Use the params parameter to add metadata that will make it easier to filter and analyze your traces later.

  5. Be mindful of performance: While the decorator adds minimal overhead, be cautious about decorating very frequently called or performance-critical functions.