Create and Use Sessions

Overview

This tutorial will guide you through creating and using a Session in Splunk Agent Observability, using a simple LLM-driven example that you can expand to multiple agents and data sources. It is a quick way to introduce you to logging sessions. By the end of this guide, you will know how to:

Initialize a logging session
Add events to your session
Inspect the Session in the Splunk Agent Observability UI to see all related Traces and Spans.

There will be minor differences around starting and flushing the session context, depending on whether you’re using the automatic or manual way. We’ll cover both below.

Prerequisites

Splunk Agent Observability Account: Ensure you have signed up for a Splunk Agent Observability account. This should provide you with the following values:
- SPLUNK_AO_API_KEY: Your API key. Only required for on-premises, standalone, and custom deployments.
- SPLUNK_AO_PROJECT: The name of your Splunk Agent Observability Project.
- SPLUNK_AO_AGENT_STREAM: The Agent Stream where you will save your sessions.
- SPLUNK_AO_CONSOLE_URL: Only required for on-premises, standalone, and custom deployments. This URL appears in the browser when you load the Splunk Agent Observability UI.
OpenAI API Key: This example will use OpenAI as the underlying LLM, so you will need an API key from them.

In addition, this tutorial assumes you are familiar with:

Simple LLM Apps, and making simple OpenAI completion calls using Python
The SplunkAOLogger class from the Python SDK

Project setup

Let’s take a moment to prepare the development environment. If you already have a project setup with Splunk Agent Observability, LangChain, and LangGraph, you can skip right to Manage a Session. If not, here’s an abbreviated quickstart:

Install dependencies

We’ll need the Splunk Agent Observability Python SDK, LangChain, LangGraph, OpenAI, and dotenv to pull in variables from your .env file. Let’s start by installing them:

pip install "splunk-ao[openai]" langchain langchain-openai langgraph python-dotenv

Create a .env file

Next, create a .env file and add in the following variables:

.env

# Provide your API key and deployment URL if you are
# using an on-premises, standalone, or custom deployment
# SPLUNK_AO_API_KEY="your-splunk-ao-api-key"
# SPLUNK_AO_CONSOLE_URL="your-splunk-ao-url"

# Your Splunk Agent Observability project name
SPLUNK_AO_PROJECT="your-splunk-ao-project-name"

# The name of the Agent Stream you want to use for logging
SPLUNK_AO_AGENT_STREAM="your-splunk-ao-agent-stream"

# OpenAI properties
OPENAI_API_KEY="your-openai-api-key"

# Optional. The base URL of your OpenAI deployment.
# Leave this commented out if you are using the default OpenAI API.
# OPENAI_BASE_URL="your-openai-base-url-here"

# Optional. Your OpenAI organization.
# OPENAI_ORGANIZATION="your-openai-organization-here"

Create your application logic file

Finally, create a main script file (e.g. main.py or main.ts) where you’ll add and run your application logic.

Now we can dive in.

Manage a session

Recall our objectives from earlier? We’ll build a simple application and use it to work through each step. If you’re in a hurry, you jump to the full code sample here, then return to see how it was put together.

Steps

Create a simple agent

In your main script, import the following dependencies. Let’s begin by creating a very simple agent using LangGraph and OpenAI:

from time import time
from dotenv import load_dotenv

# Splunk Agent Observability dependencies
from splunk_ao import SplunkAOLogger
from splunk_ao.handlers.langchain import SplunkAOCallback

# LangChain and LangGraph dependencies
from langchain.agents import create_agent
from langchain_core.runnables.config import RunnableConfig

# Load `.env` variables
load_dotenv()

# Create a simple assistant for our test (or import one). You can also provide
# your agent with tools: the session will log their usage
simple_agent = create_agent(
    name="simple_agent",
    model="openai:o3-mini",  # you can choose any OpenAI model here
    system_prompt="You are a friendly assistant that answers the user's questions",
    tools=[],  # (OPTIONAL) provide tools to your agent
)

import { configDotenv } from "dotenv";

// Splunk Agent Observability dependencies
import { SplunkAOCallback, SplunkAOLogger } from "splunk-ao";

// LangChain and LangGraph dependencies
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { RunnableConfig } from "@langchain/core/runnables";
import { ChatOpenAI } from "@langchain/openai";

// Load environment variables
configDotenv();

// Create a simple assistant for our test (or import one). You can also provide
// your agent with tools: the session will log their usage
const simpleAgent = createReactAgent({
  name: "simpleAssistant",
  llm: new ChatOpenAI({ model: "o3-mini" }),
  prompt: "You are a friendly assistant that answers the user's questions",
  tools: [] // (OPTIONAL) provide tools to your agent
});

We’ll see SplunkAOCallback and RunnableConfig in action later. For now, let’s move on to the next step.

