Skip to main content
interface ObservabilityInstance {
  startActiveSpan(
    name: string,
    attributes: Record<string, any>,
    fn: (span: Span) => void,
  ): any

  getHistogram(
    name: string,
    options: MetricOptions,
  ): (value: number, attributes?: Record<string, any>) => void

  getIncrementCounter(
    name: string,
    options: MetricOptions,
  ): (value: number, attributes?: Record<string, any>) => void

  processTelemetryAttributes(data: any): any

  shutdown(): Promise<void>
}
The handle returned by instrumentServer. Implemented by TelemetryManager.

​
Methods

​
startActiveSpan(name, attributes, fn)

Open an active span and execute fn inside it. The session id is added automatically. 
telemetry.startActiveSpan('cache.lookup', { 'cache.key': 'user:42' }, (span) => {
  // ...
  span.end()
})
fn receives an OpenTelemetry Span — call span.end() when done.

​
getHistogram(name, options)

Create or reuse a histogram instrument. Returns a recorder function. Reuse the recorder across calls — don’t recreate per call. 
const recordDuration = telemetry.getHistogram('cache.lookup.duration', {
  description: 'Cache lookup duration',
  unit: 'ms',
})

recordDuration(12, { 'cache.hit': true })

​
getIncrementCounter(name, options)

Create or reuse a counter. Returns an increment function. 
const incRetry = telemetry.getIncrementCounter('upstream.retry.count', {
  description: 'Upstream retries',
})

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

​
processTelemetryAttributes(data)

Run a value through every configured dataProcessor in order. Useful if you’re building log lines that should share the same redaction logic as your spans. 
const cleaned = telemetry.processTelemetryAttributes({
  'user.email': 'jane@acme.com',
})

​
shutdown(): Promise<void>

Records mcp.server.session.duration and shuts down the OpenTelemetry SDK. Always call on graceful exit. 
process.on('SIGTERM', async () => {
  await telemetry.shutdown()
  process.exit(0)
})

​
See also

instrumentServer

Returns this object.

Custom instrumentation

Patterns for using these methods.