@zippybee/loki-report

Loki 日志上报 SDK，适用于 uni-app 全终端平台

简介

@zippybee/loki-report 是一个轻量级的日志上报 SDK，专为 uni-app 设计，支持将日志数据上报到 Loki 日志系统。提供完善的类型支持和灵活的配置选项。

特性

• 🚀 轻量级，无外部依赖
• 📦 TypeScript 支持，完善的类型定义
• 🔧 灵活的配置选项
• 🎯 支持自定义上报参数
• 🛡️ 完善的错误处理
• 🔍 Debug 模式便于调试
• 📱 自动采集设备和网络信息

安装

# 使用 pnpm
pnpm add @zippybee/loki-report

# 使用 npm
npm install @zippybee/loki-report

# 使用 yarn
yarn add @zippybee/loki-report

快速开始

1. 初始化配置

在 main.ts 或 main.js 中初始化 SDK：

import { createSSRApp } from 'vue';
import { createLokiReport } from '@zippybee/loki-report';
import App from './App.vue';

export function createApp() {
  const app = createSSRApp(App);
  
  // 创建并安装 Loki 上报插件
  const lokiReport = createLokiReport({
    job: 'your-app-name',           // 必填：应用名称
    url: 'https://loki.example.com/loki/api/v1/push',  // 必填：Loki 服务地址
    isReport: true,                  // 必填：是否启用上报
    debug: false,                    // 可选：是否开启调试模式
    extendsInfo: {                   // 可选：扩展信息
      appVersion: '1.0.0',
      userId: '12345',
    },
    getReportParams: () => {         // 可选：动态获取上报参数
      return {
        userId: uni.getStorageSync('userId'),
        token: uni.getStorageSync('token'),
      };
    },
  });
  
  app.use(lokiReport);
  
  return { app };
}

2. TypeScript 类型声明（可选）

如果使用 TypeScript，在项目根目录的 env.d.ts 文件中添加类型声明：

declare interface Uni {
  /**
   * Loki 日志上报方法
   * @param data 要上报的数据
   * @param level 日志级别，可选值：'info' | 'error'，默认 'info'
   */
  $loki_report: (
    data: unknown,
    level?: 'info' | 'error'
  ) => Promise<void>;
}

3. 上报日志

初始化后，可以通过 uni.$loki_report 在任意位置调用：

// 上报普通信息
uni.$loki_report({
  action: 'button_click',
  pageName: 'home',
});

// 上报错误信息
uni.$loki_report({
  errorMessage: 'Network request failed',
  errorCode: 500,
}, 'error');

// 带自定义标签上报
uni.$loki_report(
  { event: 'user_login' },
  'info',
  { module: 'auth', action: 'login' }
);

API 文档

createLokiReport(config: ReportConfig)

创建 Loki 上报插件实例。

参数：

interface ReportConfig {
  job: string;                                    // 应用名称，用于区分不同应用
  url: string;                                    // Loki 服务地址
  isReport: boolean;                              // 是否启用上报
  extendsInfo?: Record<string, unknown>;          // 扩展信息，会合并到每次上报中
  debug?: boolean;                                // 是否开启调试模式
  getReportParams?: () => Record<string, unknown>; // 动态获取上报参数的函数
}

返回值： 返回一个 Vue 插件对象，可通过 app.use() 安装

示例：

const lokiReport = createLokiReport({
  job: 'mini-program',
  url: 'https://loki.example.com/loki/api/v1/push',
  isReport: true,
  debug: process.env.NODE_ENV === 'development',
  extendsInfo: {
    version: '1.0.0',
  },
});

app.use(lokiReport);

uni.$loki_report(data, level?, labels?)

上报日志数据（挂载在 uni 对象上的全局方法）。

参数：

• data (unknown): 要上报的数据，可以是任意 JSON 可序列化的数据
• level (ReportLevel): 可选，日志级别，可选值：'info' | 'error'，默认 'info'
• labels (Record<string, string>): 可选，自定义标签，用于日志筛选

