Logger / Telemetry

# core (always)
pnpm add @refraction-ui/logger

# React adapter
pnpm add @refraction-ui/react-logger

# optional — only needed when you set an `endpoint`
pnpm add @grafana/faro-web-sdk @grafana/faro-web-tracing

import { createTelemetry } from '@refraction-ui/logger'

// Create ONCE, outside React render.
export const telemetry = createTelemetry({
  app: 'interview-service',
  env: process.env.NODE_ENV === 'production' ? 'production' : 'development',
  endpoint: process.env.NEXT_PUBLIC_TELEMETRY_ENDPOINT, // optional
  sampleRate: 0.25,                                      // optional
  redactKeys: ['password', 'token', 'authorization'],    // optional
  enabled: true,                                         // optional (default true)
})

telemetry.warn('rate limited', { route: '/v1/answer' })

// Child loggers carry bound context onto every downstream record.
const session = telemetry.child({ sessionId: 's-123' })
const turn = session.child({ turnId: 't-7' })

const span = turn.startSpan('llm-call', { model: 'gpt' })
try {
  // ... async work ...
  span.end()
} catch (err) {
  span.end({ error: err })
}

await telemetry.flush()

// Zero-config dev: no endpoint -> console-only, pretty, level=debug, sync.
const dev = createTelemetry({ app: 'studio', env: 'development' })
dev.debug('cache miss', { key: 'user:42' }) // printed immediately, pretty

// Production: batched + sampled + level>=warn + structured JSON +
// beacon flush on pagehide / visibilitychange. Same call sites,
// different runtime behavior — no code changes needed.
const prod = createTelemetry({
  app: 'studio',
  env: 'production',
  endpoint: 'https://collector.example/ingest',
})
prod.debug('cache miss')             // dropped (below warn)
prod.error('checkout failed', { orderId: 'o-9' }) // buffered, sampled, flushed

// enabled: false returns a tree-shakeable noop logger. Every method is a
// no-op, no engine is ever imported, and bundlers can drop the call sites.
// Zero runtime cost — the ideal "logging off in this build" switch.
const telemetry = createTelemetry({
  app: 'interview-service',
  env: 'production',
  enabled: process.env.NEXT_PUBLIC_TELEMETRY !== 'off', // flip per build/env
})

// When disabled these compile and run, but emit nothing and cost nothing:
telemetry.info('app booted')
telemetry.child({ sessionId: 's-1' }).warn('slow turn')
telemetry.startSpan('noop-span').end()
await telemetry.flush() // resolves immediately

// app/providers.tsx
'use client'

import { TelemetryProvider } from '@refraction-ui/react-logger'
import { createTelemetry } from '@refraction-ui/logger'

// Created once at module scope — never re-created on render.
const telemetry = createTelemetry({
  app: 'interview-app',
  env: process.env.NODE_ENV === 'production' ? 'production' : 'development',
  endpoint: process.env.NEXT_PUBLIC_TELEMETRY_ENDPOINT,
})

export function Providers({ children }: { children: React.ReactNode }) {
  return <TelemetryProvider value={telemetry}>{children}</TelemetryProvider>
}

'use client'

import { useLogger } from '@refraction-ui/react-logger'

export function AnswerButton({ questionId }: { questionId: string }) {
  // Scope string -> bound context { scope }. Stable across renders.
  const log = useLogger('answer-button')

  return (
    <button
      onClick={() => {
        log.info('answer submitted', { questionId })
      }}
    >
      Submit answer
    </button>
  )
}

'use client'

import { useSpan } from '@refraction-ui/react-logger'

export function TranscribeControl({ clipId }: { clipId: string }) {
  // useSpan() returns a stable startSpan bound to the provider's logger.
  const startSpan = useSpan()

  async function transcribe() {
    const span = startSpan('transcribe-clip', { clipId })
    try {
      await fetch('/api/transcribe', { method: 'POST' })
      span.end()
    } catch (err) {
      span.end({ error: err })
    }
  }

  return <button onClick={transcribe}>Transcribe</button>
}

// app/providers.tsx
'use client'

import {
  TelemetryProvider,
  TelemetryErrorBoundary,
} from '@refraction-ui/react-logger'
import { createTelemetry } from '@refraction-ui/logger'

const telemetry = createTelemetry({ app: 'interview-app', env: 'production' })

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TelemetryProvider value={telemetry}>
      {/* Any thrown render error is logged at error level with the
          component stack, then the fallback is shown. */}
      <TelemetryErrorBoundary
        fallback={<p>Something went wrong. The team has been notified.</p>}
      >
        {children}
      </TelemetryErrorBoundary>
    </TelemetryProvider>
  )
}

'use client'

import { useEffect } from 'react'
import { useLogger } from '@refraction-ui/react-logger'

/**
 * AI interview / live meeting: a long-lived session with many nested,
 * overlapping async spans. Child loggers thread sessionId / interviewId /
 * turnId onto every record and span so a whole interview is one query.
 */
export function useInterviewTelemetry(interviewId: string) {
  const log = useLogger('ai-interview')

  useEffect(() => {
    // One logger per interview; turn loggers branch off it.
    const interview = log.child({ interviewId })
    const sessionSpan = interview.startSpan('interview-session')
    interview.info('interview started')

    let cancelled = false

    async function runTurn(turnId: string, prompt: string) {
      const turn = interview.child({ turnId })

      // Outer span covers the whole turn; inner spans cover each phase.
      const turnSpan = turn.startSpan('turn')
      try {
        const sttSpan = turn.startSpan('speech-to-text')
        const transcript = await transcribe(prompt)
        sttSpan.end({ attributes: { chars: transcript.length } })

        const llmSpan = turn.startSpan('llm-answer', { model: 'gpt' })
        const answer = await askModel(transcript)
        llmSpan.end()

        const ttsSpan = turn.startSpan('text-to-speech')
        await speak(answer)
        ttsSpan.end()

        turn.info('turn complete')
        turnSpan.end()
      } catch (err) {
        turn.error('turn failed', { phase: 'unknown' })
        turnSpan.end({ error: err })
      }
    }

    void (async () => {
      await runTurn('t-1', 'Tell me about yourself.')
      if (!cancelled) await runTurn('t-2', 'Why this role?')
      sessionSpan.end()
      interview.info('interview finished')
      // Force-deliver everything (matters under the production preset).
      await interview.flush()
    })()

    return () => {
      cancelled = true
      // Page/route exit while a turn is mid-flight: close the session span
      // with the reason and flush before unmount.
      sessionSpan.end({ attributes: { endedBy: 'unmount' } })
      void interview.flush()
    }
  }, [interviewId, log])
}

// --- stand-ins for your real async pipeline ---
declare function transcribe(input: string): Promise<string>
declare function askModel(transcript: string): Promise<string>
declare function speak(text: string): Promise<void>