行协议 #

行协议定义：

概念
├── InfluxDB的文本写入格式
├── 类似CSV的单行格式
├── 高效紧凑的数据表示
└── HTTP API写入的标准格式

特点
├── 易于阅读和编写
├── 高效的解析性能
├── 支持批量写入
└── 跨语言兼容

行协议语法：

measurement[,tag_key=tag_value...] field_key=field_value[,field_key=field_value...] [timestamp]

组成部分：
├── measurement（必需）：度量名称
├── tag_set（可选）：标签键值对
├── field_set（必需）：字段键值对
└── timestamp（可选）：时间戳

# 最简单的数据点
temperature value=23.5

# 带标签
temperature,location=room1 value=23.5

# 带时间戳
temperature,location=room1 value=23.5 1704067200000000000

# 多标签多字段
cpu,host=server01,region=us-west usage=78.5,idle=21.5i,enabled=true 1704067200000000000

Measurement规则：

命名规范
├── 必须在行首
├── 不能包含空格
├── 区分大小写
└── 建议使用小写

转义字符
├── 逗号 ,
├── 空格
└── 反斜杠 \

示例
├── temperature
├── cpu_usage
├── http_requests
└── my\ measurement  (转义空格)

# 简单measurement
temperature value=23.5

# 带下划线
cpu_usage value=78.5

# 带转义
my\ measurement value=100

# 带逗号（需转义）
cpu\,memory value=50

Tag规则：

格式
├── key=value形式
├── 多个tag用逗号分隔
├── 位于measurement之后
└── 与field用空格分隔

特点
├── 自动索引
├── 仅支持字符串类型
├── 用于查询过滤和分组
└── 建议低基数

转义
├── 逗号 ,
├── 等号 =
├── 空格
└── 反斜杠 \

# 单个tag
temperature,location=room1 value=23.5

# 多个tag
temperature,location=room1,floor=1st value=23.5

# tag值带空格（需转义）
temperature,location=room\ 1 value=23.5

# tag值带逗号（需转义）
temperature,location=room\,1 value=23.5

# tag键带特殊字符
temperature,location\-name=room1 value=23.5

Tag设计建议：

推荐
├── 使用低基数值
├── 用于分组和过滤
├── 值建议小于100字节
└── 数量建议少于10个

示例
├── host=server01
├── region=us-west
├── env=production
└── app=myapp

避免
├── 高基数值（如用户ID）
├── 时间戳作为tag
├── 频繁变化的值
└── 过长的tag值

Field规则：

格式
├── key=value形式
├── 多个field用逗号分隔
├── 位于tag之后（或measurement）
└── 必须至少有一个field

数据类型
├── float：数字（默认）
├── integer：数字 + i
├── uinteger：数字 + u
├── string：双引号包裹
└── boolean：true/false

转义
├── 逗号 ,
├── 等号 =
├── 空格
└── 双引号 "（字符串内）

# 浮点数（默认）
temperature value=23.5

# 整数（带i后缀）
counter count=100i

# 无符号整数（带u后缀）
bytes total=1024u

# 字符串（双引号）
log message="Hello World"

# 布尔值
status enabled=true

# 多种类型组合
metrics cpu=78.5,count=100i,active=true,name="server01"

字符串field规则：

基本格式
├── 双引号包裹
├── 支持转义字符
└── UTF-8编码

转义字符
├── \" - 双引号
├── \\ - 反斜杠
├── \n - 换行
└── \t - 制表符

示例
├── message="Hello World"
├── message="Hello \"World\""
├── message="Line1\nLine2"
└── message="Path: C:\\Users"

Field设计建议：

数值类型选择
├── 需要小数 → float
├── 整数计数 → integer
├── 大数值ID → uinteger
└── 百分比 → float

命名建议
├── 使用描述性名称
├── 保持一致性
├── 避免特殊字符
└── 使用下划线分隔

示例
├── cpu_usage=78.5
├── request_count=100i
├── response_time=23.5
└── error_rate=0.01

时间戳规则：

格式
├── Unix时间戳
├── 默认纳秒精度
├── 位于field之后
└── 用空格分隔

精度选项
├── ns - 纳秒（默认）
├── us - 微秒
├── ms - 毫秒
├── s - 秒
└── RFC3339格式

省略
├── 可省略时间戳
└── 使用服务器当前时间

# 纳秒精度（默认）
temperature value=23.5 1704067200000000000

# 毫秒精度（需指定precision=ms）
temperature value=23.5 1704067200000

# 秒精度（需指定precision=s）
temperature value=23.5 1704067200

# RFC3339格式
temperature value=23.5 2024-01-01T00:00:00Z

# 省略时间戳（使用当前时间）
temperature value=23.5

# 写入时指定精度
curl -X POST "http://localhost:8086/api/v2/write?precision=ms" \
    --header "Authorization: Token YOUR_TOKEN" \
    --data "temperature value=23.5 1704067200000"

# 可用精度值
# ns - 纳秒
# us - 微秒
# ms - 毫秒
# s - 秒

需要转义的字符：

元素          需转义字符
────────────────────────────────
measurement   逗号, 空格, 反斜杠\
tag key       逗号, 等号=, 空格, 反斜杠\
tag value     逗号, 等号=, 空格, 反斜杠\
field key     逗号, 等号=, 空格, 反斜杠\
field value   双引号", 反斜杠\ (仅字符串)