返回值： Promise<void>

示例：

// 基础用法
uni.$loki_report({ event: 'page_view' });

// 指定日志级别
uni.$loki_report({ error: 'API failed' }, 'error');

// 添加自定义标签
uni.$loki_report(
  { action: 'purchase' },
  'info',
  { module: 'order', type: 'payment' }
);

uni.getUniReportConfig()

获取当前上报配置。

返回值： Readonly<Partial<ReportConfig>>

示例：

const config = uni.getUniReportConfig?.();
console.log(config?.job); // 'mini-program'

uni.uniReportsetConfig(config)

更新部分配置，会与现有配置合并。

参数： config (Partial)

示例：

// 动态启用/禁用上报
uni.uniReportsetConfig?.({ isReport: false });

// 更新扩展信息
uni.uniReportsetConfig?.({
  extendsInfo: {
    userId: '12345',
  },
});

使用场景

uni.$loki_report({ event: 'page_view', pageName: 'product_detail', pageParams: this.$route.query, }); }

### 2. 用户行为追踪

```typescript
// 按钮点击
handleButtonClick() {
  uni.$loki_report({
    event: 'button_click',
    buttonName: 'submit_order',
    pageName: 'checkout',
  });
}

// 表单提交
handleSubmit(formData) {
  uni.$loki_report({
    event: 'form_submit',
    formType: 'user_info',
    success: true,
  });
}

3. 错误监控

// API 请求错误
try {
  const res = await uni.request({ url: '/api/data' });
} catch (error) {
  uni.$loki_report({
    event: 'api_error',
    url: '/api/data',
    errorMessage: error.message,
    errorStack: error.stack,
  }, 'error');
}

// 全局错误捕获
App.onError((error) => {
  uni.$loki_report({
    event: 'app_error',
    errorMessage: error,
  }, 'error');
});

4. 性能监控

// 页面加载耗时
onLoad() {
  const startTime = Date.now();
  
  // ... 数据加载
  
  uni.$loki_report({
    event: 'page_performance',
    pageName: 'home',
    loadTime: Date.now() - startTime,
  });
}

5. 业务数据上报

// 订单创建
createOrder(orderData) {
  uni.$loki_
### 5. 业务数据上报

```typescript
// 订单创建
createOrder(orderData) {
  lokiReport.report({
    event: 'order_created',
    orderId: orderData.id,
    amount: orderData.amount,
    itemCount: orderData.items.length,
  }, 'info', {
    module: 'order',
    action: 'create',
  });
}

自动采集的信息

SDK 会自动采集以下设备和平台信息，无需手动传入：

• uniPlatform: uni-app 运行平台
• uniRuntimeVersion: uni-app 运行时版本
• model: 设备型号
• platform: 客户端平台
• deviceId: 设备 ID
• benchmarkLevel: 设备性能等级
• brand: 设备品牌
• version: 微信版本号
• system: 操作系统版本
• SDKVersion: 客户端基础库版本
• router: 当前页面路由
• host: 宿主信息
• networkInfo: 网络类型信息
• pagesOptions: 页面参数（仅错误级别上报时包含）

配置说明

Debug 模式

开启 debug 模式后，每次上报都会在控制台输出详细的参数信息：

lokiReport.init({
  // ...其他配置
  debug: true,  // 开发环境建议开启
});

动态参数

使用 getReportParams 可以在每次上报时动态获取最新的参数：

const lokiReport = createLokiReport({
  // ...其他配置
  getReportParams: () => {
    return {
      userId: uni.getStorageSync('userId'),
      sessionId: uni.getStorageSync('sessionId'),
      timestamp: Date.now(),
    };
  },
});

扩展信息

extendsInfo 会在初始化时设置，并合并到每次上报中：

const lokiReport = createLokiReport({
  // ...其他配置
  extendsInfo: {
    appVersion: '1.0.0',
    environment: 'production',
    channel: 'wechat',
  },
});

