> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sedata-ai.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# ObservabilityInstance

> The object returned by instrumentServer.

```ts theme={null}
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`](/api-reference/instrument-server).
Implemented by [`TelemetryManager`](/api-reference/telemetry-manager).

## Methods

### `startActiveSpan(name, attributes, fn)`

Open an active span and execute `fn` inside it. The session id is added
automatically.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
process.on('SIGTERM', async () => {
  await telemetry.shutdown()
  process.exit(0)
})
```

## See also

<CardGroup cols={2}>
  <Card title="instrumentServer" icon="plug" href="/api-reference/instrument-server">
    Returns this object.
  </Card>

  <Card title="Custom instrumentation" icon="code" href="/metrics-and-traces/custom-instrumentation">
    Patterns for using these methods.
  </Card>
</CardGroup>