Observability

Observability Exports

import {
  createTraceCollector,
  RunflowTraceCollector,
  RunflowTraceSpan,
  traced
} from '@runflow-ai/sdk';

Conversation Messages

import { message } from '@runflow-ai/sdk/observability';

`message(data, options?)`

Emit a conversation_message trace. The portal renders these as chat bubbles and uses them to populate the thread sidebar preview. See Conversation Messages for the full guide and examples.

message({ role: 'user',      content: 'Quais acomodações?' });
message({ role: 'assistant', content: 'Oferecemos duas opções...' });

Parameters (MessageData):

Name	Type	Description
`role`	`'user' \| 'assistant' \| 'system' \| 'tool' \| string`	Speaker. Custom strings are accepted.
`content`	`string \| Record<string, any>`	Plain text or a structured object with a `type` field (e.g. `{ type: 'buttons', items: [...] }`).
`metadata`	`Record<string, any>`	Optional extra fields (citations, confidence, custom flags).
`parentId`	`string`	Optional explicit parent span’s `traceId`. Falls back to the active `startSpan()` context.

LogOptions:

Name	Type	Description
`parentId`	`string`	Same as `data.parentId`. Provided for symmetry with `log()` / `logError()`.

Available since @runflow-ai/sdk@1.1.10.

Code-first Metrics

import { metrics, MetricsRegistry } from '@runflow-ai/sdk/observability';

`metrics` (singleton)

Process-wide MetricsRegistry instance. import { metrics } returns the same object across modules, mirroring how track() and identify() share state.

`metrics.defineTab(input)`

Idempotent on name — re-registering updates the sortOrder.

metrics.defineTab({ name: 'Vendas', sortOrder: 0 });

`metrics.defineCard(input)`

Validates synchronously via shared Zod schemas. Throws on invalid cardType, invalid gridLayout, or duplicate (cardType, title) pairs. Legacy aliases (e.g. tableMode → mode) are auto-normalized before validation.

metrics.defineCard({
  tab: 'Vendas',
  title: 'Funil de checkout',
  cardType: 'funnel',
  config: {
    funnelMode: 'multi_event',
    steps: [
      { eventName: 'cart_open',        label: 'Carrinho aberto' },
      { eventName: 'checkout_started', label: 'Início checkout' },
      { eventName: 'sale',             label: 'Pagamento' },
    ],
  },
  gridLayout: { x: 0, y: 0, w: 6, h: 5 },
});

`metrics.sync(options?)`

Two-phase upsert against the runtime endpoints. Returns a tally:

const result = await metrics.sync();
// { agentId, tabs: { created, updated, total }, cards: { created, updated, failed, total } }

SyncOptions:

Name	Type	Default	Description
`agentId`	`string`	`RUNFLOW_AGENT_ID` env	Override the target agent.
`baseUrl`	`string`	`RUNFLOW_API_URL` env	Override the API host.
`apiKey`	`string`	`RUNFLOW_API_KEY` env	Override the API key.
`strict`	`boolean`	`false`	Throw on any tab/card error instead of warning.

Each card carries a deterministic idempotencyKey = ${cardType}:${title}:${tab ?? ''} so repeated sync() calls are safe. See Metrics Registry for the full guide.

Execution Reviews

import { Reviews } from '@runflow-ai/sdk';

`new Reviews(options?)`

Programmatic access to execution reviews. Requires an underlying RunflowAPIClient exposing the reviews namespace (SDK ≥ 1.1.13).

const reviews = new Reviews();
// or with a custom client:
const reviews = new Reviews({ apiClient: customClient });

Methods:

Method	Signature	Description
`create`	`(args: CreateExecutionReviewArgs) => Promise<CreateExecutionReviewResult>`	Create a review. `comment` must be ≥ 10 chars.
`checkHasReview`	`(executionId: string) => Promise<CheckHasReviewResult>`	Idempotent check before `create()`.
`list`	`(filters?: ListReviewsFilters) => Promise<ListReviewsResult>`	List with filters. Backend caps `limit` at 100 (defaults to 50).
`get`	`(reviewId: string) => Promise<ExecutionReview>`	Fetch a single review.
`update`	`(reviewId, args: UpdateExecutionReviewArgs) => Promise<UpdateReviewResult>`	Partial update. Setting `status: 'resolved'` auto-stamps `resolvedBy` / `resolvedAt`.
`delete`	`(reviewId: string) => Promise<DeleteReviewResult>`	Hard delete.
`stats`	`(filters: { agentId }) => Promise<ReviewsStats>`	Aggregate counts + `avgResolutionHours`.
`exportForTraining`	`(filters: ExportForTrainingFilters) => Promise<ExportForTrainingResult>`	Export as OpenAI conversational fine-tuning examples.

Typed errors (all extend ReviewsError):

Class	Status	When
`ReviewAlreadyExistsError`	409	Execution already has a review.
`ReviewNotFoundError`	404	reviewId not found (or wrong tenant).
`ReviewsError`	any	Other failures — exposes `status` and raw `body`.

See Execution Reviews for the feedback-loop pattern.

Business Events Tracking

import { track, flushTrackEvents } from '@runflow-ai/sdk/observability';

`track(eventName, properties?, options?)`

Emit a business event for the portal dashboard.

track('alert_received', { company: 'NW', severity: 'High' });

Parameters:

Name	Type	Description
`eventName`	`string`	Event name (e.g. `'order_placed'`)
`properties`	`Record<string, any>`	Key-value event data
`options`	`TrackOptions`	Optional overrides

TrackOptions:

Name	Type	Description
`threadId`	`string`	Override auto-resolved thread ID
`executionId`	`string`	Override auto-resolved execution ID
`timestamp`	`string`	ISO-8601 timestamp (defaults to now)

`flushTrackEvents()`

Manually flush all buffered events. Returns a Promise<void>.

await flushTrackEvents();

Observability Exports

Conversation Messages

`message(data, options?)`

Code-first Metrics

`metrics` (singleton)

`metrics.defineTab(input)`

`metrics.defineCard(input)`

`metrics.sync(options?)`

Execution Reviews

`new Reviews(options?)`

Business Events Tracking

`track(eventName, properties?, options?)`

`flushTrackEvents()`

Next Steps

API Client

Standalone Modules

​Observability Exports

​Conversation Messages

​message(data, options?)

​Code-first Metrics

​metrics (singleton)

​metrics.defineTab(input)

​metrics.defineCard(input)

​metrics.sync(options?)

​Execution Reviews

​new Reviews(options?)

​Business Events Tracking

​track(eventName, properties?, options?)

​flushTrackEvents()

​Next Steps

API Client

Standalone Modules

Observability Exports

Conversation Messages

`message(data, options?)`

Code-first Metrics

`metrics` (singleton)

`metrics.defineTab(input)`

`metrics.defineCard(input)`

`metrics.sync(options?)`

Execution Reviews

`new Reviews(options?)`

Business Events Tracking

`track(eventName, properties?, options?)`

`flushTrackEvents()`

Next Steps