Tracing agentic work

// A span is a unit of work: every tracked call inside it (including calls
// through a wrapped client) shares one session and is linked to its caller,
// so the full call tree reconstructs. Spans nest freely, and context is
// async-local: parallel branches under Promise.all never cross-wire.
await bear.withSpan('resolve-ticket', { agentId: 'triage-agent' }, async () => {
  await openai.chat.completions.create({ /* ... */ }); // child of resolve-ticket

  await bear.withSpan('escalation-check', { agentId: 'escalator' }, async () => {
    await openai.chat.completions.create({ /* ... */ }); // grandchild
  });
});

// traced() is the same span as a function wrapper. Prefer it where you DEFINE
// your agent functions, so call sites stay clean.
const research = bear.traced('web-researcher', async (query: string) => {
  return openai.chat.completions.create({ /* ... */ });
});

await bear.withSpan('resolve-ticket', {
  sessionType: 'ticket',
  userId: user.id,
  metadata: { customer_tier: 'enterprise', environment: 'prod' }, // labels cascade
}, async () => {
  await openai.chat.completions.create({ /* ... */ }); // carries tier + environment

  // Learned something mid-run? Applies to events from here on (not retroactive).
  bear.setAttribute('intent', 'refund');

  bear.track(null, {
    model: 'gpt-4o-mini',
    metadata: { customer_tier: 'internal' },  // the call site wins on conflict
    dimensions: { documents_generated: 3 },   // numeric measures NEVER cascade
  });
});

// Long-lived sessions (multi-turn chat) outlive any one process, so pass
// the session id explicitly instead of letting the root span mint one.
// Each turn is a span inside the conversation-long session.
app.post('/chat/:conversationId', async (req, res) => {
  await bear.withSpan('turn', {
    sessionId: req.params.conversationId,
    sessionType: 'support-chat',
  }, async () => {
    const reply = await openai.chat.completions.create({ /* ... */ });
    res.json({ reply });
  });
});

// Declare the outcome on the span. If the function completes, the outcome is
// counted exactly once, structurally: there is no terminal call to remember
// and no way to double-count. If it throws, the outcome is NOT counted, but
// every dollar spent inside is still attributed, so the cost of failed work
// stays visible instead of pooling silently with the successes.
await bear.withSpan('resolve-ticket', { outcome: 'ticket_resolved' }, async () => {
  // ...several agent calls, tool calls, sub-spans...
});

// Read it back: unit economics with success and failure side by side.
const perOutcome = await bear.costs.byOutcome({ lastDays: 30 });
// -> ticket_resolved: completed 412 ($389.20), failed 31 ($47.10)

// A budget turns tracking into control. The wrapped client keeps a running
// cost estimate inside the span; the call that would breach the cap throws
// BudgetExceededError instead of executing. A runaway loop stops at $0.50
// instead of running all night. Estimates are client-side and approximate
// (within a few percent); the billing-grade ledger stays server-side.
await bear.withSpan('deep-research', {
  outcome: 'report_delivered',
  budget: { usd: 0.5, onExceeded: 'throw' }, // or 'flag' to record and continue
}, async () => {
  // ...supervisor and worker calls...
});

// Budgets nest: cap one worker branch inside a larger run budget.
await bear.withSpan('web-worker', { budget: { usd: 0.1, onExceeded: 'throw' } }, work);

// Producer: inside any span, hand the trace to the job. traceContext()
// returns a W3C trace context carrier, so an OTel-instrumented queue can carry
// it natively and consumers in any language can resume it.
await queue.add('embed-doc', { docId: doc.id, trace: bear.traceContext() });

// Consumer: a different process resumes the tree via parent. unitKey makes
// redelivery honest: the same key means attempt #2 of the SAME unit. Cost
// sums across attempts (real money was spent twice), the outcome counts
// once, and retry cost becomes queryable instead of invisible.
await bear.withSpan('embed-worker', {
  parent: job.data.trace,
  unitKey: job.id,
  outcome: 'doc_embedded',
}, async () => {
  await openai.embeddings.create({ /* ... */ });
});