Observability & Analytics

Sessions

This feature is gated by the COVA_FEATURE_SESSIONS environment variable (default: ON). See Re-enable Observability Features to enable.

When building AI agents or complex workflows, your application often makes multiple LLM calls, vector database queries, and tool calls to complete a single task. Sessions group these related requests together, letting you trace the entire agent flow from initial user input to final response in one unified view.

Why use Sessions

  • Debug AI agent flows: See the entire agent workflow in one view, from initial request to final response
  • Track multi-step conversations: Reconstruct the complete flow of chatbot interactions and complex tasks
  • Analyze performance: Measure outcomes across entire interaction sequences, not just individual requests
CoreValue example of a session template for monitoring and managing inputs from requests sent to your AI applications.

Quick Start

Include three required headers in your LLM requests:

{
  "Cova-Session-Id": "unique-session-id",
  "Cova-Session-Path": "/trace-path", 
  "Cova-Session-Name": "Session Name"
}

Use path syntax to represent parent-child relationships:

"/abstract"                    // Top-level trace
"/abstract/outline"           // Child trace
"/abstract/outline/lesson-1"  // Grandchild trace

Execute your LLM request with the session headers included:

const response = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Hello" }], 
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/greeting",
      "Cova-Session-Name": "User Conversation"
    }
  }
);

Understanding Sessions

What Sessions Can Track

Sessions can group together all types of requests in your AI workflow:

  • LLM calls - OpenAI, Anthropic, and other model requests
  • Vector database queries - Embeddings, similarity searches, and retrievals
  • Tool calls - Function executions, API calls, and custom tools
  • Any logged request - Anything sent through CoreValue's logging

This gives you a complete view of your AI agent's behavior, not just the LLM interactions.

Session IDs

The session ID is a unique identifier that groups all related requests together. Think of it as a conversation thread ID.

What to use:

  • UUIDs (recommended): 550e8400-e29b-41d4-a716-446655440000
  • Unique strings: user_123_conversation_456

Why it matters:

  • Same ID = requests get grouped together in the dashboard
  • Different IDs = separate sessions, even if they're related
  • Reusing IDs across different workflows will mix unrelated requests
// ✅ Good - unique per conversation
const sessionId = randomUUID(); // Different for each user conversation

// ❌ Bad - reuses same ID
const sessionId = "chat_session"; // All users get mixed together

Session Paths

Paths create the hierarchy within your session, showing how requests relate to each other.

Path Naming Philosophy:

Think of session paths as conceptual groupings rather than chronological order. Requests with the same path represent the same "type" of work, even if they happen at different times.

Example: In a code review agent, all "security check" requests get the same path (/review/security) whether they happen early or late in the analysis. This lets you see patterns in the duration distribution chart - all security checks will be colored the same, showing you when they typically occur and how long they take.

Path Structure Rules:

  • Start with / (forward slash)
  • Use / to separate levels: /parent/child/grandchild
  • Keep names descriptive: /analyze_request/fetch_data/process_results
  • Group by function, not by time - same conceptual work = same path

How Hierarchy Works:

"/conversation"                    // Root level
"/conversation/initial_question"   // Child of conversation  
"/conversation/followup"          // Another child of conversation
"/conversation/followup/clarify"  // Child of followup

Path Design Patterns:

// Workflow pattern - good for AI agents
"/task"
"/task/research" 
"/task/research/web_search"
"/task/generate"

// Conversation pattern - good for chatbots
"/session"
"/session/question_1"
"/session/answer_1" 
"/session/question_2"

// Pipeline pattern - good for data processing
"/process"
"/process/extract"
"/process/transform"
"/process/load"

Session Names

The session name is a high-level grouping that makes it easy to filter and organize similar types of sessions in the dashboard.

Good session names:

  • "Customer Support" - All support sessions use this name
  • "Content Generation" - All content creation sessions use this name
  • "Trip Planning Agent" - All trip planning workflows use this name

Purpose:

  • Quick filtering - Filter dashboard to show only "Customer Support" sessions
  • High-level organization - Group alike sessions for easy comparison
  • Performance analysis - Compare metrics across the same session type

