[PROPOSAL] Add `client_id` to `Settings` and `extra_info` to `UserAgent` for better client-side metadata reporting

[leizhiyuan]

rocketmq-apis/apache/rocketmq/v2/definition.proto

Line 497 in 68c2cc9

optional ClientType client_type = 1;

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.

message Settings {
  // ... existing fields ...
  optional string client_id = <next_field_number>;
}

2. Add extra_info to UserAgent

UserAgent already captures language, version, and platform. Adding a map<string, string> 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.

message UserAgent {
  // ... existing fields ...
  map<string, string> extra_info = <next_field_number>;
}

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 中重建。

message Settings {
  // ... 现有字段 ...
  optional string client_id = <下一个字段编号>;
}

2. 在 UserAgent 中增加 extra_info

UserAgent 已包含 language、version、platform 等字段。增加 map<string, string> extra_info 将其扩展为可承载任意客户端元数据的开放展专（如主机名、部署环境、业务标签等），未来新增属性无需修改 proto schema。

message UserAgent {
  // ... 现有字段 ...
  map<string, string> extra_info = <下一个字段编号>;
}

改进点

• Broker 可在会话级别精确识别和管理单个客户端。
• 增强可观测性，方便问题排查，不再完全依赖每次请求的 Header。
• extra_info 前向兼容，客户端新增属性无需改动 proto。
• 为服务端高级功能奠定基础：定向配置下推、单客户端限流、连接审计等。

向后兼容性

两个字段均为 optional / map 类型。未填充这些字段的存量客户端无需任何修改即可继续正常工作。

[fanlunyong]

这是来自QQ邮箱的自动回复邮件。   您好，请您放心您的邮件我已经收到。我将在看过邮件后，尽快给您回复。