Observability & Tracing

Trace TypeGraph operations, inspect telemetry, and debug search retrieval with explain output.

Pass Trace Fields in Context

traceId and spanId live in context, alongside user, group, agent, and thread identity. Do not pass tracing fields beside context.

trace-context.ts

const context = {
  userId: UserId('dana'),
  threadId: ThreadId('thread_123'),
  traceId: requestTraceId,
  spanId: requestSpanId,
}

await typegraph.thread.addTurn(
  'thread_123',
  {
    role: 'user',
    content: 'How do I configure notifications?',
    timestamp: new Date(),
  },
  { context, graphExtraction: true },
)

const response = await typegraph.search('How do I configure notifications?', {
  resources: ['documents', 'threads', 'facts', 'entities'],
  weights: { semantic: 1, bm25: 0.7, graph: 0.3, recency: 0.5 },
  context,
  explain: true,
})

Query SDK Telemetry

SDK operational events write to typegraph_telemetry. Use this table for ingest, search, graph, memory, and policy observability.

telemetry.sql

select
  event_type,
  target_type,
  count(*) as count,
  percentile_cont(0.95) within group (order by duration_ms) as p95_ms
from typegraph_telemetry
where created_at >= now() - interval '24 hours'
group by event_type, target_type
order by count desc;

Query Business Events

typegraph_events is reserved for business events ingested through event.ingest(). Keeping it separate from telemetry makes event graph queries and dashboards cleaner.

business-events.sql

select
  id,
  name,
  description,
  occurred_at,
  metadata
from typegraph_events
where occurred_at >= now() - interval '7 days'
order by occurred_at desc;

Use Search Explain

explain: true returns active resources, weights, fusion config, candidate counts, timings, graph traces, warnings, and skipped-resource reasons. This is the first place to look when “the fact exists but did not come back.”

explain.ts

const response = await typegraph.search('renewal blockers', {
  resources: ['events', 'documents', 'entities', 'facts'],
  weights: { semantic: 0.8, bm25: 0.4, graph: 1, recency: 0.6 },
  context: { groupId: GroupId('sales') },
  explain: true,
})

console.log(response.explanation?.activeResources)
console.log(response.explanation?.activeWeights)
console.log(response.explanation?.candidateCounts)
console.log(response.explanation?.skippedResources)
console.log(response.explanation?.warnings)

Back to All Guides

const context = { userId: UserId('dana'), threadId: ThreadId('thread_123'), traceId: requestTraceId, spanId: requestSpanId, } await typegraph.thread.addTurn( 'thread_123', { role: 'user', content: 'How do I configure notifications?', timestamp: new Date(), }, { context, graphExtraction: true }, ) const response = await typegraph.search('How do I configure notifications?', { resources: ['documents', 'threads', 'facts', 'entities'], weights: { semantic: 1, bm25: 0.7, graph: 0.3, recency: 0.5 }, context, explain: true, })

select event_type, target_type, count(*) as count, percentile_cont(0.95) within group (order by duration_ms) as p95_ms from typegraph_telemetry where created_at >= now() - interval '24 hours' group by event_type, target_type order by count desc;

const response = await typegraph.search('renewal blockers', { resources: ['events', 'documents', 'entities', 'facts'], weights: { semantic: 0.8, bm25: 0.4, graph: 1, recency: 0.6 }, context: { groupId: GroupId('sales') }, explain: true, }) console.log(response.explanation?.activeResources) console.log(response.explanation?.activeWeights) console.log(response.explanation?.candidateCounts) console.log(response.explanation?.skippedResources) console.log(response.explanation?.warnings)