Create a Logger Instance

We’ll be using the SplunkAOLogger to manage our logging session. Let’s create one next:

# Create a SplunkAOLogger instance for our session
logger = SplunkAOLogger()

// Create a SplunkAOLogger instance for our session
const logger = new SplunkAOLogger();

Optional arguments for SplunkAOLogger

SplunkAOLogger takes some optional arguments: you don’t have to provide any of them, but they are listed below so that you can see what is available.

SplunkAOLogger(
    project_name: Optional[str]
    """ name of target project for the logger instance """
    agent_stream_name: Optional[str]
    """ name of target agentstream for the logger instance """
    project_id: Optional[str]
    """ ID of target project for the logger instance """
    agent_stream_id: Optional[str]
    """ ID of target agentstream for the logger instance """
    experiment_id: Optional[str]
    """ ID of an experiment to which this log session will be linked """
    session_id: Optional[str]
    """ ID of a previous session to which this log session will be linked """
    local_metrics: Optional[list[LocalMetricConfig]]
    """ Locally-defined metrics that should be used on spans/traces from
    this session: See 'Custom Metrics' for more information """
)

new SplunkAOLogger({
    /**  name of target project for the logger instance */
    projectName?: string;
    /**  name of target agentstream for the logger instance */
    agentStreamName?: string;
    /**  ID of an experiment to which this log session will be linked */
    projectId?: string;
    /**  ID of target project for the logger instance */
    agentStreamId?: string;
    /**  ID of target agentstream for the logger instance */
    experimentId?: string;
    /**  ID of a previous session to which this log session will be linked */
    sessionId?: string;
    /** Locally-defined metrics that should be used on spans/traces from
        this session: See 'Custom Metrics' for more information */
    localMetrics?: LocalMetricConfig[];
    /** Logger mode: "batch" or "streaming". Defaults to "batch" if not set.
        - "batch": Batches traces and sends on flush() (default)
        - "streaming": Enables streaming tracing with immediate
          updates to backend */
    mode?: string;
    /** Optional callback invoked on `flush()` in batch mode with the payload
        that would be sent to the API. When set, it runs instead of the
        default `ingestTraces` call—use for custom delivery. */
    ingestionHook?: (request: LogTracesIngestRequest) => Promise<void> | void;
})

Start a logging session

Our simple application will have a main function where everything happens. The first thing we will do in this function is start up a logging session. This will prepare the logger to group all captured events under a single session.Below, we give the session a unique name and external id. The name helps us find the session more easily in the Splunk Agent Observability UI. The external id is to link this session to external tracing: for example, linking to a conversation ID in your chatbot app by an ID created inside that app.You can also pass an optional metadata dictionary of string key-value pairs to attach structured information to the session, such as customer IDs, environment names, or application versions. Metadata keys appear as filterable columns in the Sessions table in the Splunk Agent Observability UI.

def main():
    """Main application logic"""

    # start a logging session
    external_id = f"custom_id-{int(time())}"
    logger.start_session(
        name="Logger Session Tutorial",
        external_id=external_id,
        metadata={
            "brand_id": "acme",
            "environment": "production",
        },
    )

/** Main application logic */
async function main() {
  // Start a logging session
  const externalId = `custom_id-${Math.round(Date.now() / 1000)}`;
  await logger.startSession({
    name: "Logger Session Tutorial",
    externalId,
    metadata: {
      brand_id: "acme",
      environment: "production",
    },
  });
}

Treat logger.start_session like a lifecycle event, and call it before any code you want to monitor. The name, external id, and metadata arguments are all optional; name and external id are recommended.

Add your LLM logic

Now you can interact with your LLM. Our very simple application will invoke the LLM with two questions: each question will be a question/answer exchange that generates a Trace with child spans in our session. We will also pass a callback handler, which will be called by LangChain after each LLM invocation.Here’s our full main function: you can make this part as complex as you like!

def main():
    """Main application logic"""

    # start a logging session
    external_id = f"custom_id-{int(time())}"
    logger.start_session(name="Logger Session Tutorial", external_id=external_id)

    # Here's what we will ask the LLM:
    prompts = [
        "Hello! How many minutes are in a year?",
        "Hello! How far is an Astronomical Unit in kilometers?",
    ]

    # Create a LangChain Runnable config object with a LangGraph callback handler:
    # We will supply the logger instance to ensure that it generates traces in the
    # correct session
    agent_config = RunnableConfig(callbacks=[SplunkAOCallback(splunk_ao_logger=logger)])

    for prompt in prompts:
        # Invoke the LLM with our question:
        response = simple_agent.invoke(
            input={"messages": [{"role": "user", "content": prompt}]},
            config=agent_config,  # pass the RunnableConfig here
        )
        # Print out the LLM's response to confirm that this code block ran:
        print("Model response:", response["messages"][-1].content.strip())

