Splunk Agent Observability Context

The Splunk Agent Observability Context Manager provides a convenient way to control the logging behavior of your application. It allows you to:

Set the project and Agent Stream for all logs
Get the current logger
Flush traces

In Python, you can also:

Set the project and Agent Stream for a particular scope
Manage sessions
Get the current span and trace

In the Python SDK, this is available through the splunk_ao_context object.

Set the project and Agent Stream

By default, Splunk Agent Observability uses the SPLUNK_AO_PROJECT and SPLUNK_AO_AGENT_STREAM environment variables to determine which project and Agent Stream to log to. You can override this by initializing the Splunk Agent Observability context with a project and Agent Stream name.

from splunk_ao import splunk_ao_context

splunk_ao_context.init(project="my-project",agent_stream="my-agent-stream")

from splunk_ao import AgentStream

agent_stream = AgentStream.get(name="my-agent-stream", project_name="my-project")

# Or create a new one
# agent_stream = AgentStream(name="my-agent-stream", project_name="my-project").create()

# Route traces to the specified Agent Stream
with agent_stream.context():
    # Every trace logged inside this block goes to the Agent Stream above
    ...

Set the project and Agent Stream for a single scope in Python

You can set the project and Agent Stream for a scope using the Python splunk_ao_context, object in a with statement. Every log inside this block, including nested calls, will use the specified project and Agent Stream.

from splunk_ao import splunk_ao_context

# This will log to the specified project and Agent Stream
with splunk_ao_context(project="my-project", agent_stream="my-agent-stream"):
    # All operations within this block will be logged to the same trace
    # in the specified project and Agent Stream
    result = your_function()
    print(result)

from splunk_ao import AgentStream

# Get the Agent Stream
agent_stream = AgentStream.get(name="my-agent-stream", project_name="my-project")

def your_function():
    # Function implementation
    return "result"

# This will log to the specified project and Agent Stream
with agent_stream.context():
    # All operations within this block will be logged to the same trace
    # in the specified project and Agent Stream
    result = your_function()
    print(result)

This also works with the @log decorator.

from splunk_ao import log, splunk_ao_context

@log
def make_nested_call():
    # Function implementation
    return "result"

# This will log to the specified project and Agent Stream
with splunk_ao_context(project="my-project", agent_stream="my-agent-stream"):
    content = make_nested_call()
    print(content)

from splunk_ao import log
from splunk_ao import AgentStream

@log
def make_nested_call():
    # Function implementation
    return "result"

# Get the Agent Stream
agent_stream = AgentStream.get(name="my-agent-stream", project_name="my-project")

# This will log to the specified project and Agent Stream
with agent_stream.context():
    content = make_nested_call()
    print(content)

Third-party integrations like the OpenAI wrapper also support this.

import os
from splunk_ao import splunk_ao_context, openai

# Initialize the Splunk Agent Observability wrapped OpenAI client
client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# This will log to the specified project and Agent Stream
with splunk_ao_context(project="my-project", agent_stream="my-agent-stream"):
    chat_completion = client.chat.completions.create(
        messages=[{"role": "user", "content": "Say this is a test"}],
        model="gpt-4o"
    )
    print(chat_completion.choices[0].message.content)

import os
from splunk_ao import AgentStream
from splunk_ao import openai

# Get the Agent Stream
agent_stream = AgentStream.get(name="my-agent-stream", project_name="my-project")

# Initialize the Splunk Agent Observability wrapped OpenAI client
client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# This will log to the specified Agent Stream
with agent_stream.context():
    chat_completion = client.chat.completions.create(
        messages=[{"role": "user", "content": "Say this is a test"}],
        model="gpt-4o"
    )
    print(chat_completion.choices[0].message.content)

Nesting scopes

You can nest splunk_ao_context calls to temporarily override the project or Agent Stream:

from splunk_ao import splunk_ao_context

with splunk_ao_context(project="my-project", agent_stream="my-agent-stream"):
    # This will log to my-project/my-agent-stream
    operation_1()

    with splunk_ao_context(agent_stream="sub-stream"):
        # This will log to my-project/sub-stream
        operation_2()

    # Back to logging to my-project/my-agent-stream
    operation_3()

