Installation

TypeScript / Cloudflare Workers:

npm install @carloscortezcloud/qhaway

Python (OpenAI, Anthropic, LangChain):

pip install qhaway-trace              # core
pip install "qhaway-trace[openai]"    # + OpenAI auto-instrumentation
pip install "qhaway-trace[anthropic]" # + Anthropic auto-instrumentation
pip install "qhaway-trace[langchain]" # + LangChain callback handler

The PyPI package is named qhaway-trace (the name qhaway was taken by an unrelated project). The Python import stays from qhaway import ....

Basic Tracing — TypeScript

import { QhawayTrace, ConsoleStorage } from '@carloscortezcloud/qhaway/trace';

const trace = new QhawayTrace(new ConsoleStorage(), {
  agent_id: 'my-agent',
});

// Wrap any LLM call
const wrappedLlm = trace.wrap(myLlmFunction, {
  model: 'gpt-4o',
  provider: 'openai',
  user_id: 'user-123',
});

const result = await wrappedLlm('Hello!');
// Console: [Qhaway] gpt-4o (openai) | $0.00063 | 150→42 tok | 1234ms

Cost Tracking

import { QhawayCost, aggregateByUser } from '@carloscortezcloud/qhaway/cost';

const cost = new QhawayCost();

// Calculate cost for a single call
const c = await cost.calculate('gpt-4o', 150, 42);
// → 0.00063

// Aggregate spans
const byUser = aggregateByUser(spans);
const byModel = aggregateByModel(spans);
const byDay = aggregateByDay(spans);

Storage Options

import {
  MemoryStorage,    // Dev/testing
  ConsoleStorage,   // Debug logging
  D1Storage,        // Production (SQL queries, aggregation)
  KVStorage,        // High-scale at edge
} from '@carloscortezcloud/qhaway/trace';

With Tinkuy Agent

import { QhawayTinkuyPlugin } from '@carloscortezcloud/qhaway/tinkuy';

const plugin = new QhawayTinkuyPlugin({
  storage: new ConsoleStorage(),
  agentName: 'finops-agent',
});

const agent = new Agent({
  router,
  tools: [myTool],
  systemPrompt: '...',
  onIteration: (e) => plugin.hooks.onIteration(e),
  onToolCall: (e) => plugin.hooks.onToolCall(e),
  onComplete: (e) => plugin.hooks.onComplete(e),
});

Prometheus Metrics

import { generatePrometheusMetrics } from '@carloscortezcloud/qhaway/cost';

const metrics = generatePrometheusMetrics(spans);
// GET /metrics → exposes:
// qhaway_cost_total{model="gpt-4o"} 0.00123
// qhaway_latency_seconds{model="gpt-4o"} 1.234
// qhaway_calls_total{model="gpt-4o",success="true"} 10

Basic Tracing — Python

import asyncio
from qhaway import QhawayTrace, console_storage

trace = QhawayTrace(storage=console_storage, agent_id="my-agent")

@trace.wrap(model="gpt-4o", provider="openai", user_id="user-123")
async def call_llm(prompt: str) -> str:
    return "answer"

asyncio.run(call_llm("hello"))
# [Qhaway] ✓ gpt-4o (openai) | $0.0000 | 0→0 tok | 0ms user=user-123

Auto-instrument OpenAI — Python

from qhaway import QhawayTrace, console_storage
from qhaway.integrations import OpenAIPatch

trace = QhawayTrace(storage=console_storage)
patch = OpenAIPatch.apply(trace)  # patches chat.completions.create

import openai
client = openai.AsyncOpenAI()
response = await client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "hi"}],
)
# Auto-captures model, tokens, latency, and cost from usage
patch.restore()

Storage — Python

ConsoleStorage, MemoryStorage, SqliteStorage (local persistence), HttpStorage (export to a Qhaway API), CompositeStorage (fan out to multiple backends).

from qhaway import QhawayTrace, SqliteStorage

trace = QhawayTrace(storage=SqliteStorage("agent.db"), agent_id="my-agent")

CLI — Python

qhaway stats                # summary of last 24h from qhaway.db
qhaway stats --db agent.db --hours 48

Prints total cost, calls, tokens, errors, avg latency, and cost by model.