Sedata.AI Docs

The auto-instrumentation gives you per-tool spans for free. For everything else — cache lookups, upstream HTTP calls, business outcomes — use the helpers on the ObservabilityInstance returned by instrumentServer.

Setup once, reuse everywhere

Create your instruments once at module scope so you’re not reallocating histograms or counters on the hot path.

instruments.ts

import { instrumentServer } from '@sedata-ai/mcp'

export const telemetry = instrumentServer(server, telemetryConfig)

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

export const incCacheOutcome = telemetry.getIncrementCounter('cache.outcome.count', {
  description: 'Cache hit/miss outcome',
})

Then import where you need them:

import { telemetry, recordCacheLookup, incCacheOutcome } from './instruments'

Pattern: time + count an operation

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
      } catch (err) {
        span.recordException(err as Error)
        span.setStatus({ code: 2, message: (err as Error).message })
        throw err
      } finally {
        span.setAttribute('user.fetch.duration_ms', Date.now() - t0)
        span.end()
      }
    },
  )
}

The new span becomes a child of the auto-generated tools/call <toolName> span if you call this from inside a tool handler.

Pattern: record a histogram with tags

const t0 = Date.now()
const value = cache.get(key)
recordCacheLookup(Date.now() - t0, {
  'cache.hit': !!value,
  'cache.key.kind': 'user',
})
incCacheOutcome(1, { outcome: value ? 'hit' : 'miss' })

Pattern: business outcomes

Counters are great for outcome tracking even when nothing is timed:

const incPaymentOutcome = telemetry.getIncrementCounter('payment.outcome.count', {
  description: 'Payment outcome',
})

incPaymentOutcome(1, { result: 'authorized', method: 'card' })
incPaymentOutcome(1, { result: 'declined',  method: 'card', code: 'insufficient_funds' })

Pattern: distributed trace context

If a tool calls an upstream HTTP service, propagate the active context so the upstream’s spans hang under your trace:

import { context, propagation } from '@opentelemetry/api'

await telemetry.startActiveSpan(
  'github.repos.get',
  { 'http.method': 'GET', 'http.target': '/repos/x/y' },
  async (span) => {
    const headers: Record<string, string> = {}
    propagation.inject(context.active(), headers)

    const res = await fetch('https://api.github.com/repos/x/y', { headers })
    span.setAttribute('http.status_code', res.status)
    span.end()
  },
)

The upstream service (if it’s also instrumented with OTel) will continue your trace.

Pattern: feature-flag the SDK

If you want to gate instrumentation:

const enabled = process.env.ENABLE_SEDATA === 'true'
const telemetry = enabled
  ? instrumentServer(server, config)
  : noopTelemetry()

function noopTelemetry() {
  const noop = () => {}
  return {
    startActiveSpan: (_n: string, _a: any, fn: any) => fn({ end: noop, setAttribute: noop, setStatus: noop, recordException: noop }),
    getHistogram: () => noop,
    getIncrementCounter: () => noop,
    processTelemetryAttributes: (d: any) => d,
    shutdown: async () => {},
  }
}

Pattern: async iterators

If your tool streams events, record one span per batch + a counter per event:

const incEvent = telemetry.getIncrementCounter('stream.event.count', {
  description: 'Stream event count',
})

for await (const evt of stream) {
  incEvent(1, { type: evt.type })
}

For a span-per-event you’d lose more in overhead than you’d gain in visibility — counters are usually the right shape for high-frequency events.

Pattern: shut down on signal

const stop = async (code = 0) => {
  await telemetry.shutdown()
  process.exit(code)
}

process.on('SIGINT', () => stop(0))
process.on('SIGTERM', () => stop(0))
process.on('uncaughtException', (err) => {
  console.error(err)
  stop(1)
})

Automatic metrics

What the package records without any code.

Data processors

Mutate every attribute set in one place.

Get started

Concepts

Guides

Metrics & traces

Examples

Help

Custom instrumentation

Setup once, reuse everywhere

Pattern: time + count an operation

Pattern: record a histogram with tags

Pattern: business outcomes

Pattern: distributed trace context

Pattern: feature-flag the SDK

Pattern: async iterators

Pattern: shut down on signal

See also

Automatic metrics

Data processors

​Setup once, reuse everywhere

​Pattern: time + count an operation

​Pattern: record a histogram with tags

​Pattern: business outcomes

​Pattern: distributed trace context

​Pattern: feature-flag the SDK

​Pattern: async iterators

​Pattern: shut down on signal

​See also

Automatic metrics

Data processors

Setup once, reuse everywhere

Pattern: time + count an operation

Pattern: record a histogram with tags

Pattern: business outcomes

Pattern: distributed trace context

Pattern: feature-flag the SDK

Pattern: async iterators

Pattern: shut down on signal

See also