Configuration Reference

Required Headers

Cova-Session-Idstringrequired

Unique identifier for the session. Use UUIDs to avoid conflicts.

Example: "550e8400-e29b-41d4-a716-446655440000"

Cova-Session-Pathstringrequired

Path representing the trace hierarchy using / syntax. Shows parent-child relationships.

Example: "/abstract" or "/parent/child"

Cova-Session-Namestringrequired

Human-readable name for the session type. Groups similar workflows together.

Example: "Course Plan" or "Customer Support"

Common Patterns

Track a complete code generation workflow with clarifications and refinements:

import { randomUUID } from "crypto";
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.corevalue.dev/v1",
  apiKey: process.env.COVA_API_KEY,
});

const sessionId = randomUUID();

// Initial feature request
const response1 = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Create a React component for user authentication with email and password" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/request",
      "Cova-Session-Name": "Code Generation Assistant",
    },
  }
);

// User asks for clarification
const response2 = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Create a React component for user authentication with email and password" },
      { role: "assistant", content: response1.choices[0].message.content },
      { role: "user", content: "Can you add form validation and error handling?" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/request/validation",
      "Cova-Session-Name": "Code Generation Assistant",
    },
  }
);

// User requests TypeScript version
const response3 = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Convert this to TypeScript with proper interfaces" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/request/validation/typescript",
      "Cova-Session-Name": "Code Generation Assistant",
    },
  }
);
import uuid
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.corevalue.dev/v1",
    api_key=os.environ.get("COVA_API_KEY"),
)

session_id = str(uuid.uuid4())

# Initial feature request
response1 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Create a React component for user authentication with email and password"}],
    extra_headers={
        "Cova-Session-Id": session_id,
        "Cova-Session-Path": "/request",
        "Cova-Session-Name": "Code Generation Assistant",
    }
)

# User asks for clarification
response2 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Create a React component for user authentication with email and password"},
        {"role": "assistant", "content": response1.choices[0].message.content},
        {"role": "user", "content": "Can you add form validation and error handling?"}
    ],
    extra_headers={
        "Cova-Session-Id": session_id,
        "Cova-Session-Path": "/request/validation",
        "Cova-Session-Name": "Code Generation Assistant",
    }
)

# User requests TypeScript version
response3 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Convert this to TypeScript with proper interfaces"}],
    extra_headers={
        "Cova-Session-Id": session_id,
        "Cova-Session-Path": "/request/validation/typescript",
        "Cova-Session-Name": "Code Generation Assistant",
    }
)

Track an automated PR review workflow with multiple analysis steps:

const sessionId = randomUUID();

// Initial PR analysis
const analysis = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Analyze this pull request for code quality and potential issues: [PR diff content]" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/analysis",
      "Cova-Session-Name": "PR Review Bot",
    },
  }
);

// Security check
const securityCheck = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Check for security vulnerabilities: SQL injection, XSS, authentication issues" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/analysis/security",
      "Cova-Session-Name": "PR Review Bot",
    },
  }
);

// Generate review comments
const reviewComments = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Generate constructive review comments based on analysis" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/analysis/security/comments",
      "Cova-Session-Name": "PR Review Bot",
    },
  }
);

Track a multi-step API documentation generation workflow:

const sessionId = randomUUID();

// Analyze API endpoints
const endpoints = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Analyze these API routes and extract endpoint information: [code content]" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/analyze",
      "Cova-Session-Name": "API Documentation Generator",
    },
  }
);

// Generate OpenAPI spec
const openApiSpec = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Generate OpenAPI 3.0 specification based on these endpoints" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/analyze/openapi",
      "Cova-Session-Name": "API Documentation Generator",
    },
  }
);

// Create usage examples
const examples = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Create code examples for each endpoint in multiple languages" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Cova-Session-Id": sessionId,
      "Cova-Session-Path": "/analyze/openapi/examples",
      "Cova-Session-Name": "API Documentation Generator",
    },
  }
);

Complete Session Example

Full JavaScript implementation showing session hierarchy and tracking


On this page