Custom spans & metrics

const telemetry = instrumentServer(server, telemetryConfig)

telemetry.startActiveSpan(
  'cache.lookup',
  { 'cache.key': 'user:42' },
  (span) => {
    const value = cache.get('user:42')
    span.setAttribute('cache.hit', !!value)
    span.end()
    return value
  },
)

await telemetry.startActiveSpan('db.query', { 'db.statement': 'SELECT ...' }, async (span) => {
  try {
    const rows = await db.query('SELECT ...')
    span.setAttribute('db.rows', rows.length)
    return rows
  } catch (err) {
    span.recordException(err as Error)
    span.setStatus({ code: 2, message: (err as Error).message }) // ERROR
    throw err
  } finally {
    span.end()
  }
})

const recordLookup = telemetry.getHistogram('cache.lookup.duration', {
  description: 'Cache lookup duration',
  unit: 'ms',
})

const t0 = Date.now()
const value = cache.get(key)
recordLookup(Date.now() - t0, { 'cache.hit': !!value })

const incRetry = telemetry.getIncrementCounter('upstream.retry.count', {
  description: 'Upstream retry count',
})

incRetry(1, { upstream: 'github', reason: 'timeout' })

const redactEmails = (data: Record<string, any>) => {
  for (const k of Object.keys(data)) {
    if (typeof data[k] === 'string' && /\S+@\S+/.test(data[k])) {
      data[k] = '[REDACTED:email]'
    }
  }
  return data
}

const config: TelemetryConfig = {
  // ...
  dataProcessors: [redactEmails],
}

async function fetchUser(id: string) {
  return telemetry.startActiveSpan('user.fetch', { 'user.id': id }, async (span) => {
    const t0 = Date.now()
    try {
      const user = await db.user.findUnique({ where: { id } })
      span.setAttribute('user.found', !!user)
      return user
    } finally {
      span.setAttribute('user.fetch.duration_ms', Date.now() - t0)
      span.end()
    }
  })
}

const outcome = telemetry.getIncrementCounter('agent.handoff.outcome', {
  description: 'Agent handoff outcome',
})

outcome(1, { from: 'router', to: 'researcher', status: 'success' })