/** Main application logic */
async function main() {
  // Start a logging session
  const externalId = `custom_id-${Math.round(Date.now() / 1000)}`;
  await logger.startSession({ name: "Logger Session Tutorial", externalId });

  // Here's what we will ask the LLM:
  const prompts = [
    "Hello! How many minutes are in a year?",
    "Hello! How far is an Astronomical Unit in kilometers?"
  ];

  // Create a LangChain Runnable config object with a LangGraph callback handler.
  // We will supply the logger instance to ensure that it generates traces in the
  // correct session
  const agentConfig: RunnableConfig = {
    callbacks: [new SplunkAOCallback(logger)]
  };

  for (const prompt of prompts) {
    // Invoke the LLM with our question:
    const result = await simpleAgent.invoke(
      { messages: [{ role: "user", content: prompt }] },
      agentConfig // pass the RunnableConfig here
    );

    //  Print out the LLM's response to confirm that this code block ran:
    console.log("LLM Reply:", result.messages.at(-1)?.content);
  }
}

The SplunkAOCallback handler

SplunkAOCallback is a callback handler specifically for LangChain. It sends the most-recent captured traces to Splunk Agent Observability UI when it is called behind the scenes: your LLM logic determines what traces are generated and/or captured.

SplunkAOCallback optional parameters (click to expand)

SplunkAOCallback has a few optional parameters:

SplunkAOCallback(
    splunk_ao_logger: Optional[SplunkAOLogger] = None,
    """ A `SplunkAOLogger` instance. Defaults to a global singleton """
    start_new_trace: bool = True,
    """ Start a new trace on next invocation. Defaults to "true" """
    flush_on_chain_end: bool = True,
    """ Flush captured traces after invocation. Defaults to "true" """
)

Full code sample

Here’s everything we have done so far:

Full code sample (click to expand)

from time import time
from dotenv import load_dotenv

# Splunk Agent Observability dependencies
from splunk_ao import SplunkAOLogger
from splunk_ao.handlers.langchain import SplunkAOCallback

# LangChain and LangGraph dependencies
from langchain.agents import create_agent
from langchain_core.runnables.config import RunnableConfig

# Load `.env` variables
load_dotenv()

# Create a simple assistant for our test (or import one). You can also provide
# your agent with tools: the session will log their usage
simple_agent = create_agent(
    name="simple_agent",
    model="openai:o3-mini",  # you can choose any OpenAI model here
    system_prompt="You are a friendly assistant that answers the user's questions",
    tools=[],  # (OPTIONAL) provide tools to your agent
)

# Create a SplunkAOLogger instance
logger = SplunkAOLogger()


def main():
    """Main application logic"""

    # start a logging session
    external_id = f"custom_id-{int(time())}"
    logger.start_session(name="Logger Session Tutorial", external_id=external_id)

    # Here's what we will ask the LLM:
    prompts = [
        "Hello! How many minutes are in a year?",
        "Hello! How far is an Astronomical Unit in kilometers?",
    ]

    # Create a LangChain Runnable config object with a LangGraph callback handler:
    # We will supply the logger instance to ensure that it generates traces in the
    # correct session
    agent_config = RunnableConfig(callbacks=[SplunkAOCallback(splunk_ao_logger=logger)])

    for prompt in prompts:
        # Invoke the LLM with our question:
        response = simple_agent.invoke(
            input={"messages": [{"role": "user", "content": prompt}]},
            config=agent_config,  # pass the RunnableConfig here
        )

        # Print out the LLM's response to confirm that this code block ran:
        print("Model response:", response["messages"][-1].content.strip())

if __name__ == "__main__":
    main()

import { configDotenv } from "dotenv";

// Splunk Agent Observability dependencies
import { SplunkAOCallback, SplunkAOLogger } from "splunk-ao";

// LangChain and LangGraph dependencies
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { RunnableConfig } from "@langchain/core/runnables";
import { ChatOpenAI } from "@langchain/openai";

// Load environment variables
configDotenv();

// Create a simple assistant for our test (or import one). You can also provide
// your agent with tools: the session will log their usage
const simpleAgent = createReactAgent({
  name: "simpleAgent",
  llm: new ChatOpenAI({ model: "o3-mini" }),
  prompt: "You are a friendly assistant that answers the user's questions",
  tools: [] // (OPTIONAL) provide tools to your agent
});

// Create a SplunkAOLogger instance for our session
const logger = new SplunkAOLogger();


