Qhaway

npm @carloscortezcloud/qhaway · PyPI qhaway-trace

Agent observability — trace every LLM call, track cost per user/model, export to OpenTelemetry, visualize in Grafana. TypeScript and Python. Zero dependencies. Edge-native.

npm — TypeScript / Workers

npm install @carloscortezcloud/qhaway

pip — Python (OpenAI, Anthropic, LangChain)

pip install qhaway-trace

Subpackages

/trace

@carloscortezcloud/qhaway/trace

Span wrapper + storage adapters (D1, KV, Memory, Console).

/cost

@carloscortezcloud/qhaway/cost

Pricing DB + cost attribution. Aggregate by user/model/day.

/otel

@carloscortezcloud/qhaway/otel

OTLP/HTTP JSON exporter. Honeycomb, Grafana Tempo, Datadog, SigNoz.

/tinkuy

@carloscortezcloud/qhaway/tinkuy

TinkuyAgent plugin. Auto-instrument runs via hooks.

/mlflow

@carloscortezcloud/qhaway/mlflow

MLflow REST exporter. Batch + streaming modes.

QhawayTrace

The core trace wrapper. Wraps any async function with measurement.

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

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

const wrapped = trace.wrap(myLlmCall, {
  model: 'gpt-4o',
  provider: 'openai',
  user_id: 'user-123',
});

const result = await wrapped(prompt);
// Console: [Qhaway] gpt-4o | $0.00063 | 150->42 tok | 1234ms

Storage Adapters

Class	Best For
`MemoryStorage`	Dev/testing
`ConsoleStorage`	Debug logging
`D1Storage`	Production (SQL queries, aggregation)
`KVStorage`	High-scale writes at edge

QhawayCost

Built-in pricing DB for OpenAI, Anthropic, Google with fallback chain.

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

const cost = new QhawayCost();
const c = await cost.calculate('gpt-4o', 150, 42);
// → 0.00063

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

OTEL Export

Send traces to any OTEL-compatible backend. Zero protobuf dependencies.

import { QhawayOtelExporter, QhawayOtelStorage, CompositeStorage }
  from '@carloscortezcloud/qhaway/otel';

const otel = new QhawayOtelExporter({
  endpoint: 'https://api.honeycomb.io/v1/traces',
  headers: { 'X-Honeycomb-Team': process.env.HONEYCOMB_API_KEY },
  serviceName: 'my-agent',
});

const storage = new CompositeStorage([
  new ConsoleStorage(),
  new QhawayOtelStorage(otel),
]);

Prometheus Metrics

Metric	Type	Labels
`qhaway_cost_total`	Counter	model, provider, user
`qhaway_latency_seconds`	Histogram	model
`qhaway_tokens_input_total`	Counter	model
`qhaway_tokens_output_total`	Counter	model
`qhaway_calls_total`	Counter	model, success

Edge Compatibility

Cloudflare WorkersNode.js 18+DenoBunAWS Lambda

GitHub →npm →PyPI →

Guides

Quickstart →

Set up tracing, cost tracking, and Prometheus metrics.

Grafana Dashboard →

Import the pre-built dashboard. Cost, latency, tokens.

MLflow Exporter →

Export traces to MLflow experiment tracking.

OTEL Exporter →

Send traces to Honeycomb, Tempo, Datadog, SigNoz.

← PreviousTideRAG — Architecture Next →Qhaway — Quickstart