measurementlab/uuid-annotator

UUID-Annotator

镜像概述和主要用途

UUID-Annotator是一个运行在M-Lab边缘系统上的服务，用于实时生成和保存每个网络连接的元数据。它为每个连接生成包含IP地址的地理位置和网络位置元数据的JSON文件，并遵循M-Lab的统一命名规范和推送最佳实践。

核心功能和特性

元数据生成

• 为每个连接生成JSON格式的元数据文件，文件路径格式为/ndt/annotation/YYYY/MM/DD/${UUID}.json，其中${UUID}为连接的实际UUID
• 初始包含以下标准字段子集：
  • client.Geo.*：客户端地理位置信息
  • server.Geo.*：服务器地理位置信息
  • client.Network.ASNumber：客户端网络自治系统号
  • server.Network.ASNumber：服务器网络自治系统号

数据来源与更新

• 从GCS存储桶提供的MaxMind文件读取位置数据
• 以无记忆方式定期轮询文件变化，确保数据时效性

设计特性

• 遵循M-Lab的统一命名最佳实践和推送最佳实践
• 未来版本可扩展支持实时交换机计数器、本地机器负载等测量质量指标

性能与可用性

性能特点

• 依赖tcp-info的UUID通知服务，但无其他本地服务依赖于该注解器
• 需能跟上TCP连接的创建速率，目前预期无性能瓶颈

可用性要求

• 作为核心服务需保持高可用性，与tcp-info、packet-headers、traceroute-caller和DISCO同等重要
• 实验服务的健康状态应依赖于UUID注解器的健康状态

使用场景和适用范围

• 独立模式：仅需本地ipservice socket为特定IP提供注解时使用
• 自动加载管道：作为数据处理流程的一部分，生成数据类型模式

使用方法和配置说明

构建镜像

sh
docker build -t local-annotator .

独立模式运行

独立模式不需要tcpinfo.eventsocket、siteinfo.url或datadir标志，适用于仅需为特定IP提供注解的场景：

sh
docker run -v $PWD/testdata:/testdata -it local-annotator \
    -ipservice.sock=/local/uuid-annotator.sock \
    -maxmind.url=file:///testdata/GeoLite2-City-real.tar.gz \
    -routeview-v4.url=file:///testdata/RouteViewIPv4.pfx2as.gz \
    -routeview-v6.url=file:///testdata/RouteViewIPv6.pfx2as.gz

参数说明

• -ipservice.sock：本地ipservice socket路径
• -maxmind.url：MaxMind数据库文件URL（支持本地文件路径）
• -routeview-v4.url：IPv4路由视图数据文件URL
• -routeview-v6.url：IPv6路由视图数据文件URL

生成数据类型模式

当将uuid-annotator数据用于自动加载管道时，可使用generate-schemas命令生成数据类型模式：

sh
docker run -v $PWD:/schemas --entrypoint /generate-schemas -it local-annotator \
    -ann2 /schemas/ann2.json -hop2 /schemas/hop2.json

参数说明

• -ann2：ann2模式输出文件路径
• -hop2：hop2模式输出文件路径