控制上报开关

可以通过 isReport 字段控制是否启用上报：

// 初始化时设置
const lokiReport = createLokiReport({
  // ...其他配置
  isReport: process.env.NODE_ENV === 'production',
});

// 运行时动态切换
uni.uniReportsetConfig?.({
  isReport: false,  // 关闭上报
});

注意事项

1. WMPF 环境自动跳过：SDK 会自动检测 WMPF 环境并跳过上报
2. 配置校验：未配置 url 和 job 时会输出警告并跳过上报
3. 网络超时：上报请求超时时间为 30 秒
4. 错误处理：上报失败不会影响业务逻辑，错误信息会在控制台输出
5. 数据格式：上报的数据需要能够被 JSON.stringify 序列化

TypeScript 支持

SDK 提供完整的 TypeScript 类型定义。在项目根目录的 env.d.ts 中添加类型声明：

// env.d.ts
declare interface Uni {
  /**
   * Loki 日志上报方法
   * @param data 要上报的数据
   * @param level 日志级别，可选值：'info' | 'error'，默认 'info'
   * @param labels 可选的自定义标签，用于日志筛选
   */
  $loki_report: (
    data: unknown,
    level?: 'info' | 'error',
    labels?: Record<string, string>
  ) => Promise<void>;

  /**
   * 获取 Loki 上报配置
   */
  getUniReportConfig?: () => Readonly<Partial<import('@zippybee/loki-report').ReportConfig>>;

  /**
   * 设置 Loki 上报配置
   */
  uniReportsetConfig?: (config: Partial<import('@zippybee/loki-report').ReportConfig>) => void;
}

使用示例：

import { createLokiReport, ReportConfig } from '@zippybee/loki-report';

// 配置对象有完整的类型提示
const config: ReportConfig = {
  job: 'my-app',
  url: 'https://loki.example.com/loki/api/v1/push',
  isReport: true,
  debug: false,
};

const lokiReport = createLokiReport(config);
app.use(lokiReport);

// 使用时有完整的类型提示
uni.$loki_report({ event: 'test' }, 'info');

最佳实践

1. 统一封装

建议封装一层业务日志方法：

// utils/logger.ts
export const logger = {
  // 页面访问
  pageView(pageName: string, params?: Record<string, unknown>) {
    uni.$loki_report({
      event: 'page_view',
      pageName,
      params,
    });
  },
  
  // 用户行为
  userAction(action: string, data?: Record<string, unknown>) {
    uni.$loki_report({
      event: 'user_action',
      action,
      ...data,
    }, 'info', { module: 'user' });
  },
  
  // 错误上报
  error(error: Error, context?: Record<string, unknown>) {
    uni.$loki_report({
      event: 'error',
      errorMessage: error.message,
      errorStack: error.stack,
      ...context,
    }, 'error');
  },
};

2. 环境区分

const isDev = process.env.NODE_ENV === 'development';

const lokiReport = createLokiReport({
  job: isDev ? 'my-app-dev' : 'my-app-prod',
  url: isDev 
    ? 'https://loki-dev.example.com/loki/api/v1/push'
    : 'https://loki.example.com/loki/api/v1/push',
  isReport: !isDev,  // 开发环境不上报
  debug: isDev,      // 开发环境开启调试
});

app.use(lokiReport);

3. 性能优化

避免上报过于频繁或数据量过大：

// 使用防抖
import { debounce } from 'lodash';

const reportScroll = debounce((scrollTop: number) => {
  uni.$loki_report({ event: 'scroll', scrollTop });
}, 1000);

// 限制数据大小
const reportData = (data: unknown) => {
  const dataStr = JSON.stringify(data);
  if (dataStr.length > 10000) {
    console.warn('上报数据过大，已截断');
    return;
  }
  uni.$loki_report(data);
};

许可证

ISC

更新日志

v1.0.24

• 初始版本发布
• 支持基础日志上报功能
• 支持自定义参数和标签