Observability - Timeback Docs (Beta)

Logging

The SDK’s built-in logger only emits warnings and errors. You can customize this with two options on createTimeback():

SdkLogger

Custom logger instance. Compatible with console, Pino, Winston, Bunyan, and any logger whose methods accept a string message followed by optional arguments.

SdkLogLevel

default:"warn"

Minimum level for the built-in logger. Ignored when a custom logger is provided.

Custom logger

Pass any logger whose methods accept a string message followed by optional arguments. The SDK prefixes each message with the internal scope, for example [timeback:handlers:user].

import { createTimeback } from '@timeback/sdk'
import pino from 'pino'

const timeback = await createTimeback({
    logger: pino({ level: 'debug' }),
    // ...
})

import { createTimeback } from '@timeback/sdk'
import winston from 'winston'

const timeback = await createTimeback({
    logger: winston.createLogger({
        level: 'debug',
        transports: [new winston.transports.Console()],
    }),
    // ...
})

import { createTimeback } from '@timeback/sdk'

const timeback = await createTimeback({
    logger: console,
    // ...
})

When a custom logger is provided, the SDK forwards all log calls to it. Level filtering is the logger’s responsibility.

Log level

When using the built-in logger, logLevel controls the minimum severity:

const timeback = await createTimeback({
    logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error' | 'silent'
    // ...
})

Level	What you see
`debug`	Everything, including request details
`info`	Operational messages and above
`warn`	Warnings and errors only (default)
`error`	Errors only
`silent`	Nothing

Set the DEBUG=1 environment variable to enable debug-level output without changing code. This takes effect when no explicit logLevel is configured.

Request lifecycle hooks

Track request timing and status with the onRequestStart and onRequestEnd hooks:

const timeback = await createTimeback({
    hooks: {
        onRequestStart({ handler }) {
            console.log(`[${handler}] started`)
        },
        onRequestEnd({ handler, durationMs, status }) {
            console.log(`[${handler}] ${status} in ${durationMs}ms`)
        },
    },
    // ...
})

These wrap the HTTP handlers listed below. They do not wrap direct namespace calls such as activity.record(), and the identity sign-out handler is not wrapped:

Handler	Trigger
`activity.submit`	Activity completion
`activity.heartbeat`	Time-spent heartbeat
`user.me`	User profile lookup
`user.verify`	User session check
`identity.signIn`	SSO sign-in initiation
`identity.callback`	SSO callback processing

| lessons.list, lessons.start | Lesson discovery and attempt start | | lessons.next, lessons.submit | Question requests and answers | | lessons.complete | Lesson completion request | | lessons.attempts, lessons.attemptDetails | Attempt history | Logging configuration is global to this SDK module. Creating another server instance replaces the effective logger/settings for existing scoped loggers. The snippets above show logging options; merge them into your complete server configuration.

​Logging

​Custom logger

​Log level

​Request lifecycle hooks

Logging

Custom logger

Log level

Request lifecycle hooks