@optima/core

Optima 生产可观测性共享库 - 专为 Next.js/Node.js 设计

功能

• 诊断端点: /health 健康检查、/debug/info、/debug/config
• 结构化日志: JSON/Text 格式、自动注入追踪信息
• 分布式追踪: trace_id 生成与传递、AsyncLocalStorage 上下文
• HTTP 客户端: 自动传递追踪 header

安装

npm install @optima/core
# 或
pnpm add @optima/core

使用方法

健康检查端点

// app/api/health/route.ts
import { createHealthHandler } from "@optima/core/diagnostics";

export const GET = createHealthHandler({
  serviceName: "agentic-chat",
  checks: {
    database: async () => {
      // 检查数据库连接
      return { status: "healthy" };
    },
    redis: async () => {
      // 检查 Redis
      return { status: "healthy" };
    },
  },
});

调试端点

// app/api/debug/info/route.ts
import { createDebugInfoHandler } from "@optima/core/diagnostics";
export const GET = createDebugInfoHandler();

// app/api/debug/config/route.ts
import { createDebugConfigHandler } from "@optima/core/diagnostics";
export const GET = createDebugConfigHandler();

API Route 追踪

// app/api/users/route.ts
import { withTracing } from "@optima/core/tracing";

async function handler(request: Request) {
  // 处理请求
  return Response.json({ users: [] });
}

export const GET = withTracing(handler, {
  serviceName: "agentic-chat",
  serviceShort: "chat",
});

结构化日志

import { createLogger } from "@optima/core/logging";

const logger = createLogger({
  serviceName: "agentic-chat",
  format: "json", // 或 "text"
  level: "info",
});

logger.info("User logged in", { userId: "123" });
logger.error("Failed to process", { error: "timeout" }, new Error("Timeout"));

带追踪的 HTTP 请求

import { tracedFetch, createTracedClient } from "@optima/core/http";

// 单次请求
const response = await tracedFetch("http://user-auth/api/users");

// 创建客户端
const authApi = createTracedClient("http://user-auth:8000");
const user = await authApi.get("/users/123");
await authApi.post("/users", { name: "John" });

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | GIT_COMMIT | Git commit hash | unknown | | GIT_BRANCH | Git 分支 | unknown | | APP_VERSION | 应用版本 | 0.0.0 | | BUILD_DATE | 构建日期 | 当前时间 | | DEPLOYMENT_ID | 部署 ID (蓝绿) | - | | LOG_FORMAT | 日志格式 | json | | LOG_LEVEL | 日志级别 | info | | DEBUG_KEY | Debug 端点密钥 | - |

Trace ID 格式

格式: {timestamp_hex}-{random_hex}-{service_short}
示例: 67890abc-f1e2d3c4b5a6-chat

响应 Header

| Header | 说明 | |--------|------| | X-Trace-ID | 追踪 ID | | X-Request-ID | 请求 ID | | X-Response-Time | 响应时间 | | X-Served-By | 服务名-版本 | | X-Deployment-ID | 部署 ID |

License

MIT