Observability

Logging

Pass any pino-compatible logger, or anything satisfying GatewayLogger. Every gateway log goes to it: request logs, hook failures, and warnings about request content it can’t translate. Without one, the gateway creates its own console logger. FrogBot passes its own logger, so an embedded gateway’s output lands in FrogBot’s logs.

import pino from 'pino'
import { createGateway } from '@frogbotai/gateway'

const gw = createGateway({
  providers: { openai: {} },
  logger: pino({ level: 'info' })
})

Or configure the built-in console logger directly. It writes one JSON line per entry and defaults to the LOG_LEVEL environment variable, or info:

createGateway({
  providers: { openai: {} },
  logger: { level: 'debug' }
})

See Config options for the accepted logger values.

Tracing

The gateway records spans through trace.getTracer() by default — a no-op unless something has registered a global tracer provider. Pass a host-provided Tracer to use one explicitly.

import { trace } from '@opentelemetry/api'

createGateway({
  providers: { openai: {} },
  tracer: trace.getTracer('my-app')
})

Bootstrap tracing yourself

The Node-only @frogbotai/gateway/setup export registers a NodeTracerProvider and an OTLP exporter — use it in a standalone deployment that doesn’t already have OpenTelemetry wired up. It’s a separate entry point specifically so the core gateway path never eagerly imports the OTel SDK (which pulls in node:async_hooks and friends).

import { setupTracing } from '@frogbotai/gateway/setup'

const flush = setupTracing({ endpoint: 'http://otel-collector:4318/v1/traces' })

// on shutdown
await flush()

Omit endpoint to fall back to the exporter’s own env handling: OTEL_EXPORTER_OTLP_ENDPOINT (with /v1/traces appended) or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT verbatim. setupTracing accepts:

Option	Type	Default	Description
`endpoint`	`string`	From `OTEL_EXPORTER_OTLP_*` env vars	Full OTLP/HTTP traces URL, used as is.
`shutdownTimeoutMs`	`number`	`10000`	How long the returned `flush` function waits for each exporter to flush before shutting it down anyway.
`metrics`	`{ endpoint?: string; exportIntervalMs?: number } \| false`	Metrics on, with the defaults below	Metrics exporter options, or `false` to skip metrics. See Metrics.
`logger`	`GatewayLogger`	The built-in console logger	Receives the warning a repeated call logs.

It also registers a global async context manager and labels exports with service.name @frogbotai/gateway, the package version, a per-process instance ID, and NODE_ENV as the environment; OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES override them. Only the first call in a process takes effect; later calls log a warning and return a no-op flush. The CLI calls setupTracing automatically when tracing.endpoint, OTEL_EXPORTER_OTLP_ENDPOINT, or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is set — no extra setup needed for the standalone server. Only the CLI reads tracing.endpoint: createGateway ignores it, so an embedded gateway exports nothing until you call setupTracing or register your own tracer provider.

@opentelemetry/* packages are optional peer dependencies. If a tracing endpoint is configured but the peers aren’t installed, the CLI reports which packages to add rather than crashing on boot.

Metrics

setupTracing’s metrics option also registers a MeterProvider with a periodic OTLP exporter, sharing the same service resource as traces. Pass metrics: false to skip it.

setupTracing({
  endpoint: 'http://otel-collector:4318/v1/traces',
  metrics: { endpoint: 'http://otel-collector:4318/v1/metrics' }
})

Option	Type	Default	Description
`endpoint`	`string`	`OTEL_EXPORTER_OTLP_ENDPOINT` with `/v1/metrics` appended, or `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	Full OTLP/HTTP metrics URL, used as is.
`exportIntervalMs`	`number`	`60000`	Milliseconds between metric exports.

The gateway records gen_ai.client.token.usage (tokens) and gen_ai.server.request.duration (seconds) for each operation when the gen_ai signal level is recommended or higher.

What gets traced

Hooks contribute low-cardinality otel attributes that get flushed to spans and metrics — every entry becomes a metric dimension, so avoid user or session IDs there.

hooks: {
  beforeUpstream: [
    ({ otel, provider, model }) => {
      otel['gateway.provider'] = provider
      otel['gateway.model'] = model
    }
  ]
}

Signal levels

signalLevel (or tracing.signalLevel, which takes precedence) sets how much telemetry the gateway records. Pass one level for every namespace, or an object with a level per namespace. A namespace you leave out of the object stays at recommended.

createGateway({
  providers: { openai: {} },
  signalLevel: { gen_ai: 'full', frogbot: 'recommended' }
})

Levels run from least to most: off, required, recommended, and full. Each namespace acts at these thresholds:

Namespace	What the level controls
`frogbot`	`required` or higher records a `gateway.<operation>` span for each upstream call. `recommended` or higher also lets the AI SDK record its own child spans.
`gen_ai`	`off` turns AI SDK spans off. `recommended` or higher records the token usage and request duration metrics. `full` also records prompts and outputs on AI SDK spans, so only use it where that content may be stored.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Logging

Tracing

Bootstrap tracing yourself

Metrics

What gets traced

Signal levels

​Logging

​Tracing

​Bootstrap tracing yourself

​Metrics

​What gets traced

​Signal levels

Logging

Tracing

Bootstrap tracing yourself

Metrics

What gets traced

Signal levels