[PROPOSAL] Add `client_id` to `Settings` and `extra_info` to `UserAgent` for better client-side metadata reporting
- Dominant language
- Starlark
- Stars
- 32
- Forks
- 26
- PR merge metrics
- No merged PRs in 30d
Description
https://github.com/apache/rocketmq-apis/blob/68c2cc9442928f769f8938515a05af6fa05c9993/apache/rocketmq/v2/definition.proto#L497
### Motivation
Currently, client identity and metadata are reported to the broker **per-request via gRPC headers**. This makes it difficult for the broker to maintain a stable, per-client view of active connections, and limits the ability to implement fine-grained client management, observability, and extensibility on the server side.
### Proposal
**1. Add `client_id` to `Settings`**
The client ID already follows established conventions in the codebase. This simply exposes it as a first-class field in `Settings`, so the broker has a stable client identity available at session establishment via `TelemetryCommand`, without reassembling it from per-request headers.
```protobuf
message Settings {
// ... existing fields ...
optional string client_id = ;
}
```
**2. Add `extra_info` to `UserAgent`**
`UserAgent` already captures `language`, `version`, and `platform`. Adding a `map extra_info` field makes it an extensible carrier for arbitrary client metadata (e.g. hostname, deployment environment, business tags), without any protocol schema changes on the client's part for future additions.
```protobuf
message UserAgent {
// ... existing fields ...
map extra_info = ;
}
```
### Benefits
- Broker can identify and manage individual clients precisely at the session level.
- Enables richer observability and easier troubleshooting without relying solely on per-request headers.
- `extra_info` is forward-compatible: new attributes can be added by clients without proto changes.
- Foundation for advanced server-side features: targeted config push, per-client rate limiting, connection auditing, etc.
### Backward Compatibility
Both fields are optional / map. Existing clients that do not populate them continue to work without any change.
中文
## [提案] 在 `Settings` 中增加 `client_id`,在 `UserAgent` 中增加 `extra_info`
### 动机
当前客户端身份与元数据是通过**每次 gRPC 请求的 Header** 上报给 Broker 的。这使得 Broker 难以建立稳定的单客户端视图,也限制了服务端实现精细化客户端管理、可观测性与扩展能力的空间。
### 提案内容
**1. 在 `Settings` 中增加 `client_id`**
client_id 的生成规则已在代码库中有明确定义,此处只需将其作为一个正式字段暴露在 `Settings` 中。这样 Broker 在通过 `TelemetryCommand` 建立会话时即可获得稳定的客户端身份,而无需再从每次请求 Header 中重建。
```protobuf
message Settings {
// ... 现有字段 ...
optional string client_id = <下一个字段编号>;
}
```
**2. 在 `UserAgent` 中增加 `extra_info`**
`UserAgent` 已包含 `language`、`version`、`platform` 等字段。增加 `map extra_info` 将其扩展为可承载任意客户端元数据的开放展专(如主机名、部署环境、业务标签等),未来新增属性无需修改 proto schema。
```protobuf
message UserAgent {
// ... 现有字段 ...
map extra_info = <下一个字段编号>;
}
```
### 改进点
- Broker 可在会话级别精确识别和管理单个客户端。
- 增强可观测性,方便问题排查,不再完全依赖每次请求的 Header。
- `extra_info` 前向兼容,客户端新增属性无需改动 proto。
- 为服务端高级功能奠定基础:定向配置下推、单客户端限流、连接审计等。
### 向后兼容性
两个字段均为 optional / map 类型。未填充这些字段的存量客户端无需任何修改即可继续正常工作。
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with apache/rocketmq/v2/definition.proto around line 497 and inspect the Settings and UserAgent messages, then trace how Settings is carried by TelemetryCommand. Confirm the next compatible field numbers and how the existing client_id convention and UserAgent metadata are represented. Done means both optional fields are defined without breaking existing clients and the schema supports the proposed session metadata.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- grpc
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100