/** Main application logic */
async function main() {
  // Start a logging session
  const externalId = `custom_id-${Math.round(Date.now() / 1000)}`;
  await logger.startSession({ name: "Logger Session Tutorial", externalId });

  // Here's what we will ask the LLM:
  const prompts = [
    "Hello! How many minutes are in a year?",
    "Hello! How far is an Astronomical Unit in kilometers?"
  ];

  // Create a LangChain Runnable config object with a LangGraph callback handler.
  // We will supply the logger instance to ensure that it generates traces in the
  // correct session
  const agentConfig: RunnableConfig = {
    callbacks: [new SplunkAOCallback(logger)]
  };

  for (const prompt of prompts) {
    // Invoke the LLM with our question:
    const result = await simpleAgent.invoke(
      { messages: [{ role: "user", content: prompt }] },
      agentConfig // pass the RunnableConfig here
    );

    //  Print out the LLM's response to confirm that this code block ran:
    console.log("LLM Reply:", result.messages.at(-1)?.content);
  }
}

main();

Run your script

That’s all the code: we have now learned to use logger.start_session before starting LLM chat session, and supply SplunkAOCallback to ensure your traces get sent to the Splunk Agent Observability UI. Now let’s run the script:

python main.py

You should see the LLM’s response in your terminal! You can also head to the Splunk Agent Observability UI to view the newly-created session. (Shown below)

View your session

Now that you’ve logged a session, it’s time to view results.

Log into Splunk Agent Observability and select your Agent Stream

Log into Splunk Agent Observability. Use the main menu to select a project, then select the Agent Stream where you were sending your session logs. If you didn’t specify a unique or new Agent Stream name, you will find the logs in your default Agent Stream.

Select your session

Selecting the Agent Stream will bring you to its event records. By default, all records will be grouped by Sessions. You can select the Sessions, Traces, or Spans tabs to change the event grouping.

Event-group controls for selecting Session, Trace, or Span granularity

Your session should be visible in the table below the controls, especially if you gave it a recognizable name. Select it to view the traces.

View your session

Once you select your session, select the Trace graph tab to see the Traces you captured from your test run as a flowchart. Any tools that were used will also show up as individual Spans.Select the nodes of the flowchart to see their inputs and outputs on your screen.

A flowchart showing the nodes in a session Trace

Optional: View individual Spans

Each message from the user and response from the LLM forms a single trace. You can view the contents here in a familiar format, as well as other details like tool calls. Select the Messages tab to see a list of traces in the session, along with their child spans. You can also select a span to see evaluators and other details on the right edge of the screen.

Additional considerations

Remember to always use the same SplunkAOLogger instance across your project. This ensures that all captured events are placed in the same session. You can achieve this in a few ways:

Export your logger instance from a separate module, so that your application uses a singleton instance.

Use the Python SDK’s splunk_ao_context context manager for a consistent reference:

from splunk_ao import splunk_ao_context

# Create a new session (with optional metadata)
splunk_ao_context.start_session(
    name="My Session",
    metadata={"brand_id": "acme", "environment": "production"},
)

# Application logic follows

# Flush the session (if you are not using SplunkAOCallback or "with splunk_ao_context()")
splunk_ao_context.flush()

You can also add Traces wherever you see fit. A Trace might represent a question asked to your LLM, and the response generated for it — as well as any tools used! Splunk Agent Observability will generate traces for you, but you can also create new ones by using your logger instance:
question = "What is the meaning of plenipotentiary?" logger.start_trace(input=question) logger.add_llm_span( input=question, output="Plenipotentiary means 'Invested with full power'" ) logger.conclude({}) # end the trace
You can learn more about traces and how to use them in our logging guide.

Conclusion

In this tutorial, you learned how to:

Create a logging session with the SplunkAOLogger class
Manually start your own session with the logger.start_session() method
View your sessions in the Splunk Agent Observability UI.

Next steps

For a more detailed walkthrough of a multi-agent application, take a look at Monitoring LangChain Agents with Splunk Agent Observability. You can also learn more about using Splunk Agent Observability’s evaluators to gain more insight about your AI application.

Sessions - An overview of sessions
Splunk Agent Observability Context - Learn about the Splunk Agent Observability Context Manager
Monitoring LangChain Agents with Splunk Agent Observability - Follow this cookbook recipe to create and evaluate a multi-agent application.

Overview

Get Started

Observability

Evaluators

Signals

AI Assistant

Luna Studio

Experiments

Agent Control

Annotations

Integrations

Security

References

Overview

Prerequisites

Project setup

Manage a session

Steps

The SplunkAOCallback handler

Full code sample

Run your script

View your session

Additional considerations

Conclusion

Next steps

​Overview

​Prerequisites

​Project setup

​Manage a session

​Steps

​The SplunkAOCallback handler

​Full code sample

​Run your script

​View your session

​Additional considerations

​Conclusion

​Next steps

​Related resources

Overview

Prerequisites

Project setup

Manage a session

Steps

The SplunkAOCallback handler

Full code sample

Run your script

View your session

Additional considerations

Conclusion

Next steps

Related resources