Структурированное логирование и трейсинг в Node.js: @cleverbrush/log и @cleverbrush/otel

import { number, object, parseString } from '@cleverbrush/schema';
const TransactionCreated = parseString(
    object({ TransactionId: number(), UserId: number() }),
    $t =>
        $t`Transaction ${t => t.TransactionId} created by ${t => t.UserId}`
);
logger.info(TransactionCreated, {
    TransactionId: transaction.id,
    UserId: principal.userId
});

transport. => {
    logger.error(error, McpTransportError, {
        UserId: apiKeyPrincipal.userId
    });
};

import {
    consoleSink,
    createLogger,
    hostnameEnricher,
    processIdEnricher
} from '@cleverbrush/log';
import { otelLogSink, traceEnricher } from '@cleverbrush/otel';
const logger = createLogger({
    minimumLevel: config.logLevel,
    sinks: [consoleSink({ theme: 'dark' }), otelLogSink()],
    enrichers: [hostnameEnricher(), processIdEnricher(), traceEnricher()],
    handleProcessExit: true
});

const logger = createLogger({
    minimumLevel: config.logLevel,
    sinks: [consoleSink({ theme: 'dark' }), otelLogSink()],
    enrichers: [hostnameEnricher(), processIdEnricher(), traceEnricher()]
});

const [correlationMiddleware, requestLogMiddleware] = useLogging(logger, {
    excludePaths: ['/health'],
    correlationResponseHeader: false
});

export function loggerFor(sourceContext: string): Logger {
    return logger.forContext('SourceContext', sourceContext);
}

const authLogger = loggerFor('Auth.js');
authLogger.error(error, AuthErrorLogged, {
    AuthErrorType: authErrorType(error),
    AuthErrorMessage: error.message
});

import { number, object, parseString } from '@cleverbrush/schema';
const TransactionCreated = parseString(
    object({ TransactionId: number(), UserId: number() }),
    $t =>
        $t`Transaction ${t => t.TransactionId} created by ${t => t.UserId}`
);
logger.info(TransactionCreated, {
    TransactionId: transaction.id,
    UserId: principal.userId
});

import type { Logger } from '@cleverbrush/log';
import { useLogging } from '@cleverbrush/log';
import { tracingMiddleware } from '@cleverbrush/otel';
import { createServer } from '@cleverbrush/server';
export function buildServer(
    config: Config,
    logger: Logger,
    resources: DbResources
) {
    const [correlationMiddleware, requestLogMiddleware] = useLogging(logger, {
        excludePaths: ['/health'],
        correlationResponseHeader: false
    });
    return createServer({ maxBodySize: 1024 * 1024 })
        .use(tracingMiddleware({ excludePaths: ['/health'] }))
        .use(corsMiddleware(config))
        .use(correlationMiddleware)
        .use(requestLogMiddleware)
        .services(services => configureDI(services, config, logger, resources));
}

export const createTransactionHandler: Handler<
    typeof CreateTransactionEndpoint
> = async ({ body, principal }, { db, config, logger }) => {
    const transaction = await createTransaction(
        db,
        config,
        principal.userId,
        body
    );
    logger.info(TransactionCreated, {
        TransactionId: transaction.id,
        UserId: principal.userId
    });
    return ActionResult.created(
        transaction,
        `/api/transactions/${transaction.id}`
    );
};

import { setupOtel } from '@cleverbrush/otel';
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
import { RuntimeNodeInstrumentation } from '@opentelemetry/instrumentation-runtime-node';
import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
const endpoint =
    process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://otel-collector:4318';
export const otel = setupOtel({
    serviceName: process.env.OTEL_SERVICE_NAME ?? 'xpenser-api',
    serviceVersion: process.env.npm_package_version,
    environment: process.env.NODE_ENV,
    otlpEndpoint: endpoint,
    instrumentations: [
        new HttpInstrumentation({
            ignoreIncomingRequestHook: request => isHealthPath(request.url)
        }),
        new UndiciInstrumentation(),
        new RuntimeNodeInstrumentation()
    ]
});

export const otel =
    existingOtel ??
    setupOtel({
        serviceName: process.env.WEB_OTEL_SERVICE_NAME ?? 'xpenser-web',
        serviceVersion: process.env.npm_package_version,
        environment: process.env.NODE_ENV,
        otlpEndpoint: endpoint
    });

