Axiom TanStack 启动
这个 @axiomhq/tanstack-start 软件包为TanStack Start跨React和Solid的应用程序提供可观察性帮助.
安装
npm install @axiomhq/js @axiomhq/logging @axiomhq/tanstack-start
软件包表面
根: 共享 TanStack 启动核心
使用根包进行框架中性启动可观察性 :
createAxiomRequestMiddlewarecreateAxiomFnMiddlewarecreateAxiomFnCorrelationMiddlewarecreateAxiomProxyHandlercreateAxiomUncaughtErrorHandlercaptureErrorgetLogLevelFromStatusCodegetStartErrorStatusCodetransformStartRequestSuccessResulttransformStartRequestErrorResulttransformStartFunctionSuccessResulttransformStartFunctionErrorResulttanStackStartServerFormatterstanStackStartClientFormatters
import {
createAxiomFnMiddleware,
createAxiomRequestMiddleware,
tanStackStartServerFormatters,
} from '@axiomhq/tanstack-start';
@axiomhq/tanstack-start/router
使用 TanStack 路由器导航和计时辅助工具的明确的路由器子路径 :
observeTanStackRoutertanStackRouterFormatters
import { observeTanStackRouter, tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';
@axiomhq/tanstack-start/react
使用 React 适配器报告 TanStack 路由器的错误 defaultErrorComponent按路线 errorComponent,或更广泛的应用级边界 :
import { createAxiomReactErrorHandler } from '@axiomhq/tanstack-start/react';
@axiomhq/tanstack-start/solid
使用 Solid 适配器报告 TanStack 路由器的错误 defaultErrorComponent按路线 errorComponent,或更广泛的应用级边界 :
import { createAxiomSolidErrorHandler } from '@axiomhq/tanstack-start/solid';
锁定设置
import { Logger, ConsoleTransport } from '@axiomhq/logging';
import { tanStackStartServerFormatters } from '@axiomhq/tanstack-start';
import { tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';
export const routerLogger = new Logger({
transports: [new ConsoleTransport()],
formatters: tanStackRouterFormatters,
});
export const startLogger = new Logger({
transports: [new ConsoleTransport()],
formatters: tanStackStartServerFormatters,
});
接收日志附件的 TanStack 启动助手 axiom-tanstack-start/<version> 用于支持的伐木运输工具 X-Axiom-Client 头曰.
共享启动中端软件
Start中相软件API是框架中立的,因为它们建立在TanStack Start核心合同上.
import {
createAxiomFnMiddleware,
createAxiomRequestMiddleware,
} from '@axiomhq/tanstack-start';
export const requestMiddleware = [
createAxiomRequestMiddleware(startLogger, {
include: ['/api/*', '/_server/*'],
exclude: ['/api/health'],
}),
];
export const functionMiddleware = [
createAxiomFnMiddleware(startLogger, {
correlation: true,
}),
];
请求和函数中间软件正在等待 logger.flush() 在解决之前。 当我们以后想要无阻送货时 干净的路就是引入注射器 waitUntil- 原始的,而不是扩大 公共配置表面.
每个服务器函数使用一个函数仪表路径. 若为 createAxiomFnMiddleware 全球通过 createStart({ functionMiddleware }),不同时将其附加到单个服务器函数中,除非您有意为同一调用需要多个日志事件.
为充分定制所排放的字段或副作用,提供 onSuccess 编号 : onError 召回电话。 当提供回调时,中间软件跳过该路径的默认日志. 这个 transformStart*Result 为想要保留默认信件/报告形状并添加自己字段的用户导出帮助器 .
import {
createAxiomRequestMiddleware,
getLogLevelFromStatusCode,
getStartErrorStatusCode,
transformStartRequestErrorResult,
transformStartRequestSuccessResult,
} from '@axiomhq/tanstack-start';
export const requestMiddleware = [
createAxiomRequestMiddleware(startLogger, {
onSuccess: async (data) => {
const [message, report] = transformStartRequestSuccessResult(data);
const logLevel = getLogLevelFromStatusCode(data.response.status);
startLogger.log(logLevel, message, {
...report,
tenant: data.request.headers.get('x-tenant-id'),
region: data.request.headers.get('x-region'),
});
await startLogger.flush();
},
onError: async (data) => {
const [message, report] = transformStartRequestErrorResult(data);
const logLevel = getLogLevelFromStatusCode(getStartErrorStatusCode(data.error));
startLogger.log(logLevel, message, {
...report,
tenant: data.request.headers.get('x-tenant-id'),
region: data.request.headers.get('x-region'),
});
await startLogger.flush();
},
}),
];
import {
createAxiomFnMiddleware,
transformStartFunctionErrorResult,
transformStartFunctionSuccessResult,
} from '@axiomhq/tanstack-start';
export const functionMiddleware = [
createAxiomFnMiddleware(startLogger, {
correlation: true,
onSuccess: async (data) => {
const [message, report] = transformStartFunctionSuccessResult(data);
startLogger.info(message, {
...report,
requestHeaders: {
tenant: data.context.context?.request?.headers.get('x-tenant-id'),
region: data.context.context?.request?.headers.get('x-region'),
},
});
await startLogger.flush();
},
onError: async (data) => {
const [message, report] = transformStartFunctionErrorResult(data);
startLogger.error(message, {
...report,
requestHeaders: {
tenant: data.context.context?.request?.headers.get('x-tenant-id'),
region: data.context.context?.request?.headers.get('x-region'),
},
});
await startLogger.flush();
},
}),
];
对于简单的副作用,回调可以完全忽略日志:
createAxiomRequestMiddleware(startLogger, {
onSuccess: async (data) => {
await analytics.track('request_complete', {
path: new URL(data.request.url).pathname,
statusCode: data.response.status,
});
},
});
路由器观察员
import { observeTanStackRouter } from '@axiomhq/tanstack-start/router';
const observe = observeTanStackRouter(routerLogger, {
source: 'tanstack-router-spa',
performance: true,
});
const unsubscribe = observe(router);
observeTanStackRouter 听着 onResolved 默认。 它只在浏览器中订阅,所以从同样运行于SSR期间的路由器设置中拨打是安全的. 回来的 unsubscribe 函数可以被HMR或自定义路由器生命周期所使用.
使用默认 source 联 合 国 tanstack-router 一般路由器仪表,或设置自定义源,例如 tanstack-router-spa, (中文(简体) ), tanstack-router-react,或 tanstack-router-solid 当您想要区分 Axiom 中的应用/框架变体时.
何时 performance 除导航日志外,还启用了观察员对路由器生命周期事件和路径定时日志.
客户端- Side 代理摄入
对于浏览器日志, 使用 ProxyTransport 并接收与客户 createAxiomProxyHandler 在服务器上。 这保留了 Axiom 令牌服务器侧面,同时保留了客户端代码中相同的logger API.
// src/lib/axiom/client.ts
import { ConsoleTransport, Logger, ProxyTransport } from '@axiomhq/logging';
import type { Transport } from '@axiomhq/logging';
import { tanStackStartClientFormatters } from '@axiomhq/tanstack-start';
import { tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';
function createBrowserTransports(): [Transport, ...Transport[]] {
return [
new ProxyTransport({ url: '/api/axiom' }),
new ConsoleTransport({ prettyPrint: true }),
];
}
export const routerLogger = new Logger({
transports: createBrowserTransports(),
formatters: tanStackRouterFormatters,
});
export const clientLogger = new Logger({
transports: createBrowserTransports(),
formatters: tanStackStartClientFormatters,
});
// src/lib/axiom/server.ts
import { Axiom } from '@axiomhq/js';
import { AxiomJSTransport, ConsoleTransport, Logger } from '@axiomhq/logging';
import { tanStackStartServerFormatters } from '@axiomhq/tanstack-start';
const axiom = new Axiom({ token: process.env.AXIOM_TOKEN! });
export const startLogger = new Logger({
transports: [
new AxiomJSTransport({
axiom,
dataset: process.env.AXIOM_DATASET!,
}),
new ConsoleTransport({ prettyPrint: true }),
],
formatters: tanStackStartServerFormatters,
});
// src/routes/api/axiom.ts
import { createFileRoute } from '@tanstack/react-router';
import { createAxiomProxyHandler } from '@axiomhq/tanstack-start';
import { startLogger } from '../../lib/axiom/server';
const proxyHandler = createAxiomProxyHandler(startLogger);
export const Route = createFileRoute('/api/axiom')({
server: {
handlers: {
POST: ({ request }) => proxyHandler(request),
},
},
});
对于 Solid 应用程序, 使用相同的路径模式 createFileRoute 从 @tanstack/solid-router。 。 。 .
客户端出错边界
TanStack Start的内置模式是用 TanStack 路由器捕捉路径渲染和加载器出错 defaultErrorComponent 或路线 errorComponent。下面的适配器被设计为首先插入该边界模型.
反应
import { ErrorComponent, createRouter, type ErrorComponentProps } from '@tanstack/react-router';
import { useEffect } from 'react';
import { createAxiomReactErrorHandler } from '@axiomhq/tanstack-start/react';
const handleClientError = createAxiomReactErrorHandler(startLogger);
function RouterErrorBoundary({ error, reset }: ErrorComponentProps) {
useEffect(() => {
handleClientError(error);
}, [error]);
return <ErrorComponent error={error} />;
}
const router = createRouter({
routeTree,
defaultErrorComponent: RouterErrorBoundary,
});
固态
import { ErrorComponent, createRouter, type ErrorComponentProps } from '@tanstack/solid-router';
import { onMount } from 'solid-js';
import { createAxiomSolidErrorHandler } from '@axiomhq/tanstack-start/solid';
const handleClientError = createAxiomSolidErrorHandler(startLogger);
function RouterErrorBoundary(props: ErrorComponentProps) {
onMount(() => handleClientError(props.error, props.reset));
return <ErrorComponent error={props.error} />;
}
const router = createRouter({
routeTree,
defaultErrorComponent: RouterErrorBoundary,
});
如果您还想要在 TanStack 路由器路由界限外捕获客户端错误, 您仍然可以从一个更广泛的框架级边界使用相同的适配器帮助器 .
覆盖率
SDK 备份 :
- 请求中间软件
- 服务器功能中间软件
- 请求/功能关联
- 路由器导航日志
- 路由器计时日志
- 代理摄取
- 未发现服务器输入抓取
- React and Solid 客户端错误边界帮助器
仅供用户使用:
- 健康检查
- 调试信头
- 专门针对环境的伐木政策
实例
移徙说明
路由仪现在被故意明确。 导入路由器帮助器 @axiomhq/tanstack-start/router 而不是根包.