From de1a5c28932e1ae8b8c7b3600132d050b425f8e5 Mon Sep 17 00:00:00 2001
From: IgorRachkov <89467086+igor04091968@users.noreply.github.com>
Date: Sun, 14 Jun 2026 14:36:56 +0300
Subject: [PATCH] docs(portal): document metrics contract

---
 adk-rust/crates/detmir-portal/src/production/metrics.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/adk-rust/crates/detmir-portal/src/production/metrics.rs b/adk-rust/crates/detmir-portal/src/production/metrics.rs
index 02f6639..99e34e6 100644
--- a/adk-rust/crates/detmir-portal/src/production/metrics.rs
+++ b/adk-rust/crates/detmir-portal/src/production/metrics.rs
@@ -1,3 +1,9 @@
+//! In-process Prometheus-style metrics for the portal.
+//!
+//! CONTRACT: metric names and label keys are part of the operational contract
+//! used by dashboards and smoke checks. Additive metrics are allowed; renaming
+//! existing metrics requires synchronized dashboard/documentation changes.
+
 use std::collections::BTreeMap;
 use std::fmt::Write as FmtWrite;
 use std::sync::{Mutex, OnceLock};
@@ -179,5 +185,7 @@ pub(crate) fn render_prometheus_metrics(args: &Cli) -> String {
 }
 
 fn prom_escape(value: &str) -> String {
+    // SECURITY: metric label values are route/module tokens, but escaping keeps
+    // the endpoint safe if future callers pass proxy-derived values.
     value.replace('\\', "\\\\").replace('"', "\\\"")
 }