const tracer = trace.getTracer('xpenser.telegram-bot');
export async function traceTelegramUpdate<T>(
    info: TelegramUpdateSpanInfo,
    handler: () => Promise<T>
): Promise<T> {
    return tracer.startActiveSpan(
        telegramSpanName(info),
        {
            kind: SpanKind.CONSUMER,
            attributes: telegramSpanAttributes(info)
        },
        async span => {
            try {
                const result = await handler();
                span.setAttribute('telegram.update.success', true);
                span.setStatus({ code: SpanStatusCode.OK });
                return result;
            } catch (err) {
                span.setAttribute('telegram.update.success', false);
                span.recordException(
                    err instanceof Error ? err : errorMessage(err)
                );
                span.setStatus({
                    code: SpanStatusCode.ERROR,
                    message: errorMessage(err)
                });
                throw err;
            } finally {
                span.end();
            }
        }
    );
}

const server = createServer({ maxBodySize: 1024 * 1024 })
    .use(tracingMiddleware({ excludePaths: ['/health'] }))
    .use(corsMiddleware(config))
    .use(correlationMiddleware)
    .use(requestLogMiddleware);

ctx.response.setHeader(
    'Access-Control-Allow-Headers',
    'Content-Type, Authorization, X-API-Key, Mcp-Protocol-Version, Mcp-Session-Id, traceparent, tracestate, baggage'
);

import { createClient } from '@cleverbrush/client';
import { clientTracingMiddleware } from '@cleverbrush/otel/client';
import { api } from '@xpenser/contracts';
export function createXpenserClient(options: XpenserClientOptions) {
    return createClient(api, {
        baseUrl: options.baseUrl,
        getToken: options.getToken,
        headers: options.headers,
        onUnauthorized: options.onUnauthorized,
        fetch: options.fetch,
        middlewares: [
            clientTracingMiddleware(),
            retry({ limit: 2, retryOnTimeout: true }),
            timeout({ timeout: 10_000 }),
            dedupe(),
            cacheTags({
                defaultTtl: 5_000,
                ttlByTag: {
                    currencies: 24 * 60 * 60 * 1_000,
                    dashboard: 60_000,
                    transactions: 30_000,
                    categories: 30_000,
                    'user-profile': 30_000
                }
            })
        ]
    });
}

import { createDb } from '@cleverbrush/orm';
import { instrumentKnex } from '@cleverbrush/otel';
import knex from 'knex';
export function createDbResources(config: Config, logger: Logger): DbResources {
    const connection = instrumentKnex(
        knex({
            client: 'pg',
            connection: config.db.connectionString,
            pool: { min: 2, max: 10 },
            acquireConnectionTimeout: 10_000
        })
    );
    logger.debug('Configured application database connection pool', {});
    return {
        knex: connection,
        db: createDb(connection, entityMap)
    };
}

const logger = createLogger({
    minimumLevel: config.logLevel,
    sinks: [consoleSink({ theme: 'dark' }), otelLogSink()],
    enrichers: [hostnameEnricher(), processIdEnricher(), traceEnricher()]
});

logger.info(McpToolCalled, {
    ToolName: toolName,
    UserId: context.principal.userId,
    ApiKeyId: context.principal.apiKeyId
});

• setupOtel() запускается в xpenser-web, xpenser-api и xpenser-telegram-bot
  
• otelLogSink() отправляет структурированные логи как OTel Log Records
  
• traceEnricher() добавляет TraceId и SpanId в каждое лог-событие
  
• tracingMiddleware() создаёт server span для каждого API-запроса
  
• clientTracingMiddleware() связывает web requests с API calls
  
• instrumentKnex() превращает SQL-запросы в дочерние spans
  
• Telegram bot создаёт custom spans для команд, сообщений и callback queries

• после push в GitHub, разворачиватся ephemeral среда, в которой сервисы будут иметь имена типа xpenser-api-pr-123, xpenser-web-pr-123
  
• LLM агент тестирует новый код с помощью Playwright или интеграционных тестов, которы дергают API и web UI
  
• MCP endpoint в SigNoz анализирует трейсы и логи на предмет ошибок, медленных запросов или других аномалий, которые могли появиться из-за изменений в коде. Если что-то пошло не так.

docker compose up --build

• Web app: http://localhost:3000
  
• External API proxy: http://localhost:3000/external-api
  
• Swagger UI: http://localhost:8090
  
• SigNoz: http://localhost:8080

• структурированные message templates превращают важные значения в поля для поиска и агрегации
  
• traceEnricher() связывает каждое лог-событие с активным OTel-трейсом
  
• otelLogSink() отправляет логи в тот же OTLP pipeline, что трейсы и метрики
  
• clientTracingMiddleware() сохраняет distributed trace между web app и API
  
• instrumentKnex() даёт SQL-spans без изменений в query-коде
  
• useLogging() подключает request logging к серверу двумя middleware

npm install @cleverbrush/log
npm install @cleverbrush/otel