Get the current logger

The Splunk Agent Observability 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 splunk_ao import splunk_ao_context

# Get the current logger
logger = splunk_ao_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 or created automatically by an experiment, then this will return that logger instance so you can manually add additional spans.

from splunk_ao import log, splunk_ao_context

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

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

Flush logs

To keep your app performant, logs are not continually flushed. In some cases, you may want to flush traces explicitly:

import os
from splunk_ao import splunk_ao_context, openai

# Initialize the Splunk Agent Observability wrapped OpenAI client
client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def call_openai():
    chat_completion = client.chat.completions.create(
        messages=[{"role": "user", "content": "Say this is a test"}],
        model="gpt-4o"
    )
    return chat_completion.choices[0].message.content

# This will create a single span trace with the OpenAI call
call_openai()

# This will upload the trace to Splunk Agent Observability
splunk_ao_context.flush()

This approach is particularly useful for long-running applications where you need to control when traces are flushed to Splunk Agent Observability.

When using a Python Notebook (such as Jupyter, Google Colab, etc.), you should use the splunk_ao_context and make sure to call splunk_ao_context.flush() at the end of your notebook.

Manage sessions in Python

With the Python SDK, you can manage sessions from the context level in addition to the logger level. All the session management functions are applied to the current logger if called from the context. If you want to apply these to a specific logger instance, call the same methods directly on that logger instance.

Create a new session

To create a new session, use the start_session function.

from splunk_ao import splunk_ao_context

# Start a new session
splunk_ao_context.start_session(name="My session")

When you start a session you can optionally give it a name. If you don’t provide a name, one is created for you based off the traces in the session. You can also provide an external ID to link a session in Splunk Agent Observability to an external identifier.

from splunk_ao import splunk_ao_context

# Start a new session
splunk_ao_context.start_session(external_id=conversation_id)

Continue an existing session

If you want to add a trace to an existing session, you can use the set_session function, 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.

from splunk_ao import splunk_ao_context

# Start an existing session to add new traces to it
splunk_ao_context.set_session(session_id=conversation_session_id)

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

from splunk_ao import splunk_ao_context

# Start an existing session by its external ID to add new traces to it
splunk_ao_context.start_session(external_id=conversation_id)

End a session

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

from splunk_ao import splunk_ao_context

# Clear the current session
splunk_ao_context.clear_session()

Next steps

Basic logging components

Splunk Agent Observability logger

Log with full control over sessions, traces, and spans using the Splunk Agent Observability logger.

Log decorator

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

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 Splunk Agent Observability trace processor.

LangChain callback

Automatically log all the steps in your LangChain or LangGraph application with the Splunk Agent Observability callback.

Overview

Get Started

Observability

Evaluators

Signals

AI Assistant

Luna Studio

Experiments

Agent Control

Annotations

Integrations

Security

References

Set the project and Agent Stream

Set the project and Agent Stream for a single scope in Python

Nesting scopes

Get the current logger

Flush logs

Manage sessions in Python

Create a new session

Continue an existing session

End a session

Next steps

Basic logging components

Splunk Agent Observability logger

Log decorator

Integrations with third-party SDKs

OpenAI wrapper

OpenAI Agents trace processor

LangChain callback

​Set the project and Agent Stream

​Set the project and Agent Stream for a single scope in Python

​Nesting scopes

​Get the current logger

​Flush logs

​Manage sessions in Python

​Create a new session

​Continue an existing session

​End a session

​Next steps

​Basic logging components

Splunk Agent Observability logger

Log decorator

​Integrations with third-party SDKs

OpenAI wrapper

OpenAI Agents trace processor

LangChain callback

Set the project and Agent Stream

Set the project and Agent Stream for a single scope in Python

Nesting scopes

Get the current logger

Flush logs

Manage sessions in Python

Create a new session

Continue an existing session

End a session

Next steps

Basic logging components

Integrations with third-party SDKs