# @beesolve/analytics-processor 中文文档

规范地址：https://npmcn.com/package/%40beesolve/analytics-processor/

版本：0\.10\.0
npm 元数据更新时间：2026-10-19T18:54:50.081Z
中文译文更新时间：2026-11-07T20:47:41.980Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40beesolve/analytics-processor
原文对照：https://npmcn.com/package/%40beesolve/analytics-processor/?lang=original
项目主页：https://github.com/BeeSolve/packages/tree/main/packages/analytics-processor#readme
源码仓库：https://github.com/BeeSolve/packages

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：21.6 MB，279 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：constructs ^10\.8\.1，typescript ^7\.0\.2，aws-cdk-lib ^2\.273\.0
- 首次发布：2026-10-12T14:33:28.408Z
- 最新版本发布：2026-10-19T18:54:49.715Z
- 近 30 天下载量：2687（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

CloudFront分析处理器 — Athena- to- DynamoDB 小时总和、分解和滚动

## 安装

```sh
npm install @beesolve/analytics-processor
```

也可以使用：`pnpm add @beesolve/analytics-processor`、`yarn add @beesolve/analytics-processor`、`bun add @beesolve/analytics-processor`

## README

# @ beesolve/分析-处理器

CloudFront分析处理器. 通过雅典娜阅读 CloudFront 标准日志 保持单表DynamoDB设计,每平方位计时总和 以及使用原子计数器更新的每日/月滚动 偶发性标记.

> \[尖叫声\] **前1.0——不稳定的API.** 这个软件包是 `0.x` 活动 发展。 打破的改变可以降落在任何 `0.x` 释放无主 版本凸起。 选中一个精确的版本并在升级前审查更改日志 . 一旦API稳定,包裹到达 `1.0.0`,它跟随语义 版本和此通知被删除 .

## 建筑

```
┌──────────────┐   hourly    ┌────────┐   ADD + marker   ┌──────────┐
│ CloudFront   │ ──────────► │ Athena │ ───────────────► │ DynamoDB │
│ v2 Parquet   │   query     │        │   (transaction)  │  totals  │
│ (S3 + Glue)  │             └────────┘                  │  breakdowns│
└──────────────┘                                         └──────────┘
                                                               ▲
                      daily / monthly rollups (read-back) ─────┘
```

一个小时的Lambda在关闭的Athena 上运行着一个分块的查询 小时v2Parquet数据并写总计 + 每分数细分 原子 `ADD` 更新,每小时守护一次 `applied#...` 已写入标记 有条件地在同一地点 `TransactWriteCommand`每日和每月滚动 Lambdas sum fineer-grain DynamoDB项目(从未重新征服雅典娜). 一次性 独立回填脚本将历史数据行走同一写道 (单位:千美元) `compact` 命令将遗留的 v1 日志重写到 v2 Parquet 形状, 因此 可以通过同一路径读取.

## 安装

```bash
npm install @beesolve/analytics-processor
```

## 出口

-   `.` - 计划/类型(`totalsSchema`编号 :`TotalsItem`, (中文(简体) ), `breakdownSchema`编号 :`BreakdownItem`, (中文(简体) ), `appliedMarkerSchema`编号 :`AppliedMarker`, (中文(简体) ), `configSchema`编号 :`AnalyticsConfig`, (中文(简体) ), `grains`编号 :`Grain`, (中文(简体) ), `dimensions`编号 :`Dimension`, (中文(简体) ), 时间/窗口助手( e)`hourKey`, (中文(简体) ), `dayKey`, (中文(简体) ), `monthKey`, (中文(简体) ), `maxWindowFor`, (中文(简体) ), `windowKeys`, (中文(简体) ), `shiftAnchor`, (中文(简体) ), `hoursBetween`, (中文(简体) ), `parsePeriodKey`, (中文(简体) ), `grainForPeriodKey`, (中文(简体) ), 示范班级(`Totals`, (中文(简体) ), `Breakdowns`, (中文(简体) ), `AppliedMarkers`, (中文(简体) ), `Config`, (中文(简体) ), `IpInfoCache` + 键 `lookupIpInfo` + 键 `IpInfo`编号 :`IpInfoCacheItem`, (中文(简体) ), 纯助行者`buildHourlyQuery`, (中文(简体) ), `classifyDevice`, (中文(简体) ), `sumTotals`, (中文(简体) ), `sumBreakdown`, (中文(简体) ), `topNWithOther`),活体综合解析器 (单位:千美元)`resolveTotalsLive`编号 :`resolveBreakdownLive`),以及 `processHour` (+ 数) `applyDailyRollup`编号 :`applyMonthlyRollup`) (中文(简体) ).
-   `./cdk` - 那个 `AnalyticsProcessor` CDK 构造 .

