[UPDATE] AMS(Ambari Metrics Service) 처리 로직 개편 : 사전 정의 및 하드코딩된 Catalog 방식(metrics_catalog.py) 에서 Metadata(6188) 실시간 조회 및 필터링 방식으로 정확도/효율성/유연성 향상 및 appId 처리 로직 고도화

Author: call518

README.md

@@ -139,10 +139,19 @@ Below is an example screenshot showing how to query the Ambari cluster using MCP
 
 ## 📈 Metrics & Trends
 
-- `list_common_metrics_catalog`: keyword search against the live metadata-backed metric catalog (cached locally). Use `search="heap"` or similar to narrow suggestions before running a time-series query.
-- `list_ambari_metric_apps`: list discovered AMS `appId` values, optionally including metric counts; pass `refresh=true` or `limit` to control output.
-- `query_ambari_metrics`: fetch time-series data; the tool auto-selects curated metric names, falls back to metadata search when needed, and honors Ambari's default precision unless you explicitly supply `precision="SECONDS"`, etc.
-- `list_ambari_metrics_metadata`: raw AMS metadata explorer for ad-hoc discovery (supports `app_id`, `metric_name_filter`, `host_filter`, `search` and adjustable `limit`, default 50).
+- **Terminology quick reference**
+  - **appId**: Ambari Metrics Service groups every metric under an application identifier (e.g., `namenode`, `datanode`, `ambari_server`, `HOST`). Think of it as the component or service emitting that timeseries.
+  - **metric name**: The fully qualified string Ambari uses for each timeseries (e.g., `jvm.JvmMetrics.MemHeapUsedM`, `dfs.datanode.BytesWritten`). Exact names are required when querying AMS.
+
+- `list_common_metrics_catalog`: keyword search against the live metadata-backed metric catalog (cached locally). Use `search="heap"` or similar to narrow suggestions before running a time-series query.  
+  _Example_: “Show the heap-related metrics available for the NameNode appId.”
+- `list_ambari_metric_apps`: list discovered AMS `appId` values, optionally including metric counts; pass `refresh=true` or `limit` to control output.  
+  _Example_: “List every appId currently exposed by AMS.”
+- The natural-language query “AMS에서 사용 가능한 appId 목록만 보여줘” maps to `list_ambari_metric_apps` and returns the exact identifiers you can copy into other tools.
+- `list_ambari_metrics_metadata`: raw AMS metadata explorer (supports `app_id`, `metric_name_filter`, `host_filter`, `search`, adjustable `limit`, default 50).  
+  _Example_: “Give me CPU-related metric metadata under HOST.”
+- `query_ambari_metrics`: fetch time-series data; the tool auto-selects curated metric names, falls back to metadata search when needed, and honors Ambari's default precision unless you explicitly supply `precision="SECONDS"`, etc.  
+  _Examples_: “Plot the last 30 minutes of `jvm.JvmMetrics.MemHeapUsedM` for the NameNode.” / “Compare `jvm.JvmMetrics.MemHeapUsedM` for DataNode hosts `bigtop-hostname0.demo.local` and `bigtop-hostname1.demo.local` over the past 30 minutes.”
 - `hdfs_dfadmin_report`: produce a DFSAdmin-style capacity/DataNode summary (mirrors `hdfs dfsadmin -report`).
 
 **Live Metric Catalog (via AMS metadata)**

src/mcp_ambari_api/prompt_template.md

@@ -359,10 +359,10 @@ Any suggestion to check elsewhere manually instead of using the API tools.
 - 💡 **Tip**: use `search="heap"`, `"gc"`, etc. to narrow the catalog, then copy the exact metric names for `query_ambari_metrics`.
 
 **query_ambari_metrics**
-- "query_ambari_metrics(metric_names=\"jvm.JvmMetrics.MemHeapUsedM\", app_id=\"namenode\", duration=\"1h\")"
-- "query_ambari_metrics(metric_names=\"dfs.FSNamesystem.SafeModeTime\", app_id=\"namenode\", duration=\"6h\")"
-- "query_ambari_metrics(metric_names=\"dfs.datanode.BytesWritten\", app_id=\"datanode\", duration=\"30m\", group_by_host=true)"
-- "query_ambari_metrics(metric_names=\"yarn.QueueMetrics.Queue=root.PendingMB\", app_id=\"resourcemanager\", duration=\"24h\")"
+- "Show the last hour of NameNode heap usage." → `query_ambari_metrics(metric_names="jvm.JvmMetrics.MemHeapUsedM", app_id="namenode", duration="1h")`
+- "Trend SafeMode time for the past 6 hours." → `query_ambari_metrics(metric_names="dfs.FSNamesystem.SafeModeTime", app_id="namenode", duration="6h")`
+- "Compare DataNode heap usage on bigtop-hostname0.demo.local and bigtop-hostname1.demo.local over 30 minutes." → `query_ambari_metrics(metric_names="jvm.JvmMetrics.MemHeapUsedM", app_id="datanode", duration="30m", hostnames="bigtop-hostname0.demo.local,bigtop-hostname1.demo.local", group_by_host=true)`
+- "Show pending YARN memory for the last day." → `query_ambari_metrics(metric_names="yarn.QueueMetrics.Queue=root.PendingMB", app_id="resourcemanager", duration="24h")`
 - 💡 **Tip**: Hostnames are optional—omit them for cluster-wide stats or specify explicit hosts to focus on particular nodes. If Ambari returns no datapoints, re-check the identifiers via `/ws/v1/timeline/metrics/metadata`.
 
 **hdfs_dfadmin_report**