measurementlab/jostler

Jostler Docker镜像文档

镜像概述

Jostler是Autoloading项目的上传代理，主要用于M-Lab节点的测量数据处理与上传。它支持两种运行模式：交互式本地模式（用于生成BigQuery表模式文件）和长时间运行的守护进程模式（作为测量容器的sidecar容器，监控并上传数据至GCS）。其核心目标是实现测量数据的自动化加载，避免手动解析，并确保节点磁盘空间有效管理。

核心功能与特性

运行模式

• 交互式本地模式：为指定数据类型生成BigQuery表模式文件，供操作员验证表结构。
• 守护进程模式：作为sidecar容器长期运行，通过inotify监控预定义目录的文件系统事件，处理并上传数据。

数据处理与上传

• 文件监控：使用inotify监听指定目录的文件创建/关闭事件，捕获JSON格式数据文件。
• 数据打包：将多个JSON文件合并为JSONL（JSON Lines）格式，压缩后生成数据 bundle。
• 触发机制：当bundle达到配置的最大大小（如30MB）或最大年龄（如3小时）时触发上传。
• GCS上传：将压缩后的bundle上传至指定GCS bucket，并生成对应的索引文件。
• 本地清理：成功上传后删除本地源文件；对无效文件（非.json格式、读取错误、无效JSON）直接删除，避免磁盘空间占用。

数据结构

• 标准列：每个JSONL条目包含date（数据日期）、archiver（Jostler元信息）和raw（原始测量数据）字段。
• 索引文件：为每个数据bundle生成索引文件，记录包含的源文件名列表，作为index1数据类型上传。

模式管理

• 数据类型模式：读取指定路径的JSON格式数据类型模式文件，生成包含M-Lab标准列的BigQuery表模式，并上传至GCS。

使用场景

• 测量数据上传：作为M-Lab节点测量容器的sidecar，自动处理并上传JSON格式测量数据。
• 表模式验证：操作员通过交互式模式生成并检查BigQuery表模式，确保数据结构符合预期。
• 节点数据管理：监控并清理本地文件，防止无效数据占用磁盘空间。

使用方法

交互式模式（生成表模式）

生成指定数据类型的BigQuery表模式文件：

bash
docker run --rm -v /path/to/datatypes:/var/spool/datatypes docker.xuanyuan.run/jostler \
  -schema \
  -datatype foo1 \
  -datatype bar1 \
  -datatype-file bar1:/var/spool/datatypes/bar1.json

参数说明：

• -schema：启用交互式模式
• -datatype：指定数据类型（可多个）
• -datatype-file：指定数据类型模式文件路径（格式：datatype:path）

守护进程模式（数据上传）

Docker Run示例

bash
docker run -d \
  -v /var/spool:/var/spool \
  -e GCS_BUCKET=pusher-mlab-oti \
  -e EXPERIMENT=ndt \
  -e DATATYPES=scamper1,foo1 \
  -e BUNDLE_MAX_SIZE=30MB \
  -e BUNDLE_MAX_AGE=3h \
  docker.xuanyuan.run/jostler

Docker Compose示例

yaml
version: '3'
services:
  jostler:
    image: docker.xuanyuan.run/jostler
    volumes:
      - /var/spool:/var/spool
    environment:
      - GCS_BUCKET=pusher-mlab-oti
      - HOME_FOLDER=autoload/v1
      - NODE_NAME=mlab2-gru01
      - BUNDLE_MAX_SIZE=30MB
      - BUNDLE_MAX_AGE=3h
      - HOME_DIR=/var/spool
      - EXTENSIONS=.json
      - EXPERIMENT=ndt
      - DATATYPES=scamper1,foo1
      - MIN_FILE_AGE=2h
      - SCAN_INTERVAL=5m
      - FLUSH_TIMEOUT=5m
    restart: always

配置参数

GCS配置

• GCS_BUCKET：GCS bucket名称（如pusher-mlab-sandbox、pusher-mlab-staging）
• HOME_FOLDER：GCS对象名前缀（默认autoload/v1）
• NODE_NAME：M-Lab节点名称，用于生成bundle文件名

包配置

• BUNDLE_MAX_SIZE：bundle最大大小（如30MB）
• BUNDLE_MAX_AGE：bundle最大存在时间（如3h）

文件系统配置

• HOME_DIR：测量数据根目录（默认/var/spool）
• EXTENSIONS：监控的文件扩展名（默认.json）
• EXPERIMENT：测量服务名称（如ndt）
• DATATYPES：数据类型列表（逗号分隔，如scamper1,foo1）
• MIN_FILE_AGE：文件最小修改时间（超过此时间视为遗漏文件，默认2h）
• SCAN_INTERVAL：遗漏文件扫描间隔（默认5m）

执行配置

• FLUSH_TIMEOUT：进程退出前刷新bundle的最大等待时间（默认5m）
• SCHEMA：启用交互式模式（生成表模式）
• VERBOSE：启用详细日志模式

数据路径与命名规范

本地路径

• 测量数据文件：/var/spool/<experiment>/<datatype>/<yyyy>/<mm>/<dd>/
• 数据类型模式文件：/var/spool/datatypes/<datatype>.json（默认）

GCS对象路径

• 表模式文件：autoload/v1/tables/<experiment>/<datatype>.table.json
• 数据bundle：autoload/v1/<experiment>/<datatype>/<yyyy>/<mm>/<dd>/<timestamp>-<datatype>-<node>-<experiment>-data.jsonl.gz
• 索引bundle：autoload/v1/<experiment>/<datatype>/<yyyy>/<mm>/<dd>/<timestamp>-<datatype>-<node>-<experiment>-index1.jsonl.gz

架构说明

Jostler包含以下核心组件：

• api：定义标准列和index1数据类型
• internal/gcs：处理GCS上传/下载
• internal/jsonlbundle：JSONL bundle处理逻辑
• internal/schema：数据类型和表模式处理
• internal/uploadbundle：本地文件打包与上传逻辑
• internal/watchdir：目录监控与文件事件通知

通过上述组件，Jostler实现了从文件监控、数据处理到GCS上传的全流程自动化，确保测量数据高效、安全地上传与管理。