Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

doc(observability): add grpc metadata guide && format test code (#1807)

baojun-zhang21c8d08d6cfe
diff --git a/docs/en/concepts/12-metrics.md b/docs/en/concepts/12-metrics.md
index ccc06e3ab..badbb10e0 100644
--- a/docs/en/concepts/12-metrics.md
+++ b/docs/en/concepts/12-metrics.md
@@ -380,6 +380,7 @@ Key fields:
- `server.observability.metrics.exporters.otel.service_name`: OTLP `service.name` resource attribute (default `"openviking-server"`)
- `server.observability.metrics.exporters.otel.export_interval_ms`: OTLP push interval in milliseconds (default `10000`)
- `server.observability.metrics.exporters.otel.headers`: optional custom OTLP headers; sent as gRPC metadata for gRPC and HTTP headers for HTTP
+- When using gRPC, header keys in `headers` should be lowercase, for example `x-byteapm-appkey`; HTTP does not have this restriction
Example:
diff --git a/docs/en/guides/05-observability.md b/docs/en/guides/05-observability.md
index 38553c4de..33db809ee 100644
--- a/docs/en/guides/05-observability.md
+++ b/docs/en/guides/05-observability.md
@@ -333,6 +333,7 @@ Notes:
- `headers` forwards custom OTLP request headers or gRPC metadata to the exporter.
- This is useful when an OTLP backend requires extra auth headers for direct ingestion.
- The `headers` shape is the same across `traces`, `logs`, and `metrics.exporters.otel`.
+- When `protocol="grpc"`, `headers` are sent as gRPC metadata and keys should be lowercase, for example `x-byteapm-appkey`; this restriction does not apply to `protocol="http"`.
For full fields, supported ranges, and more examples, see:
diff --git a/docs/zh/concepts/12-metrics.md b/docs/zh/concepts/12-metrics.md
index b9201269a..7c8ff2c77 100644
--- a/docs/zh/concepts/12-metrics.md
+++ b/docs/zh/concepts/12-metrics.md
@@ -383,6 +383,7 @@ scrape_configs:
- `server.observability.metrics.exporters.otel.service_name`:OTLP `service.name` 资源属性(默认 `"openviking-server"`)
- `server.observability.metrics.exporters.otel.export_interval_ms`:OTLP 推送间隔,单位毫秒(默认 `10000`)
- `server.observability.metrics.exporters.otel.headers`:可选的自定义 OTLP 请求头;gRPC 会作为 metadata 发送,HTTP 会作为 headers 发送
+- 使用 gRPC 时,`headers` 中的 key 需要使用小写形式,例如 `x-byteapm-appkey`;HTTP 不受该限制
示例:
diff --git a/docs/zh/guides/05-observability.md b/docs/zh/guides/05-observability.md
index 385efd178..1ec343a62 100644
--- a/docs/zh/guides/05-observability.md
+++ b/docs/zh/guides/05-observability.md
@@ -332,6 +332,7 @@ OpenViking 将信号级别的可观测性配置统一放在 `server.observabilit
- `headers` 用于给 OTLP exporter 透传自定义请求头或 gRPC metadata。
- 常见场景包括直连需要额外鉴权头的 OTLP 后端;请只配置 header key/value,不要把敏感值写入日志或截图中。
- 对 `traces`、`logs` 和 `metrics.exporters.otel` 三条链路,`headers` 的配置方式保持一致。
+- 当 `protocol="grpc"` 时,`headers` 会作为 gRPC metadata 发送,key 需要使用小写形式,例如 `x-byteapm-appkey`;该限制不适用于 `protocol="http"`。
完整字段、支持范围和更多示例见:
diff --git a/tests/metrics/core/test_exporter.py b/tests/metrics/core/test_exporter.py
index 42702aec1..c879ccede 100644
--- a/tests/metrics/core/test_exporter.py
+++ b/tests/metrics/core/test_exporter.py
@@ -142,7 +142,7 @@ def test_otel_grpc_send_forwards_custom_metadata(registry):
enabled=False,
protocol="grpc",
endpoint="apmplus-cn-beijing.ivolces.com:4317",
- headers={"X-ByteAPM-AppKey": "metric-appkey"},
+ headers={"x-byteapm-appkey": "metric-appkey"},
)
class _FakeStub:
@@ -163,5 +163,5 @@ def test_otel_grpc_send_forwards_custom_metadata(registry):
exporter._send_grpc_request(ExportMetricsServiceRequest())
- assert exporter._grpc_stub.metadata == [("X-ByteAPM-AppKey", "metric-appkey")]
+ assert exporter._grpc_stub.metadata == [("x-byteapm-appkey", "metric-appkey")]
assert exporter._grpc_stub.timeout == 5.0
diff --git a/tests/test_telemetry_runtime.py b/tests/test_telemetry_runtime.py
index 061896c11..793bae181 100644
--- a/tests/test_telemetry_runtime.py
+++ b/tests/test_telemetry_runtime.py
@@ -282,13 +282,13 @@ def test_init_tracer_forwards_headers_to_grpc_exporter(monkeypatch):
service_name="memorydb",
protocol="grpc",
insecure=True,
- headers={"X-ByteAPM-AppKey": "trace-appkey"},
+ headers={"x-byteapm-appkey": "trace-appkey"},
enabled=True,
)
assert captured["endpoint"] == "apmplus-cn-beijing.ivolces.com:4317"
assert captured["insecure"] is True
- assert captured["headers"] == {"X-ByteAPM-AppKey": "trace-appkey"}
+ assert captured["headers"] == {"x-byteapm-appkey": "trace-appkey"}
def test_init_tracer_forwards_headers_to_http_exporter(monkeypatch):
@@ -389,14 +389,14 @@ def test_init_otel_log_handler_forwards_headers_to_grpc_exporter(monkeypatch):
endpoint="apmplus-cn-beijing.ivolces.com:4317",
service_name="memorydb",
insecure=True,
- headers={"X-ByteAPM-AppKey": "log-appkey"},
+ headers={"x-byteapm-appkey": "log-appkey"},
enabled=True,
)
assert handler is not None
assert captured["endpoint"] == "apmplus-cn-beijing.ivolces.com:4317"
assert captured["insecure"] is True
- assert captured["headers"] == {"X-ByteAPM-AppKey": "log-appkey"}
+ assert captured["headers"] == {"x-byteapm-appkey": "log-appkey"}
def test_init_otel_log_handler_forwards_headers_to_http_exporter(monkeypatch):