# measurement转义
my\ measurement value=100
cpu\,memory value=50

# tag转义
location=room\ 1
location=room\=1
location=room\,1

# field key转义
cpu\ usage=78.5

# field value字符串转义
message="Hello \"World\""
message="Path: C:\\Users"
message="Line1\nLine2"

转义建议：

推荐做法
├── 避免使用特殊字符
├── 使用下划线代替空格
├── 使用连字符代替逗号
└── 保持命名简洁

不推荐
├── measurement: "my measurement"
├── tag: "location=room 1"
└── field: "cpu,usage"

推荐替代
├── measurement: "my_measurement"
├── tag: "location=room_1"
└── field: "cpu_usage"

批量写入格式：

每行一个数据点
├── 用换行符分隔
├── 共享相同的组织/Bucket
└── 可以不同的measurement

示例：
temperature,location=room1 value=23.5 1704067200000000000
temperature,location=room2 value=24.0 1704067200000000000
temperature,location=room1 value=23.8 1704067260000000000
cpu,host=server01 usage=78.5 1704067200000000000
memory,host=server01 used=8192i 1704067200000000000

# 批量写入多个数据点
curl -X POST "http://localhost:8086/api/v2/write?org=my-org&bucket=my-bucket" \
    --header "Authorization: Token YOUR_TOKEN" \
    --data '
temperature,location=room1 value=23.5 1704067200000000000
temperature,location=room2 value=24.0 1704067200000000000
temperature,location=room1 value=23.8 1704067260000000000
cpu,host=server01 usage=78.5 1704067200000000000
memory,host=server01 used=8192i 1704067200000000000
'

# CPU监控
cpu,host=server01,region=us-west,env=production usage_user=45.2,usage_system=12.3,usage_idle=42.5 1704067200000000000
cpu,host=server02,region=us-west,env=production usage_user=38.5,usage_system=15.2,usage_idle=46.3 1704067200000000000

# 内存监控
memory,host=server01,region=us-west total=16384i,used=8192i,free=8192i,usage_percent=50.0 1704067200000000000
memory,host=server02,region=us-west total=32768i,used=24576i,free=8192i,usage_percent=75.0 1704067200000000000

# 磁盘监控
disk,host=server01,path=/,type=ssd total=500i,used=250i,free=250i,usage_percent=50.0 1704067200000000000

# 温湿度传感器
sensor,device=sensor01,type=temperature,location=warehouse temperature=23.5,humidity=65.2 1704067200000000000
sensor,device=sensor02,type=temperature,location=office temperature=22.8,humidity=55.0 1704067200000000000

# 压力传感器
sensor,device=sensor03,type=pressure,location=factory pressure=101.325,status="normal" 1704067200000000000

# 设备状态
device,device_id=device001,status=online,battery_level=85i,last_seen="2024-01-01T00:00:00Z" 1704067200000000000

# HTTP请求
http_requests,service=api,endpoint=/users,method=GET,status=200 count=100i,latency_ms=23.5,error_count=0i 1704067200000000000
http_requests,service=api,endpoint=/orders,method=POST,status=201 count=50i,latency_ms=45.2,error_count=2i 1704067200000000000

# 数据库查询
db_query,database=mysql,query_type=SELECT count=500i,avg_time_ms=12.3,max_time_ms=150.5 1704067200000000000

# 缓存命中
cache,service=api,type=redis hits=800i,misses=200i,hit_rate=0.8 1704067200000000000

常见错误示例：

❌ 缺少field
temperature,location=room1

❌ field格式错误
temperature value=23.5,24.0

❌ tag在field之后
temperature value=23.5,location=room1

❌ 时间戳格式错误
temperature value=23.5 2024-01-01

❌ 整数缺少后缀
counter count=100

✅ 正确格式
temperature,location=room1 value=23.5 1704067200000000000
counter count=100i

类型错误示例：

❌ 字符串未加引号
log message=Hello World

❌ 布尔值使用引号
status enabled="true"

❌ 整数使用小数点
counter count=100.0i

✅ 正确格式
log message="Hello World"
status enabled=true
counter count=100i

转义错误示例：

❌ 未转义特殊字符
my measurement value=100
location=room 1 value=23.5

❌ 字符串内引号未转义
message="Hello "World""

✅ 正确格式
my\ measurement value=100
location=room\ 1 value=23.5
message="Hello \"World\""

使用InfluxDB CLI验证：

# 写入并查看错误
influx write \
    --bucket my-bucket \
    --org my-org \
    --precision s \
    "temperature,location=room1 value=23.5 1704067200"

# 查询验证
influx query 'from(bucket: "my-bucket")
    |> range(start: -1h)
    |> filter(fn: (r) => r._measurement == "temperature")'

# Python验证示例
from influxdb_client import Point

# 创建数据点
point = Point("temperature") \
    .tag("location", "room1") \
    .field("value", 23.5) \
    .time(1704067200000000000)

# 获取行协议
line_protocol = point.to_line_protocol()
print(line_protocol)
# 输出: temperature,location=room1 value=23.5 1704067200000000000