Lambda处理器不属于可导入的API. 业务 命令船舶作为可执行的垃圾箱—— `analytics-backfill`, (中文(简体) ), `analytics-watch-backfill`, (中文(简体) ), 财务报告和审定财务报表 `analytics-compact` - 可通过 `npx` (见 [如何引导](https://npmcn.com/package/%40beesolve/analytics-processor/docs/how-to/run-operational-commands.md)) (中文(简体) ).

## CDK 用户

```typescript
import { AnalyticsProcessor } from "@beesolve/analytics-processor/cdk";

const processor = new AnalyticsProcessor(this, "Analytics", {
  athenaDatabase: logging.glueDatabaseName,
  athenaV2Table: logging.glueTableName,
  athenaWorkgroup: logging.workgroupName,
  logBucketArn: logging.logBucket.bucketArn,
  athenaResultsBucketArn: logging.athenaResultsBucket.bucketArn,
  ipInfoApiKey: process.env.IPINFO_API_KEY,
});

// Grant read-only access to a dashboard Lambda. Sets ANALYTICS_TABLE_NAME and
// ANALYTICS_REVERSE_INDEX env vars on the handler.
processor.grantRead(dashboardLambda);
```

构筑条款:

-   DynamoDB表(按需,复合键) `pk`编号 :`sk`,反转GSI `reverse`, TTL) (中文(简体) )
-   三兰布达斯(第24节): `Hourly`, (中文(简体) ), `DailyRollup`, (中文(简体) ), `MonthlyRollup`
-   事件桥表:小时 `rate(1 hour)`日克龙`00:15`月克龙(`01:30` (第1个)
-   每小时Lambda的Athena/Glue/S3准入率最低

## 后补

> **成本警告 :** 如果您的来源是遗留的 v1 日志( 许多小 gzip 文件), 运行 [`compact`](https://npmcn.com/package/%40beesolve/analytics-processor/docs/how-to/compact-v1-logs.md) 第一和点 `ATHENA_TABLE` 在紧凑的桌子上。 直接回填一个原始 v1 表格使每个小时 s3 对象数以万计的查询风扇——至少雅典娜发行 每一个文件,它的成本 **几百元的S3 得到请求** 页:1 一个完整的回填。 收缩首先会降低到一分钱.

一次性回填脚本将历史日志数据通过相同的写法 路由作为小时Lambda。 它通过独一无二的力量是可以恢复的,而且是一成不变的 标记——已经应用的时数立即跳过. 它读出v2 Parquet表; 来回填充遗存 v1 日志, 第一次运行 [`compact`](https://npmcn.com/package/%40beesolve/analytics-processor/docs/how-to/compact-v1-logs.md) 将其重写为 v2 形状,然后点 `ATHENA_TABLE` 在紧凑的 页:1.

```bash
TABLE_NAME=... \
ATHENA_DATABASE=... ATHENA_TABLE=... ATHENA_WORKGROUP=... \
bun run backfill -- --from 2026-01-01T00:00:00Z --to 2026-01-31T23:00:00Z --concurrency 2 --rollups
```

-   `--from` 编号 : `--to` ——包容性ISO小时范围(需要).
-   `--concurrency` ——界限平行主义(默认2).
-   `--rollups` ——每小时填满后,每日和每月在范围上进行滚动.

证书通过默认 AWS SDK 链( 荣誉) 解决 `AWS_PROFILE`) (中文(简体) ).

## 压缩

这个 `compact` 命令转换遗留 v1 `LazySimpleSerDe` 将表格输入一个 v2 形状 Parquet 表格( 每小时一个文件分区, v1 列重命名为 v2 schema),所以查询停止在数以万计的微小S3上扇出 对象。 见 [如何引导](https://npmcn.com/package/%40beesolve/analytics-processor/docs/how-to/compact-v1-logs.md)。 。 。 .

```bash
bun run compact -- \
  --database cf_logs_db --source-table cf_logs_v1_backfill \
  --target-table cf_logs_v1_compact \
  --external-location s3://log-bucket/compact/v1/ \
  --workgroup primary --output-location s3://athena-results/ctas/ \
  --from 2025-10-16 --to 2026-10-13
```

## 常见问题

### @beesolve/analytics-processor 是什么？

CloudFront分析处理器 — Athena- to- DynamoDB 小时总和、分解和滚动

### 如何安装 @beesolve/analytics-processor？

在项目目录运行 npm install @beesolve/analytics-processor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.8\.1）、aws-cdk-lib（^2\.273\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 analytics-compact、analytics-backfill、analytics-watch-backfill，可以用 npx analytics-compact 直接运行。

### @beesolve/analytics-processor 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @beesolve/analytics-processor 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @beesolve/analytics-processor 可以商用吗？

@beesolve/analytics-processor 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @beesolve/analytics-processor 的下载量有多少？

根据 npm 官方下载统计，@beesolve/analytics-processor 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,687 次，日均约 90 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @beesolve/analytics-processor 还在维护吗？

最新版本 0\.10\.0 发布于 2026/10/20（19 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/10/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。