Log Categories

Log types are organized into named categories for structured filtering and grouping. Categories are resolved automatically from the type field during ingestion -- you never need to send a category in your log payload.

Built-In Categories

AI (ai)

Types for AI/LLM system tracing.

Type	Description
llm	LLM API call -- input, output, model, token usage
interaction	User interaction event
step	A discrete step in a workflow or agent loop
action	An action taken by an agent or system
response	A response produced -- to the user or to another system
summary	A summary or rollup of a session or process

HTTP (http)

Types for HTTP request/response tracing.

Type	Description
request	An inbound HTTP request
response	An outbound HTTP response

TIP

The response type exists in both ai and http categories. The category is resolved based on first matching category. Built-in types map to their first entry in the LOG_CATEGORIES map. If you need explicit control, use the category filter when querying.

System (system)

General-purpose logging types.

Type	Description
error	An error event with structured context
debug	Debug-specific output
info	Informational event
warn	Warning -- non-fatal but noteworthy
log	Generic log entry (default type)

Custom Categories

Any type string not in the built-in categories is automatically assigned the custom category. Custom types must be a non-empty string:

{
  "message": "User signed up",
  "type": "signup",
  "level": "info"
}

This log is resolved to category: "custom".

Examples of Custom Types

• billing -- Payment and usage events
• deployment -- CI/CD pipeline events
• audit -- Security audit trail
• notification -- Push/email notification events

The Type Field

The type field on a log entry is a free-form string. Built-in types are mapped to their categories, but any non-empty string is valid:

// Source: src/types/categories.ts
export const LOG_CATEGORIES = {
  ai: ['llm', 'interaction', 'step', 'action', 'response', 'summary'],
  http: ['request', 'response'],
  system: ['error', 'debug', 'info', 'warn', 'log'],
} as const

The resolveCategory() function checks the type against the category map. If no match is found, it returns 'custom'.

The isValidTypeForCategory() function validates that a given type belongs to a specific category, preventing custom types from overlapping with built-in category names.

Using Categories in Queries

Filter logs by category in query requests:

curl -X POST https://api.logvista.orph.dev/logger/{projectId}/query \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "category": "ai"
    }
  }'

You can also filter by specific type:

{
  "filters": {
    "type": "llm"
  }
}

Using Categories in the Client SDK

The logger interface provides category-specific methods:

const logger = c.get('logger')

// AI category
logger.ai('llm', { message: 'GPT-4 call', data: { tokens: 512 } })
logger.ai('step', { message: 'Agent step 3', data: { action: 'search' } })

// HTTP category
logger.http('request', { message: 'External API called' })

// System category
logger.system('error', { message: 'Connection failed' })
logger.system('info', { message: 'Cache warmed' })

// Custom category
logger.custom('billing', { message: 'Invoice created', data: { amount: 99 } })
logger.custom('audit', { message: 'User role changed' })

Next Steps

• Log Types Reference -- Full type definitions and LogPayload schema
• Middleware -- Auto-logging with the client SDK
• API Reference: Query -- Query endpoint documentation