Grafana

ทางการ

ค้นหาแดชบอร์ด ตรวจสอบเหตุการณ์ และสอบถามแหล่งข้อมูลในอินสแตนซ์ Grafana ของคุณ

GitHub
3.4k

คุณทำอะไรได้บ้างด้วย Grafana MCP?

  • ค้นหาและตรวจสอบแดชบอร์ด — ใช้ search_dashboards และ get_dashboard_summary เพื่อค้นหาแดชบอร์ดและรับภาพรวมแบบกระชับโดยไม่ต้องใช้ JSON เต็มรูปแบบ
  • สอบถาม Prometheus และ Loki — รันคำสั่ง PromQL และ LogQL กับแหล่งข้อมูลของคุณ รวมถึงข้อมูลเมตาและเปอร์เซ็นไทล์ของฮิสโตแกรม
  • จัดการการแจ้งเตือน — แสดงรายการ สร้าง อัปเดต และลบกฎการแจ้งเตือน พร้อมดูนโยบายการแจ้งเตือนและจุดติดต่อ
  • สร้างลิงก์ลึก — สร้าง URL ที่แม่นยำไปยังแดชบอร์ด แผง และ Explore พร้อมช่วงเวลาโดยใช้เครื่องมือนำทาง
  • รันคำสั่งแผง — ดำเนินการคำสั่งของแผงแดชบอร์ดด้วยช่วงเวลาและตัวแปรที่กำหนดเองโดยใช้ run_panel_query

เอกสาร

เซิร์ฟเวอร์ Grafana MCP

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

เซิร์ฟเวอร์ Model Context Protocol (MCP) สำหรับ Grafana

เครื่องมือนี้ให้การเข้าถึงอินสแตนซ์ Grafana ของคุณและระบบนิเวศโดยรอบ

เริ่มต้นใช้งานอย่างรวดเร็ว

ต้องมี uv เพิ่มข้อมูลต่อไปนี้ลงในการกำหนดค่า MCP client ของคุณ (เช่น Claude Desktop, Cursor):

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

สำหรับ Grafana Cloud ให้แทนที่ GRAFANA_URL ด้วย URL ของอินสแตนซ์ของคุณ (เช่น https://myinstance.grafana.net) ดู การใช้งาน สำหรับตัวเลือกการติดตั้งเพิ่มเติม เช่น Docker, binary และ Helm

ข้อกำหนด

  • ต้องใช้ Grafana เวอร์ชัน 9.0 ขึ้นไป สำหรับการทำงานเต็มรูปแบบ คุณสมบัติบางอย่าง โดยเฉพาะการดำเนินการที่เกี่ยวข้องกับ datasource อาจทำงานไม่ถูกต้องกับเวอร์ชันที่เก่ากว่า เนื่องจากไม่มี API endpoints ที่จำเป็น

คุณสมบัติ

คุณสมบัติต่อไปนี้พร้อมใช้งานใน MCP server ในปัจจุบัน รายการนี้มีไว้เพื่อให้ข้อมูลเท่านั้น และไม่ได้แสดงถึง roadmap หรือข้อผูกพันต่อคุณสมบัติในอนาคต

แดชบอร์ด

  • ค้นหาแดชบอร์ด: ค้นหาแดชบอร์ดด้วยชื่อหรือ metadata อื่น ๆ
  • รับแดชบอร์ดด้วย UID: ดึงรายละเอียดแดชบอร์ดทั้งหมดโดยใช้ตัวระบุเฉพาะ คำเตือน: แดชบอร์ดขนาดใหญ่อาจใช้พื้นที่ context window จำนวนมาก
  • รับสรุปแดชบอร์ด: รับภาพรวมแบบกระชับของแดชบอร์ด รวมถึงชื่อ จำนวน panel ประเภท panel ตัวแปร และ metadata โดยไม่ต้องใช้ JSON เต็มรูปแบบเพื่อลดการใช้ context window
  • รับคุณสมบัติของแดชบอร์ด: แยกส่วนเฉพาะของแดชบอร์ดโดยใช้นิพจน์ JSONPath (เช่น $.title, $.panels[*].title) เพื่อดึงข้อมูลที่จำเป็นเท่านั้นและลดการใช้ context window
  • อัปเดตหรือสร้างแดชบอร์ด: แก้ไขแดชบอร์ดที่มีอยู่หรือสร้างใหม่ คำเตือน: ต้องใช้ JSON แดชบอร์ดเต็มรูปแบบซึ่งอาจใช้พื้นที่ context window จำนวนมาก
  • แก้ไขแดชบอร์ดแบบเฉพาะจุด: ใช้การเปลี่ยนแปลงเฉพาะกับแดชบอร์ดโดยไม่ต้องใช้ JSON เต็มรูปแบบ ช่วยลดการใช้ context window อย่างมากสำหรับการแก้ไขแบบเจาะจง
  • รับข้อมูล queries และ datasource ของ panel: รับชื่อ สตริง query และข้อมูล datasource (รวมถึง UID และประเภท หากมี) จากทุก panel ในแดชบอร์ด

รัน Panel Query

หมายเหตุ: เครื่องมือรัน panel query ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม runpanelquery ใน flag --enabled-tools ของคุณ

  • รัน panel query: ดำเนินการ query ของ panel ในแดชบอร์ดด้วยช่วงเวลาและตัวแปรที่กำหนดเอง

การจัดการ Context Window

เครื่องมือแดชบอร์ดตอนนี้มีกลยุทธ์หลายอย่างเพื่อจัดการการใช้ context window อย่างมีประสิทธิภาพ (issue #101):

  • ใช้ get_dashboard_summary สำหรับภาพรวมแดชบอร์ดและการวางแผนการแก้ไข
  • ใช้ get_dashboard_property ร่วมกับ JSONPath เมื่อคุณต้องการเฉพาะบางส่วนของแดชบอร์ด
  • หลีกเลี่ยง get_dashboard_by_uid เว้นแต่คุณจำเป็นต้องใช้ JSON แดชบอร์ดที่สมบูรณ์จริง ๆ

Datasources

  • แสดงรายการและดึงข้อมูล datasource: ดู datasource ที่กำหนดค่าทั้งหมดและดึงข้อมูลโดยละเอียดเกี่ยวกับแต่ละรายการ
    • ประเภท datasource ที่รองรับ: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena

ตัวอย่าง Query

หมายเหตุ: เครื่องมือตัวอย่าง query ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม examples ใน flag --enabled-tools ของคุณ

  • รับตัวอย่าง query: ดึงตัวอย่าง query สำหรับประเภท datasource ต่าง ๆ เพื่อเรียนรู้ไวยากรณ์ query

การ Query Prometheus

  • Query Prometheus: ดำเนินการ query PromQL (รองรับทั้ง instant และ range metric queries) กับ datasource Prometheus
  • Query metadata ของ Prometheus: ดึง metric metadata, ชื่อ metric, ชื่อ label และค่าของ label จาก datasource Prometheus
  • Query เปอร์เซ็นไทล์ของ histogram: คำนวณค่าเปอร์เซ็นไทล์ของ histogram (p50, p90, p95, p99) โดยใช้ histogram_quantile

การ Query Loki

  • Query logs และ metrics ของ Loki: รันทั้ง log queries และ metric queries โดยใช้ LogQL กับ datasource Loki
  • Query metadata ของ Loki: ดึงชื่อ label ค่าของ label และสถิติ stream จาก datasource Loki
  • Query patterns ของ Loki: ดึง log patterns ที่ Loki ตรวจพบเพื่อระบุโครงสร้าง log ทั่วไปและความผิดปกติ

การ Query InfluxDB

หมายเหตุ: เครื่องมือ InfluxDB ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม influxdb ใน flag --enabled-tools ของคุณ

  • Query InfluxDB: ดำเนินการ query กับ datasource InfluxDB โดยใช้ InfluxQL (v1.x) หรือ Flux (v2.x) ภาษาถูกอนุมานจากการกำหนดค่า datasource หรือสามารถตั้งค่าได้อย่างชัดเจนผ่านพารามิเตอร์ dialect

การ Query ClickHouse

หมายเหตุ: เครื่องมือ ClickHouse ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม clickhouse ใน flag --enabled-tools ของคุณ

  • แสดงรายการตาราง ClickHouse: แสดงรายการตารางทั้งหมดในฐานข้อมูล ClickHouse พร้อมจำนวนแถวและขนาด
  • อธิบายโครงสร้างตาราง: รับชื่อคอลัมน์ ประเภท และ metadata สำหรับตาราง ClickHouse
  • Query ClickHouse: ดำเนินการ query SQL พร้อมการรองรับ Grafana macro และการแทนที่ตัวแปร

การ Query CloudWatch

หมายเหตุ: เครื่องมือ CloudWatch ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม cloudwatch ใน flag --enabled-tools ของคุณ

  • แสดงรายการ namespaces ของ CloudWatch: ค้นพบ AWS CloudWatch namespaces ที่พร้อมใช้งาน
  • แสดงรายการ metrics ของ CloudWatch: แสดงรายการ metrics ที่มีอยู่ใน namespace เฉพาะ
  • แสดงรายการ dimensions ของ CloudWatch: รับ dimensions สำหรับการกรอง metric queries
  • Query CloudWatch: ดำเนินการ CloudWatch metric queries พร้อมการรองรับช่วงเวลา

การ Query Graphite

หมายเหตุ: เครื่องมือ Graphite ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม graphite ใน flag --enabled-tools ของคุณ

  • Query Graphite: ดำเนินการ query ผ่าน Graphite render API กับ datasource Graphite
  • แสดงรายการ metrics ของ Graphite: เรียกดูและค้นพบเส้นทาง metric ของ Graphite
  • แสดงรายการ tags ของ Graphite: แสดงรายการ tags และค่าของ tag ที่พร้อมใช้งานใน Graphite
  • Query ความหนาแน่นของ Graphite: Query ความหนาแน่นของ metric Graphite สำหรับ pattern ที่กำหนด

การ Query Athena

หมายเหตุ: เครื่องมือ Athena ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม athena ใน flag --enabled-tools ของคุณ

  • แสดงรายการ catalogs ของ Athena: ค้นพบ data catalogs ที่พร้อมใช้งาน (เช่น AwsDataCatalog, ตัวเชื่อมต่อ Iceberg)
  • แสดงรายการฐานข้อมูล Athena: แสดงรายการฐานข้อมูลใน catalog ของ Athena
  • แสดงรายการตาราง Athena: แสดงรายการตารางในฐานข้อมูล Athena
  • อธิบายตาราง Athena: รับชื่อคอลัมน์สำหรับตาราง Athena
  • Query Athena: ดำเนินการ query SQL กับ Amazon Athena ผ่าน Grafana พร้อมการแทนที่ macro การบังคับขีดจำกัด และการรองรับ template variables

การ Query Snowflake

หมายเหตุ: เครื่องมือ Snowflake ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม snowflake ใน flag --enabled-tools ของคุณ

Query ผ่าน datasource Snowflake ของ Grafana (ปลั๊กอิน Grafana Enterprise grafana-snowflake-datasource) ดังนั้นการรับรองความถูกต้องจึงจัดการโดยการกำหนดค่า datasource ใน Grafana — ข้อมูลประจำตัวจะไม่ถูกมองเห็นโดย MCP server นี่เป็นรูปแบบเดียวกับที่ใช้กับเครื่องมือ ClickHouse

  • แสดงรายการตาราง Snowflake: ค้นพบตาราง (พร้อมฐานข้อมูล schema ชนิด จำนวนแถว และขนาด) ผ่าน INFORMATION_SCHEMA.TABLES มีตัวกรองฐานข้อมูล/schema แบบไม่บังคับ
  • อธิบายโครงสร้างตาราง: รับชื่อคอลัมน์ ชนิดข้อมูล ความสามารถเป็น null ค่าเริ่มต้น และความคิดเห็นสำหรับตาราง Snowflake
  • Query Snowflake: ดำเนินการ query SQL พร้อมการรองรับการแทนที่ macro และตัวแปร มีประโยชน์สำหรับการ query event tables ของ Snowflake (เช่น SNOWFLAKE.TELEMETRY.EVENTS) สำหรับ logs และ traces หรือตารางผู้ใช้ใด ๆ
    • Macro ที่รองรับ: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (วินาที), $__interval_ms และ ${varname} สำหรับการแทนที่ template variables

การ Query Elasticsearch/OpenSearch

หมายเหตุ: เครื่องมือ Elasticsearch/OpenSearch ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม elasticsearch ใน flag --enabled-tools ของคุณ

  • Query Elasticsearch/OpenSearch: ดำเนินการค้นหา query กับ datasource Elasticsearch หรือ OpenSearch โดยใช้ไวยากรณ์ Lucene query หรือ Elasticsearch Query DSL รองรับการกรองตามช่วงเวลาและการดึง logs metrics หรือข้อมูลที่จัดทำดัชนีใด ๆ ส่งคืนเอกสารพร้อม index, ID, ฟิลด์ต้นทาง และคะแนนความเกี่ยวข้องแบบไม่บังคับ

การ Query Quickwit

หมายเหตุ: เครื่องมือ Quickwit ถูกปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม quickwit ใน flag --enabled-tools ของคุณ

  • Query Quickwit: ดำเนินการค้นหา query กับ datasource Quickwit โดยใช้ไวยากรณ์ Lucene query หรือ Query DSL ที่เข้ากันได้กับ Elasticsearch บางส่วน รองรับการกรองตามช่วงเวลาและการดึง logs หรือเอกสารที่จัดทำดัชนีอื่น ๆ ส่งคืนเอกสารพร้อม index, ID, ฟิลด์ต้นทาง และคะแนนความเกี่ยวข้องแบบไม่บังคับ

การสังเกตการณ์ Agent

หมายเหตุ: เครื่องมือสังเกตการณ์ Agent ถูกปิดใช้งานโดยค่าเริ่มต้น และทำงานเฉพาะใน Grafana Cloud เท่านั้น หากต้องการเปิดใช้งาน ให้เพิ่ม agento11y ใน flag --enabled-tools ของคุณ

  • แสดงรายการและค้นหาการสนทนา: แสดงรายการการสนทนา LLM ล่าสุดหรือค้นหาด้วยนิพจน์ตัวกรอง (model, provider, agent, สถานะ, ประเภทข้อผิดพลาด, ผลการประเมิน และอื่น ๆ) ตามช่วงเวลา ผลการค้นหาประกอบด้วยจำนวนข้อผิดพลาด สรุปการให้คะแนน สรุปการประเมิน และ trace IDs
  • รับรายละเอียดการสนทนา: ดึงการสนทนาเดียวพร้อม generations ทั้งหมด รวมถึง prompts และ outputs
  • รับรายละเอียดและคะแนนของ generation: ดึง generation เดียวด้วย ID และคะแนนการประเมิน (ผู้ประเมิน, คีย์คะแนน, ค่า, ผ่าน/ไม่ผ่าน, คำอธิบาย)
  • อ่านแคตตาล็อก agent: แสดงรายการ agents ที่ส่ง telemetry ดึง agent เวอร์ชันเดียวแบบเต็ม (system prompt ที่สมบูรณ์ ทุก tool พร้อม JSON schema และ models ที่รัน) ดูประวัติเวอร์ชันของ agent และเปรียบเทียบผลรวมคะแนนการประเมินต่อเวอร์ชัน เวอร์ชันที่มีผลคือ sha256: hashes ที่การเปลี่ยนแปลง tool ไม่มีผลกระทบ สำหรับ agent ที่ไม่รายงานเวอร์ชันของตนเอง จะ hash system prompt ดังนั้นการแก้ไข prompt จะสร้างเวอร์ชันใหม่ แถวแคตตาล็อกและเวอร์ชันมี token_estimate ซึ่งควรตรวจสอบก่อนดึง prompt เต็มรูปแบบ
  • ตรวจสอบผู้ประเมินและเทมเพลต: อ่านผู้ประเมินที่คะแนนมาจาก เทมเพลตที่ได้มาจาก และ judge providers และ models ที่พร้อมใช้งานสำหรับผู้ประเมิน LLM-judge เมื่อเปิดใช้งานเครื่องมือเขียน ยังสามารถสร้าง fork ทดสอบ และลบผู้ประเมินได้
  • ตรวจสอบกฎการประเมินและการป้องกัน: อ่านกฎการประเมินแบบ async ที่ผูกผู้ประเมินเข้ากับ traffic การผลิต และการป้องกัน (hook rules) ที่รันแบบ inline และสามารถเตือนหรือปฏิเสธได้ เมื่อเปิดใช้งานเครื่องมือเขียน ยังสามารถสร้าง อัปเดต ดูตัวอย่าง และลบได้ การเขียนและการดำเนินการ preview_rule และ test_evaluator ที่ไม่คงอยู่ ต้องมีสิทธิ์ grafana-agento11y-app.eval:write ซึ่งได้รับจากบทบาท Agento11y Admin
  • ดูแลการสนทนาและคอลเลกชันที่บันทึกไว้: อ่านการสนทนาที่บันทึกไว้ (bookmarks ที่ให้การสนทนามี ID ชื่อ และ tags ที่เสถียร) และคอลเลกชันที่จัดกลุ่ม รวมถึงจำนวนสมาชิกของแต่ละคอลเลกชันและคอลเลกชันที่ฝังอยู่ในทุกแถวการสนทนาที่บันทึกไว้ เมื่อเปิดใช้งานเครื่องมือเขียน ยังสามารถบุ๊กมาร์กการสนทนา สร้างและแก้ไขคอลเลกชัน และเพิ่มหรือลบสมาชิกได้ การเขียนเหล่านี้ต้องมีสิทธิ์ grafana-agento11y-app.eval:write เดียวกัน
  • อ่านและแก้ไขชุดทดสอบ: แสดงรายการชุดทดสอบแบบมีเวอร์ชันที่การทดลองออฟไลน์รันด้วย อ่านชุดเดียวพร้อมประวัติเวอร์ชันเต็ม และแบ่งหน้าผ่านกรณีทดสอบของเวอร์ชัน เมื่อเปิดใช้งานเครื่องมือเขียน ยังสามารถสร้างชุด เปลี่ยนชื่อหรือติดแท็กใหม่ เปิดเวอร์ชันร่าง เผยแพร่ และเขียนหรือลบกรณีทดสอบได้ เวอร์ชันที่เผยแพร่แล้วถูกแช่แข็ง ดังนั้นการแก้ไขหมายถึงการเปิดร่างใหม่ การเขียนเหล่านี้ต้องมี grafana-agento11y-app.eval:write
  • อ่านการทดลองออฟไลน์: แสดงรายการการรันการประเมินบนชุดทดสอบและอ่านหนึ่งรายการพร้อมอัตราการผ่านหลัก ต้นทุน และยอดรวม token เจาะลึกผ่านรายงานต่อกรณีทดสอบไปยังการทดลอง คะแนนพร้อมคำอธิบายของผู้ตัดสินแต่ละคน และ metadata ของสิ่งประดิษฐ์ เมื่อเปิดใช้งานเครื่องมือเขียน ยังสามารถเปลี่ยนชื่อหรือติดแท็กใหม่การทดลองและยกเลิกการทดลองที่กำลังรันอยู่ ซึ่งต้องมี grafana-agento11y-app.eval:write การทดลองถูกสร้างโดย SDK runners ไม่ใช่โดยเครื่องมือนี้

Grafana Assistant

หมายเหตุ: เครื่องมือ Assistant ถูกปิดใช้งานตามค่าเริ่มต้น และต้องติดตั้งปลั๊กอิน Grafana Assistant (grafana-assistant-app) บนอินสแตนซ์ Grafana เป้าหมาย นอกจากนี้ยังเป็น เครื่องมือเขียน (assistant อาจเปลี่ยนแปลงสถานะของ stack) ดังนั้นจึงถูกข้ามเมื่อตั้งค่า --disable-write หากต้องการเปิดใช้งาน ให้เพิ่ม assistant ลงในแฟล็ก --enabled-tools ของคุณ

  • สอบถาม assistant: ส่งพรอมต์ภาษาธรรมชาติไปยัง Grafana Assistant และรอคำตอบข้อความแบบเต็ม assistant อาจใช้เครื่องมือ เมตริก ล็อก และบริบทอื่น ๆ ของ stack ซึ่งกว้างกว่าการเรียกใช้คิวรีจากแหล่งข้อมูลเดียว ส่งคืน contextId ที่ได้รับกลับมาในการเรียกครั้งถัดไปเพื่อดำเนินการสนทนาเดียวกันต่อ งานที่ซับซ้อนอาจใช้เวลาหลายนาที การเรียกจะบล็อกจนกว่าคำตอบจะเสร็จสิ้นหรือคำขอหมดเวลา (5 นาที)

Incidents

  • ค้นหา สร้าง และอัปเดต incidents: จัดการ incidents ใน Grafana Incident รวมถึงการค้นหา การสร้าง และการเพิ่มกิจกรรมให้กับ incidents

Sift Investigations

  • รายการ Sift investigations: ดึงรายการ Sift investigations พร้อมรองรับพารามิเตอร์ limit
  • รับ Sift investigation: ดึงรายละเอียดของ Sift investigation เฉพาะตาม UUID
  • รับ Sift analyses: ดึงการวิเคราะห์เฉพาะจาก Sift investigation
  • ค้นหารูปแบบข้อผิดพลาดในล็อก: ตรวจจับรูปแบบข้อผิดพลาดที่สูงขึ้นในล็อก Loki โดยใช้ Sift
  • ค้นหาคำขอที่ช้า: ตรวจจับคำขอที่ช้าโดยใช้ Sift (Tempo)

Alerting

  • รายการและดึงข้อมูลกฎการแจ้งเตือน: ดูกฎการแจ้งเตือนและสถานะ (firing/normal/error/ฯลฯ) ใน Grafana รองรับทั้งกฎที่จัดการโดย Grafana และกฎที่จัดการโดยแหล่งข้อมูลจากแหล่งข้อมูล Prometheus หรือ Loki
  • สร้างและอัปเดตกฎการแจ้งเตือน: สร้างกฎการแจ้งเตือนใหม่หรือแก้ไขกฎที่มีอยู่
  • ลบกฎการแจ้งเตือน: ลบกฎการแจ้งเตือนตาม UID
  • จัดการเส้นทางการแจ้งเตือน: ดูนโยบายการแจ้งเตือน จุดติดต่อ และช่วงเวลา รองรับทั้งจุดติดต่อที่จัดการโดย Grafana และ receivers จากแหล่งข้อมูล Alertmanager ภายนอก (Prometheus Alertmanager, Mimir, Cortex)

Grafana OnCall

  • รายการและจัดการตารางเวลา: ดูและจัดการตารางเวลา on-call ใน Grafana OnCall
  • รับรายละเอียดกะ: ดึงข้อมูลโดยละเอียดเกี่ยวกับกะ on-call เฉพาะ
  • รับผู้ใช้ on-call ปัจจุบัน: ดูว่าผู้ใช้ใดกำลัง on-call สำหรับตารางเวลาหนึ่ง
  • รายการทีมและผู้ใช้: ดูทีมและผู้ใช้ OnCall ทั้งหมด
  • รายการกลุ่มการแจ้งเตือน: ดูและกรองกลุ่มการแจ้งเตือนจาก Grafana OnCall ตามเกณฑ์ต่าง ๆ รวมถึงสถานะ การผสานรวม ป้ายกำกับ และช่วงเวลา
  • รับรายละเอียดกลุ่มการแจ้งเตือน: ดึงข้อมูลโดยละเอียดเกี่ยวกับกลุ่มการแจ้งเตือนเฉพาะตาม ID

Admin

หมายเหตุ: เครื่องมือ Admin ถูกปิดใช้งานตามค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้รวม admin ในแฟล็ก --enabled-tools ของคุณ

  • รายการทีม: ดูทีมที่กำหนดค่าทั้งหมดใน Grafana
  • รายการผู้ใช้: ดูผู้ใช้ทั้งหมดในองค์กรใน Grafana
  • รายการบทบาททั้งหมด: แสดงรายการบทบาท Grafana ทั้งหมด พร้อมตัวกรองเสริมสำหรับบทบาทที่สามารถมอบหมายได้
  • รับรายละเอียดบทบาท: รับรายละเอียดสำหรับบทบาท Grafana เฉพาะตาม UID
  • รายการการมอบหมายสำหรับบทบาท: แสดงรายการผู้ใช้ ทีม และบัญชีบริการทั้งหมดที่ได้รับมอบหมายให้กับบทบาท
  • รายการบทบาทสำหรับผู้ใช้: แสดงรายการบทบาททั้งหมดที่มอบหมายให้กับผู้ใช้หนึ่งรายหรือมากกว่า
  • รายการบทบาทสำหรับทีม: แสดงรายการบทบาททั้งหมดที่มอบหมายให้กับทีมหนึ่งหรือมากกว่า
  • รายการสิทธิ์สำหรับทรัพยากร: แสดงรายการสิทธิ์ทั้งหมดที่กำหนดไว้สำหรับทรัพยากรเฉพาะ (dashboard, datasource, folder, ฯลฯ)
  • อธิบายทรัพยากร Grafana: แสดงรายการสิทธิ์ที่พร้อมใช้งานและความสามารถในการมอบหมายสำหรับประเภททรัพยากร

Navigation

  • สร้าง deeplinks: สร้าง URL deeplink ที่แม่นยำสำหรับทรัพยากร Grafana แทนการพึ่งพาการเดา URL ของ LLM
    • ลิงก์ Dashboard: สร้างลิงก์โดยตรงไปยัง dashboards โดยใช้ UID (เช่น http://localhost:3000/d/dashboard-uid)
    • ลิงก์ Panel: สร้างลิงก์ไปยัง panels เฉพาะภายใน dashboards ด้วยพารามิเตอร์ viewPanel (เช่น http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • ลิงก์ Explore: สร้างลิงก์ไปยัง Grafana Explore พร้อมแหล่งข้อมูลที่กำหนดค่าไว้ล่วงหน้า (เช่น http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • รองรับช่วงเวลา: เพิ่มพารามิเตอร์ช่วงเวลาในลิงก์ (from=now-1h&to=now)
    • พารามิเตอร์ที่กำหนดเอง: รวมพารามิเตอร์คิวรีเพิ่มเติม เช่น ตัวแปร dashboard หรือช่วงเวลารีเฟรช

Annotations

  • รับ Annotations: คิวรี annotations พร้อมตัวกรอง รองรับช่วงเวลา dashboard UID แท็ก และโหมดการจับคู่
  • สร้าง Annotation: สร้าง annotation ใหม่บน dashboard หรือ panel
  • สร้าง Graphite Annotation: สร้าง annotations โดยใช้รูปแบบ Graphite (what, when, tags, data)
  • อัปเดต Annotation: แทนที่ทุกฟิลด์ของ annotation ที่มีอยู่ (การอัปเดตแบบเต็ม)
  • แก้ไข Annotation: อัปเดตเฉพาะบางฟิลด์ของ annotation (การอัปเดตบางส่วน)
  • รับแท็ก Annotation: แสดงรายการแท็ก annotation ที่พร้อมใช้งานพร้อมตัวกรองเสริม

Snapshots

  • รายการ snapshots: แสดงรายการ dashboard snapshots พร้อมตัวกรองคิวรีและ limit เสริม
  • รับ snapshot: ดึงข้อมูลเมตาของ snapshot และ payload ของ dashboard ตามคีย์ snapshot
  • สร้าง snapshot: สร้าง dashboard snapshot จาก payload ของ dashboard แบบเต็ม พร้อมตัวเลือกการหมดอายุและ snapshot ภายนอก
  • ลบ snapshot: ลบ snapshot ตามคีย์ snapshot

Rendering

  • รับภาพ panel หรือ dashboard: เรนเดอร์ panel ของ Grafana dashboard หรือ dashboard ทั้งหมดเป็นภาพ PNG ส่งคืนภาพเป็นข้อมูลที่เข้ารหัส base64 สำหรับใช้ในรายงาน การแจ้งเตือน หรือการนำเสนอ รองรับการปรับขนาด ช่วงเวลา ชุดรูปแบบ สเกล และตัวแปร dashboard นอกจากนี้ยังรองรับการเรนเดอร์ dashboards ที่ยังไม่ได้นำไปใช้จากสาขาของ provisioning repository (เช่น ตัวอย่าง PR ของ git-sync) ผ่านพารามิเตอร์เสริม provisioningPreview
    • หมายเหตุ: ต้องติดตั้งและกำหนดค่าบริการ Grafana Image Renderer

Provisioning

  • รายการ provisioning repositories: แสดงรายการ provisioning repositories ที่กำหนดค่าสำหรับอินสแตนซ์ Grafana นี้ (เช่น แหล่งที่มา git-sync) โดยส่งคืน slug ของแต่ละ repository พร้อมกับ URL แหล่งที่มา สาขา พาธ สถานะการซิงค์ และความสมบูรณ์
  • ตรวจสอบไฟล์ provisioning: ทดลองใช้ไฟล์จาก provisioning repository ที่สาขาหรือ commit ที่กำหนด โดยส่งคืนว่าไฟล์จะได้รับการยอมรับหรือไม่ การดำเนินการกับทรัพยากร (create/update) ประเภททรัพยากรเป้าหมาย และข้อผิดพลาดการตรวจสอบที่มีโครงสร้าง — พื้นผิวการยอมรับเดียวกันกับที่ PR commenter ของ Grafana ใช้

รายการเครื่องมือสามารถกำหนดค่าได้ ดังนั้นคุณจึงเลือกได้ว่าเครื่องมือใดที่ต้องการให้พร้อมใช้งานกับ MCP client สิ่งนี้มีประโยชน์หากคุณไม่ได้ใช้ฟังก์ชันบางอย่างหรือไม่ต้องการใช้พื้นที่ใน context window มากเกินไป หากต้องการปิดใช้งานหมวดหมู่เครื่องมือ ให้ใช้แฟล็ก --disable-<category> เมื่อเริ่มต้นเซิร์ฟเวอร์ ตัวอย่างเช่น หากต้องการปิดใช้งาน เครื่องมือ OnCall ให้ใช้ --disable-oncall หรือหากต้องการปิดใช้งานการสร้าง deeplink สำหรับการนำทาง ให้ใช้ --disable-navigation

RBAC Permissions

แต่ละเครื่องมือต้องมีสิทธิ์ RBAC เฉพาะเพื่อให้ทำงานได้อย่างถูกต้อง เมื่อสร้าง service account สำหรับ MCP server ตรวจสอบให้แน่ใจว่ามีสิทธิ์ที่จำเป็นตามเครื่องมือที่คุณวางแผนจะใช้ สิทธิ์ที่ระบุไว้คือการดำเนินการขั้นต่ำที่จำเป็น — คุณอาจต้องมี scopes ที่เหมาะสมด้วย (เช่น datasources:*, dashboards:*, folders:*) ขึ้นอยู่กับกรณีการใช้งานของคุณ

เคล็ดลับ: หากคุณไม่คุ้นเคยกับ RBAC ของ Grafana หรือต้องการการตั้งค่าที่รวดเร็วและง่ายกว่าแทนการกำหนดค่า scopes แบบละเอียดจำนวนมาก คุณสามารถกำหนดบทบาทในตัว เช่น Editor ให้กับ service account ได้ บทบาท Editor ให้สิทธิ์การอ่าน/เขียนในวงกว้างซึ่งจะอนุญาตให้การดำเนินการส่วนใหญ่ของ MCP server ทำงานได้ มีความละเอียดน้อยกว่า (และจึงเข้มงวดน้อยกว่า) มากกว่า scopes ที่กำหนดด้วยตนเอง ดังนั้นควรใช้เฉพาะเมื่อความสะดวกสำคัญกว่าการเข้าถึงแบบสิทธิ์น้อยที่สุดที่เข้มงวด

หมายเหตุ: เครื่องมือ Grafana Incident และ Sift ใช้บทบาท Grafana พื้นฐานแทนสิทธิ์ RBAC แบบละเอียด:

  • บทบาท Viewer: จำเป็นสำหรับการดำเนินการแบบอ่านอย่างเดียว (รายการ incidents, รับ investigations)
  • บทบาท Editor: จำเป็นสำหรับการดำเนินการแบบเขียน (สร้าง incidents, แก้ไข investigations)

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ RBAC ของ Grafana โปรดดูเอกสารอย่างเป็นทางการ

RBAC Scopes

Scopes กำหนดทรัพยากรเฉพาะที่สิทธิ์นำไปใช้กับ แต่ละการดำเนินการต้องใช้ทั้งสิทธิ์และชุด scope ที่เหมาะสม

รูปแบบ Scope ทั่วไป:

  • การเข้าถึงในวงกว้าง: ใช้ wildcards * สำหรับการเข้าถึงทั้งองค์กร

    • datasources:* - การเข้าถึงแหล่งข้อมูลทั้งหมด
    • dashboards:* - การเข้าถึง dashboards ทั้งหมด
    • folders:* - การเข้าถึง folders ทั้งหมด
    • teams:* - การเข้าถึงทีมทั้งหมด

  • การเข้าถึงแบบจำกัด: ใช้ UID หรือ ID เฉพาะเพื่อจำกัดการเข้าถึงทรัพยากรแต่ละรายการ

    • datasources:uid:prometheus-uid - การเข้าถึงเฉพาะแหล่งข้อมูล Prometheus ที่ระบุ
    • dashboards:uid:abc123 - การเข้าถึงเฉพาะ dashboard ที่มี UID abc123
    • folders:uid:xyz789 - การเข้าถึงเฉพาะ folder ที่มี UID xyz789
    • teams:id:5 - การเข้าถึงเฉพาะทีมที่มี ID 5
    • global.users:id:123 - การเข้าถึงเฉพาะผู้ใช้ที่มี ID 123

ตัวอย่าง:

  • การเข้าถึง MCP server แบบเต็ม: ให้สิทธิ์ในวงกว้างสำหรับเครื่องมือทั้งหมด

    datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

  • การเข้าถึงแหล่งข้อมูลแบบจำกัด: คิวรีเฉพาะอินสแตนซ์ Prometheus และ Loki ที่ระบุเท่านั้น

    datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

  • การเข้าถึงเฉพาะ dashboard: อ่านเฉพาะ dashboards ที่ระบุ

    dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

Tools

เครื่องมือหมวดหมู่คำอธิบายสิทธิ์ RBAC ที่จำเป็นขอบเขตที่จำเป็น
list_teamsAdminแสดงรายการทีมทั้งหมดteams:readteams:* หรือ teams:id:1
list_users_by_orgAdminแสดงรายการผู้ใช้ทั้งหมดในองค์กรusers:readglobal.users:* หรือ global.users:id:123
list_all_rolesAdminแสดงรายการบทบาท Grafana ทั้งหมดroles:readroles:*
get_role_detailsAdminรับรายละเอียดสำหรับบทบาท Grafanaroles:readroles:uid:editor
get_role_assignmentsAdminแสดงรายการการกำหนดสำหรับบทบาทหนึ่งroles:readroles:uid:editor
list_user_rolesAdminแสดงรายการบทบาทสำหรับผู้ใช้roles:readglobal.users:id:123
list_team_rolesAdminแสดงรายการบทบาทสำหรับทีมroles:readteams:id:7
get_resource_permissionsAdminแสดงรายการสิทธิ์สำหรับทรัพยากรหนึ่งpermissions:readdashboards:uid:abcd1234
get_resource_descriptionAdminอธิบายประเภททรัพยากร Grafanapermissions:readdashboards:*
search_dashboardsSearchค้นหาแดชบอร์ดdashboards:readdashboards:* หรือ dashboards:uid:abc123
get_dashboard_by_uidDashboardรับแดชบอร์ดตาม uiddashboards:readdashboards:uid:abc123
update_dashboardDashboardอัปเดตหรือสร้างแดชบอร์ดใหม่dashboards:create, dashboards:writedashboards:*, folders:* หรือ folders:uid:xyz789
get_dashboard_panel_queriesDashboardรับชื่อแผง การสอบถาม UID ของแหล่งข้อมูล และประเภทจากแดชบอร์ดdashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*ดำเนินการสอบถามแผงแดชบอร์ดหนึ่งหรือหลายรายการdashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyDashboardแยกส่วนเฉพาะของแดชบอร์ดโดยใช้นิพจน์ JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryDashboardรับสรุปแบบกระชับของแดชบอร์ดโดยไม่ต้องใช้ JSON ทั้งหมดdashboards:readdashboards:uid:abc123
list_datasourcesDatasourcesแสดงรายการแหล่งข้อมูลdatasources:readdatasources:*
get_datasourceDatasourcesรับแหล่งข้อมูลโดย UID หรือชื่อdatasources:readdatasources:uid:prometheus-uid
get_query_examplesExamples*รับตัวอย่างการสอบถามสำหรับประเภทแหล่งข้อมูลdatasources:readdatasources:*
query_prometheusPrometheusดำเนินการสอบถามกับแหล่งข้อมูล Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusแสดงรายการเมตาดาต้าของเมตริกdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusแสดงรายการชื่อเมตริกที่พร้อมใช้งานdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusแสดงรายการชื่อป้ายกำกับที่ตรงกับตัวเลือกdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusแสดงรายการค่าสำหรับป้ายกำกับเฉพาะdatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusคำนวณค่าเปอร์เซ็นไทล์ของฮิสโตแกรมdatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidentแสดงรายการเหตุการณ์ใน Grafana Incidentสิทธิ์ ViewerN/A
create_incidentIncidentสร้างเหตุการณ์ใน Grafana Incidentสิทธิ์ EditorN/A
add_activity_to_incidentIncidentเพิ่มรายการกิจกรรมในเหตุการณ์ใน Grafana Incidentสิทธิ์ EditorN/A
get_incidentIncidentรับเหตุการณ์เดี่ยวตาม IDสิทธิ์ ViewerN/A
query_loki_logsLokiสอบถามและดึงข้อมูลล็อกโดยใช้ LogQL (ทั้งการสอบถามแบบล็อกหรือเมตริก)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiแสดงรายการชื่อป้ายกำกับที่พร้อมใช้งานทั้งหมดในล็อกdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiแสดงรายการค่าสำหรับป้ายกำกับล็อกเฉพาะdatasources:querydatasources:uid:loki-uid
query_loki_statsLokiรับสถิติเกี่ยวกับสตรีมล็อกdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiสอบถามรูปแบบล็อกที่ตรวจพบเพื่อระบุโครงสร้างทั่วไปdatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiตรวจสอบกลยุทธ์ป้ายกำกับ Loki (แบบสดหรือแบบคงที่) และวินิจฉัยประสิทธิภาพการสอบถามได้datasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configConfigสร้างส่วนย่อยของ Alloy loki.process ที่บังคับใช้ป้ายกำกับที่อนุมัติN/AN/A
query_influxdbInfluxDBสอบถาม InfluxDB โดยใช้ InfluxQL (v1) หรือ Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*แสดงรายการตารางในฐานข้อมูล ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*รับสคีมาตารางพร้อมประเภทคอลัมน์datasources:querydatasources:uid:*
query_clickhouseClickHouse*ดำเนินการสอบถาม SQL พร้อมการแทนที่มาโครdatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*แสดงรายการ namespace ของ AWS CloudWatch ที่พร้อมใช้งานdatasources:querydatasources:uid:*
list_cloudwatch_metricsCloudWatch*แสดงรายการเมตริกในเนมสเปซdatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*แสดงไดเมนชันสำหรับเมตริกdatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*ดำเนินการคิวรีเมตริกของ CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*แสดงรายการแคตตาล็อกข้อมูล Athena ที่มีอยู่datasources:querydatasources:uid:*
list_athena_databasesAthena*แสดงรายการฐานข้อมูลในแคตตาล็อก Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*แสดงรายการตารางในฐานข้อมูล Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*รับชื่อคอลัมน์สำหรับตาราง Athenadatasources:querydatasources:uid:*
query_athenaAthena*ดำเนินการคิวรี SQL พร้อมการแทนที่แมโครdatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*คิวรี Elasticsearch หรือ OpenSearch โดยใช้ไวยากรณ์ Lucene หรือ Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*คิวรี Quickwit โดยใช้ไวยากรณ์ Lucene หรือ Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*แสดงรายการตารางในฐานข้อมูล/สคีมา Snowflake ผ่าน INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*รับสคีมาของตาราง (ชนิดคอลัมน์, การยอมรับค่า null, ค่าเริ่มต้น, ความคิดเห็น)datasources:querydatasources:uid:*
query_snowflakeSnowflake*ดำเนินการคิวรี SQL พร้อมการแทนที่แมโคร/ตัวแปรdatasources:querydatasources:uid:*
alerting_manage_rulesAlertingจัดการกฎการแจ้งเตือน (แสดงรายการ, รับ, เวอร์ชัน, สร้าง, อัปเดต, ลบ)alert.rules:read + alert.rules:write สำหรับการเปลี่ยนแปลงfolders:* หรือ folders:uid:alerts-folder
alerting_manage_routingAlertingจัดการนโยบายการแจ้งเตือน, จุดติดต่อ, และช่วงเวลาalert.notifications:readขอบเขตทั่วโลก
list_oncall_schedulesOnCallแสดงรายการตารางเวลาจาก Grafana OnCallgrafana-oncall-app.schedules:readขอบเขตเฉพาะปลั๊กอิน
get_oncall_shiftOnCallรับรายละเอียดสำหรับกะ OnCall เฉพาะgrafana-oncall-app.schedules:readขอบเขตเฉพาะปลั๊กอิน
get_current_oncall_usersOnCallรับผู้ใช้ที่อยู่เวรปัจจุบันสำหรับตารางเวลาเฉพาะgrafana-oncall-app.schedules:readขอบเขตเฉพาะปลั๊กอิน
list_oncall_teamsOnCallแสดงรายการทีมจาก Grafana OnCallgrafana-oncall-app.user-settings:readขอบเขตเฉพาะปลั๊กอิน
list_oncall_usersOnCallแสดงรายการผู้ใช้จาก Grafana OnCallgrafana-oncall-app.user-settings:readขอบเขตเฉพาะปลั๊กอิน
list_alert_groupsOnCallแสดงรายการกลุ่มการแจ้งเตือนจาก Grafana OnCall พร้อมตัวเลือกการกรองgrafana-oncall-app.alert-groups:readขอบเขตเฉพาะปลั๊กอิน
get_alert_groupOnCallรับกลุ่มการแจ้งเตือนเฉพาะจาก Grafana OnCall ตาม IDgrafana-oncall-app.alert-groups:readขอบเขตเฉพาะปลั๊กอิน
get_sift_investigationSiftดึงข้อมูลการสอบสวน Sift ที่มีอยู่โดย UUIDบทบาทผู้ชมN/A
get_sift_analysisSiftดึงข้อมูลการวิเคราะห์เฉพาะจากการสอบสวน Siftบทบาทผู้ชมN/A
list_sift_investigationsSiftดึงข้อมูลรายการการสอบสวน Sift พร้อมขีดจำกัดที่ไม่บังคับบทบาทผู้ชมN/A
find_error_pattern_logsSiftค้นหารูปแบบข้อผิดพลาดที่สูงขึ้นในบันทึก LokiบทบาทบรรณาธิการN/A
find_slow_requestsSiftค้นหาคำขอที่ช้าจากแหล่งข้อมูล tempo ที่เกี่ยวข้องบทบาทบรรณาธิการN/A
list_pyroscope_label_namesPyroscopeแสดงรายการชื่อป้ายกำกับที่ตรงกับตัวเลือกdatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeแสดงรายการค่าป้ายกำกับที่ตรงกับตัวเลือกสำหรับชื่อป้ายกำกับdatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeแสดงรายการชนิดโปรไฟล์ที่มีอยู่datasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeคิวรีโปรไฟล์, เมตริก หรือทั้งสองจาก Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsรับสรุปการยืนยันสำหรับเอนทิตีที่กำหนดสิทธิ์เฉพาะปลั๊กอินขอบเขตเฉพาะปลั๊กอิน
agento11y_manage_conversationsAgent Observability*แสดงรายการ, ค้นหา, และดึงข้อมูลการสนทนา LLM จาก Grafana Agent Observabilitygrafana-agento11y-app.conversations:readN/A
agento11y_manage_generationsAgent Observability*ดึงข้อมูลรายละเอียดการสร้าง LLM และคะแนนการประเมินจาก Grafana Agent Observabilitygrafana-agento11y-app.data:readN/A
agento11y_manage_agentsAgent Observability*อ่านแคตตาล็อกเอเจนต์: แสดงรายการเอเจนต์, รับเวอร์ชันเอเจนต์หนึ่งแบบเต็ม, แสดงรายการประวัติเวอร์ชัน, และคะแนนรวมต่อเวอร์ชันgrafana-agento11y-app.data:readN/A
agento11y_manage_evaluatorsAgent Observability*จัดการตัวประเมิน, เทมเพลตตัวประเมิน, และแคตตาล็อกผู้ตัดสิน (แสดงรายการ, รับ, upsert, fork, ทดสอบ, ลบ)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write สำหรับการเปลี่ยนแปลงและการทดสอบN/A
agento11y_manage_eval_rulesAgent Observability*จัดการกฎการประเมินและการ์ด (แสดงรายการ, รับ, สร้าง, อัปเดต, ดูตัวอย่าง, ลบ)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write สำหรับการเปลี่ยนแปลงและการดูตัวอย่างN/A
agento11y_manage_eval_collectionsAgent Observability*จัดการการสนทนาที่บันทึกไว้และคอลเล็กชันที่จัดกลุ่ม (แสดงรายการ, รับ, บันทึก, สร้าง, อัปเดต, ลบ, เพิ่มและลบสมาชิก)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write สำหรับการเปลี่ยนแปลงN/A
agento11y_manage_experimentsAgent Observability*อ่านการทดลองออฟไลน์, การทดลองย่อย, คะแนน, ข้อมูลเมตาของอาร์ติแฟกต์, และ facet การกรอง; อัปเดตและยกเลิกการทดลองgrafana-agento11y-app.data:read + grafana-agento11y-app.eval:write สำหรับการเปลี่ยนแปลงN/A
agento11y_manage_test_suitesAgent Observability*จัดการชุดทดสอบที่การทดลองออฟไลน์รันกับ, เวอร์ชัน, และกรณีทดสอบ (แสดงรายการ, รับ, สร้าง, อัปเดต, ร่าง, เผยแพร่, upsert, ลบ)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write สำหรับการเปลี่ยนแปลงN/A
ask_assistantAssistant*ส่งพรอมต์ไปยัง Grafana Assistant และส่งคืนข้อความตอบกลับแบบเต็ม (หลายเทิร์นผ่าน contextId)สิทธิ์เฉพาะปลั๊กอินขอบเขตเฉพาะปลั๊กอิน
generate_deeplinkNavigationสร้าง URL ลิงก์ลึกที่แม่นยำสำหรับทรัพยากร Grafanaไม่มี (การสร้าง URL แบบอ่านอย่างเดียว)N/A
get_annotationsAnnotationsดึงข้อมูลคำอธิบายประกอบพร้อมตัวกรองannotations:readannotations:* หรือ annotations:id:123
create_annotationคำอธิบายประกอบสร้างคำอธิบายประกอบใหม่ (รูปแบบมาตรฐานหรือ Graphite)annotations:writeannotations:*
update_annotationคำอธิบายประกอบอัปเดตฟิลด์เฉพาะของคำอธิบายประกอบ (อัปเดตบางส่วน)annotations:writeannotations:*
get_annotation_tagsคำอธิบายประกอบแสดงรายการแท็กคำอธิบายประกอบพร้อมการกรองแบบไม่บังคับannotations:readannotations:*
list_snapshotsสแนปช็อตแสดงรายการสแนปช็อตแดชบอร์ดพร้อมการกรองด้วยคิวรีและขีดจำกัดแบบไม่บังคับdashboards:readdashboards:* หรือ dashboards:uid:abc123
get_snapshotสแนปช็อตรับข้อมูลเมตาของสแนปช็อตและเพย์โหลดแดชบอร์ดด้วยคีย์สแนปช็อตdashboards:readdashboards:* หรือ dashboards:uid:abc123
create_snapshotสแนปช็อตสร้างสแนปช็อตแดชบอร์ดจากเพย์โหลดแดชบอร์ดแบบเต็มรูปแบบdashboards:writedashboards:* หรือ dashboards:uid:abc123
delete_snapshotสแนปช็อตลบสแนปช็อตแดชบอร์ดด้วยคีย์สแนปช็อตdashboards:writedashboards:* หรือ dashboards:uid:abc123
get_panel_imageการเรนเดอร์เรนเดอร์แดชบอร์ดหรือแผงที่จัดเก็บไว้ — หรือตัวอย่างการจัดเตรียมจากสาขาที่เก็บ — เป็นภาพ PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesการจัดเตรียมแสดงรายการที่เก็บการจัดเตรียม (เช่น แหล่งที่มา git-sync) พร้อม URL ต้นทาง สาขา สถานะการซิงค์ และสุขภาพprovisioning.repositories:readN/A
validate_provisioning_fileการจัดเตรียมใช้แบบทดลองกับไฟล์จากที่เก็บการจัดเตรียมและรายงานข้อผิดพลาดการตรวจสอบการยอมรับprovisioning.repositories:readN/A
* ปิดใช้งานตามค่าเริ่มต้น เพิ่มหมวดหมู่ใน --enabled-tools เพื่อเปิดใช้งาน

ข้อมูลอ้างอิงแฟล็ก CLI

ไบนารี mcp-grafana รองรับแฟล็กบรรทัดคำสั่งต่าง ๆ สำหรับการกำหนดค่า:

ตัวเลือกการขนส่ง:

  • -t, --transport: ประเภทการขนส่ง (stdio, sse, หรือ streamable-http) - ค่าเริ่มต้น: stdio
  • --address: โฮสต์และพอร์ตสำหรับเซิร์ฟเวอร์ SSE/streamable-http - ค่าเริ่มต้น: localhost:8000
  • --base-path: เส้นทางฐานสำหรับเซิร์ฟเวอร์ SSE/streamable-http
  • --endpoint-path: เส้นทางปลายทางสำหรับเซิร์ฟเวอร์ streamable-http - ค่าเริ่มต้น: /mcp
  • --server-name: ชื่อเซิร์ฟเวอร์ที่ใช้ในการเชื่อมต่อ MCP และ OTel service.name - ค่าเริ่มต้น: mcp-grafana. ใช้แทนที่ตัวแปรสภาพแวดล้อม GRAFANA_MCP_SERVER_NAME

ความปลอดภัยการขนส่ง HTTP (SSE / streamable-http เท่านั้น):

การตรวจสอบ Host/Origin ถูกบังคับใช้กับ ทุก เส้นทางบนตัวฟัง — /sse, /mcp, /healthz, และ /metrics — ดังนั้นเบราว์เซอร์ที่ทำ DNS-rebinding ไม่สามารถเข้าถึงเส้นทางใด ๆ ได้ การขนส่งแบบ Stdio ไม่ได้รับผลกระทบ

  • --allowed-hosts: รายการอนุญาตค่าของส่วนหัว Host คั่นด้วยเครื่องหมายจุลภาค ค่าเริ่มต้นคือรูปแบบ loopback ของ --address (เช่น localhost:8000,127.0.0.1:8000,[::1]:8000) ค่าที่แยกแล้วว่างเปล่า (ไม่ได้ตั้งค่า, ,, ,, ฯลฯ) จะย้อนกลับเป็นค่าเริ่มต้นเพื่อให้การพิมพ์ผิดไม่สามารถปิดการตรวจสอบอย่างเงียบ ๆ คำขอที่มีส่วนหัว Host ภายนอกรายการอนุญาตจะถูกปฏิเสธด้วย 403 ส่ง * เพื่อปิดการตรวจสอบ — ปลอดภัยเฉพาะเมื่อทำงานหลังพร็อกซีย้อนกลับที่เชื่อถือได้ซึ่งเขียน Host ใหม่ หรือในเครือข่ายที่แยกจากกัน การตรวจสอบ K8s httpGet และการดึงข้อมูล /metrics ภายนอกจะต้องระบุ hostname อย่างชัดเจนในรายการนี้, *, หรือใช้ tcpSocket probe / พอร์ตเมตริกแยกต่างหาก (--metrics-address)
  • --allowed-origins: รายการอนุญาตค่าของส่วนหัว Origin คั่นด้วยเครื่องหมายจุลภาค ค่าเริ่มต้นว่างเปล่า — คำขอใด ๆ ที่มีส่วนหัว Origin จะถูกปฏิเสธ (เบราว์เซอร์มักจะส่งส่วนหัวนี้สำหรับคำขอข้ามต้นทาง และไม่มีเบราว์เซอร์ใดควรเรียกเซิร์ฟเวอร์นี้โดยตรง) ตั้งค่ารายการที่ชัดเจนเพื่ออนุญาตไคลเอ็นต์ที่ใช้เบราว์เซอร์ หรือ * เพื่อปิดการตรวจสอบ

การตรวจสอบสิทธิ์ผู้เรียก (SSE / streamable-http เท่านั้น):

ตัวเลือกให้ไคลเอ็นต์ MCP ต้องตรวจสอบสิทธิ์ กับเซิร์ฟเวอร์ ซึ่งแยกจากการรับรองที่เซิร์ฟเวอร์ใช้เพื่อเข้าถึง Grafana Stdio ไม่ได้รับผลกระทบ

  • --server-auth-token: โทเค็น Bearer ที่ผู้เรียกต้องส่งเป็น Authorization: Bearer <token> ย้อนกลับไปยังตัวแปรสภาพแวดล้อม MCP_GRAFANA_SERVER_TOKEN เมื่อตั้งค่า คำขอที่ไม่มีโทเค็นที่ถูกต้องจะถูกปฏิเสธด้วย 401 ก่อนที่เครื่องมือใดจะทำงาน ควรใช้ตัวแปรสภาพแวดล้อมเพื่อไม่ให้ความลับปรากฏในอาร์กิวเมนต์ของกระบวนการ

การตรวจสอบสิทธิ์ผู้เรียกจะถูกบังคับใช้เฉพาะเมื่อตั้งค่า --server-auth-token เมื่อไม่ได้ตั้งค่าและเซิร์ฟเวอร์ผูกกับที่อยู่ที่ไม่ใช่ loopback เซิร์ฟเวอร์จะ เริ่มต้นแต่บันทึกข้อผิดพลาดด้านความปลอดภัย — แสดงที่ระดับล็อก error เพื่อไม่ให้ถูกซ่อนโดย --log-level (loopback และ stdio ไม่ได้รับผลกระทบ); เวอร์ชันหลักในอนาคตจะทำให้เป็นข้อผิดพลาดตอนเริ่มต้น ใช้ TLS (หรือการสิ้นสุด TLS) ทุกครั้งที่เปิดใช้การตรวจสอบสิทธิ์ผู้เรียกบนที่อยู่ที่ไม่ใช่ loopback เมื่อเปิดใช้การตรวจสอบสิทธิ์ผู้เรียก ส่วนหัว Authorization ที่ตรวจสอบแล้วจะถูกตัดออกก่อนที่คำขอจะถึง Grafana; การรวม --server-auth-token กับ GRAFANA_FORWARD_HEADERS=Authorization จะถูกปฏิเสธเมื่อเริ่มต้น

การดีบักและการบันทึก:

  • --debug: เปิดโหมดดีบักสำหรับการบันทึกรายละเอียดคำขอ/การตอบสนอง HTTP
  • --log-level: ระดับล็อก (debug, info, warn, error) - ค่าเริ่มต้น: info

ตัวเลือกไคลเอ็นต์ Grafana:

  • --grafana-timeout: จำกัดเวลาสำหรับคำขอที่ไคลเอ็นต์ Grafana ส่ง รับสตริงระยะเวลา Go (เช่น 10s, 500ms) - ค่าเริ่มต้น: 10s
  • --include-args-in-spans: รวมอาร์กิวเมนต์การเรียกเครื่องมือใน OpenTelemetry spans เปิดใช้เฉพาะในสภาพแวดล้อมที่ไม่ใช่ production หรือเมื่อทราบว่าอาร์กิวเมนต์ไม่มี PII - ค่าเริ่มต้น: false

การสังเกตได้:

  • --metrics: เปิดใช้จุดสิ้นสุดเมตริก Prometheus ที่ /metrics
  • --metrics-address: ที่อยู่แยกสำหรับเซิร์ฟเวอร์เมตริก (เช่น :9090) ถ้าว่าง เมตริกจะถูกให้บริการบนเซิร์ฟเวอร์หลัก
  • --slow-request-threshold: บันทึกเหตุการณ์เมื่อคำขอ MCP ใด ๆ (การเรียกเครื่องมือ, การแสดงรายการ, การอ่านทรัพยากร ฯลฯ) ใช้เวลานานกว่าระยะเวลานี้ รับสตริงระยะเวลา Go (เช่น 500ms, 5s) ค่าเริ่มต้น 0 ปิดการบันทึกคำขอช้า ดูส่วน การบันทึกคำขอช้า
  • --slow-request-log-level: ระดับล็อกสำหรับเหตุการณ์คำขอช้า (info หรือ warn) - ค่าเริ่มต้น: warn

การจัดการเซสชัน:

  • --session-idle-timeout-minutes: ระยะหมดเวลาเซสชันที่ไม่ได้ใช้งานในหน่วยนาที เซสชันที่ไม่มีการเคลื่อนไหวในช่วงเวลานี้จะถูกรวบรวมโดยอัตโนมัติ - ค่าเริ่มต้น: 30 ตั้งเป็น 0 เพื่อปิดการรวบรวมเซสชัน ใช้ได้เฉพาะกับ transport SSE และ streamable-http

การกำหนดค่าเครื่องมือ:

  • --enabled-tools: รายการหมวดหมู่ที่เปิดใช้งานคั่นด้วยเครื่องหมายจุลภาค - ค่าเริ่มต้น: ทุกหมวดหมู่ยกเว้น admin, agento11y, assistant, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery, และ snowflake เพื่อเปิดใช้งานหมวดหมู่ที่ปิด ให้เพิ่มลงในรายการ (เช่น "search,datasource,...,snowflake")
  • --max-loki-log-limit: จำนวนสูงสุดของบรรทัดล็อกที่ส่งกลับต่อการเรียก query_loki_logs - ค่าเริ่มต้น: 100 หมายเหตุ: ตั้งค่าให้ต่ำกว่า max_entries_limit_per_query ฝั่งเซิร์ฟเวอร์ของ Loki อย่างน้อย 1 เพื่อให้ตรวจจับการตัดทอนได้ (เครื่องมือร้องขอ limit+1 ภายในเพื่อตรวจสอบว่ามีข้อมูลมากกว่านั้นหรือไม่)
  • --disable-search: ปิดเครื่องมือค้นหา
  • --disable-datasource: ปิดเครื่องมือ datasource
  • --disable-incident: ปิดเครื่องมือ incident
  • --disable-prometheus: ปิดเครื่องมือ prometheus
  • --disable-write: ปิดเครื่องมือเขียน (การสร้าง/อัปเดต)
  • --disable-loki: ปิดเครื่องมือ loki
  • --disable-elasticsearch: ปิดเครื่องมือ elasticsearch และ opensearch
  • --disable-quickwit: ปิดเครื่องมือ quickwit
  • --disable-influxdb: ปิดเครื่องมือ InfluxDB
  • --disable-alerting: ปิดเครื่องมือ alerting
  • --disable-dashboard: ปิดเครื่องมือ dashboard
  • --disable-oncall: ปิดเครื่องมือ oncall
  • --disable-asserts: ปิดเครื่องมือ asserts
  • --disable-sift: ปิดเครื่องมือ sift
  • --disable-admin: ปิดเครื่องมือ admin
  • --disable-pyroscope: ปิดเครื่องมือ pyroscope
  • --disable-navigation: ปิดเครื่องมือ navigation
  • --disable-rendering: ปิดเครื่องมือ rendering (การส่งออกภาพแผง/dashboard)
  • --disable-snapshot: ปิดเครื่องมือ snapshot
  • --disable-cloudwatch: ปิดเครื่องมือ CloudWatch
  • --disable-examples: ปิดเครื่องมือ query examples
  • --disable-clickhouse: ปิดเครื่องมือ ClickHouse
  • --disable-snowflake: ปิดเครื่องมือ Snowflake
  • --disable-runpanelquery: ปิดเครื่องมือ run panel query
  • --disable-graphite: ปิดเครื่องมือ Graphite
  • --disable-athena: ปิดเครื่องมือ Athena
  • --disable-provisioning: ปิดเครื่องมือ provisioning
  • --disable-agento11y: ปิดเครื่องมือ Agent Observability
  • --disable-assistant: ปิดเครื่องมือ Grafana Assistant

โหมดอ่านอย่างเดียว

แฟล็ก --disable-write เป็นวิธีให้เซิร์ฟเวอร์ MCP ทำงานในโหมดอ่านอย่างเดียว ป้องกันการดำเนินการเขียนใด ๆ กับอินสแตนซ์ Grafana ของคุณ มีประโยชน์สำหรับสถานการณ์ที่คุณต้องการให้การเข้าถึงแบบอ่านอย่างเดียวที่ปลอดภัย เช่น:

  • การใช้บัญชีบริการที่มีสิทธิ์อ่านอย่างเดียวจำกัด
  • ให้ AI assistants เข้าถึงข้อมูลการสังเกตได้โดยไม่มีความสามารถในการแก้ไข
  • การรันในสภาพแวดล้อม production ที่ควรจำกัดการเขียน
  • สถานการณ์การทดสอบและการพัฒนาที่คุณต้องการป้องกันการแก้ไขโดยไม่ตั้งใจ

เมื่อเปิดใช้ --disable-write การดำเนินการเขียนต่อไปนี้จะถูกปิดใช้งาน:

เครื่องมือ Dashboard:

  • update_dashboard

เครื่องมือโฟลเดอร์:

  • create_folder

เครื่องมือ Incident:

  • create_incident
  • add_activity_to_incident

เครื่องมือ Alerting:

  • alerting_manage_rules (การสร้าง, อัปเดต, ลบ)

เครื่องมือคำอธิบายประกอบ:

  • create_annotation
  • update_annotation

เครื่องมือ Sift:

  • find_error_pattern_logs (สร้างการสอบสวน)
  • find_slow_requests (สร้างการสอบสวน)

เครื่องมือ Snapshot:

  • create_snapshot
  • delete_snapshot

เครื่องมือ Agent Observability:

  • agento11y_manage_evaluators (การ upsert, ลบ, fork, การทดสอบประเมินผล)
  • agento11y_manage_eval_rules (การสร้าง, อัปเดต, ลบ, พรีวิว rule และ guard)
  • agento11y_manage_eval_collections (บันทึกและลบบทสนทนาที่บันทึก; สร้าง, อัปเดต, ลบคอลเลกชัน; เพิ่มและลบสมาชิกคอลเลกชัน)
  • agento11y_manage_experiments (การอัปเดตและยกเลิกการทดลอง)
  • agento11y_manage_test_suites (สร้างและอัปเดตชุดทดสอบ; สร้างและเผยแพร่เวอร์ชัน; upsert และลบกรณีทดสอบ)

การดำเนินการอ่านทั้งหมดยังคงใช้งานได้ ช่วยให้คุณสอบถาม dashboards, รันคำสั่ง PromQL/LogQL, แสดงรายการทรัพยากร, และดึงข้อมูล

การกำหนดค่า TLS ของไคลเอ็นต์ (สำหรับการเชื่อมต่อ Grafana):

  • --tls-cert-file: เส้นทางไปยังไฟล์ใบรับรอง TLS สำหรับการตรวจสอบสิทธิ์ไคลเอ็นต์
  • --tls-key-file: เส้นทางไปยังไฟล์คีย์ส่วนตัว TLS สำหรับการตรวจสอบสิทธิ์ไคลเอ็นต์
  • --tls-ca-file: เส้นทางไปยังไฟล์ใบรับรอง CA TLS สำหรับการตรวจสอบเซิร์ฟเวอร์
  • --tls-skip-verify: ข้ามการตรวจสอบใบรับรอง TLS (ไม่ปลอดภัย)

การกำหนดค่า TLS ของเซิร์ฟเวอร์ (เฉพาะ transport streamable-http):

  • --server.tls-cert-file: เส้นทางไปยังไฟล์ใบรับรอง TLS สำหรับ HTTPS ของเซิร์ฟเวอร์
  • --server.tls-key-file: เส้นทางไปยังไฟล์คีย์ส่วนตัว TLS สำหรับ HTTPS ของเซิร์ฟเวอร์

การใช้งาน

เซิร์ฟเวอร์ MCP นี้ทำงานร่วมกับทั้ง Grafana ในเครื่องและ Grafana Cloud สำหรับ Grafana Cloud ให้ใช้ URL ของอินสแตนซ์ของคุณ (เช่น https://myinstance.grafana.net) แทน http://localhost:3000 ในตัวอย่างการกำหนดค่าด้านล่าง

  1. หากใช้การตรวจสอบสิทธิ์ด้วยโทเค็นบัญชีบริการ ให้สร้างบัญชีบริการใน Grafana พร้อมสิทธิ์เพียงพอที่จะใช้เครื่องมือที่คุณต้องการใช้ สร้างโทเค็นบัญชีบริการและคัดลอกไปยังคลิปบอร์ดเพื่อใช้ในไฟล์กำหนดค่า ปฏิบัติตาม เอกสารบัญชีบริการ Grafana สำหรับรายละเอียดเกี่ยวกับการสร้างโทเค็นบัญชีบริการ เคล็ดลับ: หากคุณไม่สะดวกใจในการกำหนดค่า RBAC แบบละเอียด ตัวเลือกที่ง่ายกว่า (แต่จำกัดน้อยกว่า) คือกำหนดบทบาท Editor ในตัวให้กับบัญชีบริการ ซึ่งให้สิทธิ์อ่าน/เขียนกว้าง ๆ ครอบคลุมการดำเนินการส่วนใหญ่ของเซิร์ฟเวอร์ MCP — ใช้เมื่อความสะดวกสำคัญกว่าข้อกำหนดสิทธิ์น้อยที่สุดที่เข้มงวด

    หมายเหตุ: ตัวแปรสภาพแวดล้อม GRAFANA_API_KEY เลิกใช้แล้วและจะถูกลบในเวอร์ชันอนาคต กรุณาย้ายไปใช้ GRAFANA_SERVICE_ACCOUNT_TOKEN แทน ชื่อตัวแปรเก่าจะยังทำงานเพื่อความเข้ากันได้ย้อนหลัง แต่จะแสดงคำเตือนการเลิกใช้

อ่านโทเค็นบัญชีบริการจากไฟล์

แทนที่จะส่งโทเค็นแบบอินไลน์ผ่าน GRAFANA_SERVICE_ACCOUNT_TOKEN คุณสามารถชี้ GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE ไปยังเส้นทางไฟล์ที่มีโทเค็น ไฟล์จะถูกอ่านใหม่ทุกคำขอ ดังนั้นโทเค็นที่หมุนเวียนจะถูกนำไปใช้โดยอัตโนมัติโดยไม่ต้องรีสตาร์ทเซิร์ฟเวอร์

มีประโยชน์อย่างยิ่งใน Kubernetes ซึ่ง Secret ที่เมานต์เป็นวอลุ่มจะถูกอัปเดตในตำแหน่งเมื่อ Secret ต้นทางเปลี่ยนแปลง (โดยปกติภายใน ~1 นาที) เมื่อรวมกับแคชไคลเอ็นต์ต่อคำขอ — ซึ่งใช้ค่าโทเค็นเป็นคีย์ — โทเค็นที่หมุนเวียนจะสร้างไคลเอ็นต์ใหม่โดยโปร่งใสโดยไม่ต้องรีสตาร์ทพอดและไม่มีเวลาหยุดทำงาน:

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

ช่องว่างโดยรอบ (รวมถึงบรรทัดใหม่ท้าย) จะถูกตัดออกจากเนื้อหาไฟล์ หากตั้งทั้ง GRAFANA_SERVICE_ACCOUNT_TOKEN และ GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE โทเค็นอินไลน์จะมีความสำคัญกว่า

การรองรับหลายองค์กร

คุณสามารถระบุองค์กรที่ต้องการโต้ตอบได้โดยใช้:

  • ตัวแปรสภาพแวดล้อม: ตั้ง GRAFANA_ORG_ID เป็น ID องค์กรตัวเลข
  • ส่วนหัว HTTP: ตั้ง X-Grafana-Org-Id เมื่อใช้ transport SSE หรือ streamable HTTP (ส่วนหัวมีความสำคัญกว่าตัวแปรสภาพแวดล้อม - หมายความว่าคุณสามารถตั้งค่า org เริ่มต้นได้)

เมื่อระบุ ID องค์กร เซิร์ฟเวอร์ MCP จะตั้งค่าส่วนหัว X-Grafana-Org-Id ในทุกคำขอไปยัง Grafana เพื่อให้แน่ใจว่าการดำเนินการเกิดขึ้นในบริบทองค์กรที่ระบุ

ตัวอย่างพร้อม ID องค์กร:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

ส่วนหัว HTTP ที่กำหนดเอง

คุณสามารถเพิ่มส่วนหัว HTTP ตามอำเภอใจให้กับคำขอ Grafana API ทั้งหมดได้โดยใช้ตัวแปรสภาพแวดล้อม GRAFANA_EXTRA_HEADERS ค่าควรเป็นวัตถุ JSON ที่จับคู่ชื่อส่วนหัวกับค่า

ตัวอย่างพร้อมส่วนหัวที่กำหนดเอง:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

การส่งต่อส่วนหัวจากไคลเอนต์ (เฉพาะ SSE/Streamable-HTTP)

เมื่อเซิร์ฟเวอร์ MCP ทำงานอยู่เบื้องหลังเกตเวย์หรือพร็อกซีย้อนกลับที่จัดการ SSO (เช่น AWS ALB พร้อม OIDC) คุกกี้เซสชันของผู้ใช้แต่ละคนจะต้องไปถึง Grafana เพื่อให้สามารถเชื่อมโยงคำขอเข้ากับผู้ใช้ที่รับรองความถูกต้องได้ ตัวแปรสภาพแวดล้อม GRAFANA_FORWARD_HEADERS เปิดใช้งานสิ่งนี้โดยระบุรายการชื่อส่วนหัวที่อนุญาตแบบคั่นด้วยเครื่องหมายจุลภาคเพื่อคัดลอกจากคำขอ HTTP ที่เข้ามา ไปยังคำขอ Grafana API ที่ส่งออกทุกรายการ

สิ่งนี้ใช้ได้เฉพาะเมื่อใช้ SSE (-t sse) หรือ streamable-http (-t streamable-http) เท่านั้น ซึ่งไม่มีผลในโหมด stdio

ตัวอย่าง: ส่งต่อคุกกี้เซสชัน

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

คุณสามารถส่งต่อส่วนหัวหลายรายการได้โดยคั่นด้วยเครื่องหมายจุลภาค:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

ส่วนหัวที่ส่งต่อจะถูกรวมเข้ากับส่วนหัวที่กำหนดใน GRAFANA_EXTRA_HEADERS หากชื่อส่วนหัวปรากฏในทั้งสองค่า ค่าจากคำขอที่เข้ามาจะมีความสำคัญสำหรับคำขอนั้น

  1. คุณมีหลายตัวเลือกในการติดตั้ง mcp-grafana:

    • uvx (แนะนำ): หากคุณติดตั้ง uv ไว้แล้ว ไม่จำเป็นต้องตั้งค่าเพิ่มเติม — uvx จะดาวน์โหลดและรันเซิร์ฟเวอร์โดยอัตโนมัติ:

      uvx mcp-grafana

    • อิมเมจ Docker: ใช้อิมเมจ Docker ที่สร้างไว้ล่วงหน้าจาก Docker Hub

      สำคัญ: entrypoint ของอิมเมจ Docker ถูกกำหนดค่าให้รันเซิร์ฟเวอร์ MCP ในโหมด SSE โดยค่าเริ่มต้น แต่ผู้ใช้ส่วนใหญ่ต้องการใช้โหมด STDIO สำหรับการรวมเข้ากับผู้ช่วย AI โดยตรง เช่น Claude Desktop:

      1. โหมด STDIO: สำหรับโหมด stdio คุณต้องแทนที่ค่าเริ่มต้นอย่างชัดเจนด้วย -t stdio และรวมแฟล็ก -i เพื่อให้ stdin เปิดอยู่:
      docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

      หมายเหตุ — รักษาความปลอดภัยโหมดที่ใช้เครือข่าย: ในโหมด SSE และ streamable-http คอนเทนเนอร์จะผูกที่อยู่ที่ไม่ใช่ลูปแบ็ค (0.0.0.0:8000) หากไม่มีโทเค็นผู้เรียก เซิร์ฟเวอร์จะเริ่มทำงานแต่บันทึกข้อผิดพลาดด้านความปลอดภัย (ที่ระดับบันทึก error ดังนั้นจึงไม่ถูกซ่อนโดย --log-level; และจะปฏิเสธที่จะเริ่มทำงานในเวอร์ชันหลักในอนาคต) ตั้งค่า MCP_GRAFANA_SERVER_TOKEN เพื่อกำหนดให้ต้องมี Authorization: Bearer <token> จากไคลเอนต์ (แนะนำ) โหมด STDIO ไม่ได้รับผลกระทบ ดู การรับรองความถูกต้องของผู้เรียก

      1. โหมด SSE: ในโหมดนี้ เซิร์ฟเวอร์จะทำงานเป็นเซิร์ฟเวอร์ HTTP ที่ไคลเอนต์เชื่อมต่อได้ คุณต้องเปิดพอร์ต 8000 โดยใช้แฟล็ก -p:
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      1. โหมด Streamable HTTP: ในโหมดนี้ เซิร์ฟเวอร์ทำงานเป็นกระบวนการอิสระที่สามารถจัดการการเชื่อมต่อไคลเอนต์หลายรายการได้ คุณต้องเปิดพอร์ต 8000 โดยใช้แฟล็ก -p: สำหรับโหมดนี้ คุณต้องแทนที่ค่าเริ่มต้นอย่างชัดเจนด้วย -t streamable-http
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http

      สำหรับโหมด streamable HTTP แบบ HTTPS พร้อมใบรับรอง TLS ของเซิร์ฟเวอร์:

      docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

    • ดาวน์โหลดไบนารี: ดาวน์โหลดเวอร์ชันล่าสุดของ mcp-grafana จาก หน้าเผยแพร่ และวางไว้ใน $PATH ของคุณ

    • สร้างจากซอร์ส: หากคุณมีชุดเครื่องมือ Go ติดตั้งอยู่ คุณสามารถสร้างและติดตั้งจากซอร์สได้ โดยใช้ตัวแปรสภาพแวดล้อม GOBIN เพื่อระบุไดเรกทอรีที่ควรติดตั้งไบนารี ซึ่งควรอยู่ใน $PATH ของคุณด้วย

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

    • ปรับใช้กับ Kubernetes โดยใช้ Helm: ใช้ Helm chart จากที่เก็บ helm-charts ของ Grafana

      helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp

  2. เพิ่มการกำหนดค่าเซิร์ฟเวอร์ลงในไฟล์การกำหนดค่าไคลเอนต์ของคุณ ตัวอย่างเช่น สำหรับ Claude Desktop:

    หากใช้ uvx:

    {
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

    หากใช้ไบนารี:

    {
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

หมายเหตุ: หากคุณเห็น Error: spawn mcp-grafana ENOENT ใน Claude Desktop คุณต้องระบุพาธแบบเต็มไปยัง mcp-grafana

หากใช้ Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

หมายเหตุ: อาร์กิวเมนต์ -t stdio จำเป็นที่นี่เพราะแทนที่โหมด SSE เริ่มต้นในอิมเมจ Docker

การใช้ VSCode พร้อมเซิร์ฟเวอร์ MCP ระยะไกล

หากคุณใช้ VSCode และรันเซิร์ฟเวอร์ MCP ในโหมด SSE (ซึ่งเป็นค่าเริ่มต้นเมื่อใช้อิมเมจ Docker โดยไม่แทนที่ทรานสปอร์ต) ตรวจสอบให้แน่ใจว่า .vscode/settings.json ของคุณมีสิ่งต่อไปนี้:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

สำหรับโหมด streamable HTTP แบบ HTTPS พร้อมใบรับรอง TLS ของเซิร์ฟเวอร์:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

โหมดดีบัก

คุณสามารถเปิดใช้งานโหมดดีบักสำหรับทรานสปอร์ต Grafana ได้โดยเพิ่มแฟล็ก -debug ลงในคำสั่ง สิ่งนี้จะให้การบันทึกโดยละเอียดของคำขอ HTTP และการตอบกลับระหว่างเซิร์ฟเวอร์ MCP และ Grafana API ซึ่งมีประโยชน์สำหรับการแก้ไขปัญหา

หากต้องการใช้โหมดดีบักกับการกำหนดค่า Claude Desktop ให้อัปเดตการกำหนดค่าของคุณดังนี้:

หากใช้ไบนารี:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

หากใช้ Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

หมายเหตุ: เช่นเดียวกับการกำหนดค่ามาตรฐาน อาร์กิวเมนต์ -t stdio จำเป็นเพื่อแทนที่โหมด SSE เริ่มต้นในอิมเมจ Docker

การกำหนดค่า TLS

หากอินสแตนซ์ Grafana ของคุณอยู่เบื้องหลัง mTLS หรือต้องใช้ใบรับรอง TLS ที่กำหนดเอง คุณสามารถกำหนดค่าเซิร์ฟเวอร์ MCP ให้ใช้ใบรับรองที่กำหนดเองได้ เซิร์ฟเวอร์รองรับตัวเลือกการกำหนดค่า TLS ต่อไปนี้:

  • --tls-cert-file: พาธไปยังไฟล์ใบรับรอง TLS สำหรับการรับรองความถูกต้องของไคลเอนต์
  • --tls-key-file: พาธไปยังไฟล์คีย์ส่วนตัว TLS สำหรับการรับรองความถูกต้องของไคลเอนต์
  • --tls-ca-file: พาธไปยังไฟล์ใบรับรอง CA TLS สำหรับการตรวจสอบเซิร์ฟเวอร์
  • --tls-skip-verify: ข้ามการตรวจสอบใบรับรอง TLS (ไม่ปลอดภัย ใช้สำหรับการทดสอบเท่านั้น)

ตัวอย่างพร้อมการรับรองความถูกต้องด้วยใบรับรองไคลเอนต์:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

ตัวอย่างพร้อม Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

การกำหนดค่า TLS ถูกนำไปใช้กับไคลเอนต์ HTTP ทั้งหมดที่เซิร์ฟเวอร์ MCP ใช้ รวมถึง:

  • ไคลเอนต์ Grafana OpenAPI หลัก
  • ไคลเอนต์ datasource Prometheus
  • ไคลเอนต์ datasource Loki
  • ไคลเอนต์การจัดการเหตุการณ์
  • ไคลเอนต์การสืบสวน Sift
  • ไคลเอนต์การแจ้งเตือน
  • ไคลเอนต์ Asserts

ตัวอย่างการใช้งาน CLI โดยตรง:

สำหรับการทดสอบกับใบรับรองที่ลงนามด้วยตนเอง:

./mcp-grafana --tls-skip-verify -debug

ด้วยการรับรองความถูกต้องด้วยใบรับรองไคลเอนต์:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

ด้วยใบรับรอง CA ที่กำหนดเองเท่านั้น:

./mcp-grafana --tls-ca-file /path/to/ca.crt

การใช้งานเชิงโปรแกรม:

หากคุณใช้ไลบรารีนี้เชิงโปรแกรม คุณยังสามารถสร้างฟังก์ชันบริบทที่เปิดใช้งาน TLS ได้:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

การตรวจสอบ URL:

เมื่อเรียก NewGrafanaClient โดยตรง (stdio หรือการสร้างเชิงโปรแกรม) ให้ตรวจสอบ URL ล่วงหน้าเพื่อหลีกเลี่ยง panic ที่เข้าถึงได้:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

การกำหนดค่า TLS ของเซิร์ฟเวอร์ (เฉพาะ Streamable HTTP Transport)

เมื่อใช้ทรานสปอร์ต streamable HTTP (-t streamable-http) คุณสามารถกำหนดค่าเซิร์ฟเวอร์ MCP เพื่อให้บริการ HTTPS แทน HTTP ได้ สิ่งนี้มีประโยชน์เมื่อคุณต้องการรักษาความปลอดภัยการเชื่อมต่อระหว่างไคลเอนต์ MCP และเซิร์ฟเวอร์เอง

เซิร์ฟเวอร์รองรับตัวเลือกการกำหนดค่า TLS ต่อไปนี้สำหรับทรานสปอร์ต streamable HTTP:

  • --server.tls-cert-file: พาธไปยังไฟล์ใบรับรอง TLS สำหรับ HTTPS ของเซิร์ฟเวอร์ (จำเป็นสำหรับ TLS)
  • --server.tls-key-file: พาธไปยังไฟล์คีย์ส่วนตัว TLS สำหรับ HTTPS ของเซิร์ฟเวอร์ (จำเป็นสำหรับ TLS)

หมายเหตุ: แฟล็กเหล่านี้แยกจากแฟล็ก TLS ของไคลเอนต์ที่อธิบายไว้ข้างต้นโดยสิ้นเชิง แฟล็ก TLS ของไคลเอนต์กำหนดวิธีที่เซิร์ฟเวอร์ MCP เชื่อมต่อกับ Grafana ในขณะที่แฟล็ก TLS ของเซิร์ฟเวอร์เหล่านี้กำหนดวิธีที่ไคลเอนต์เชื่อมต่อกับเซิร์ฟเวอร์ MCP เมื่อใช้ทรานสปอร์ต streamable HTTP

ตัวอย่างพร้อมเซิร์ฟเวอร์ streamable HTTP แบบ HTTPS:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

สิ่งนี้จะเริ่มเซิร์ฟเวอร์ MCP บนพอร์ต HTTPS 8443 ไคลเอนต์จะเชื่อมต่อกับ https://localhost:8443/ แทน http://localhost:8000/

ตัวอย่าง Docker พร้อม TLS ของเซิร์ฟเวอร์:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Endpoint การตรวจสอบสุขภาพ

เมื่อใช้ทรานสปอร์ต SSE (-t sse) หรือ streamable HTTP (-t streamable-http) เซิร์ฟเวอร์ MCP จะแสดง endpoint การตรวจสอบสุขภาพที่ /healthz endpoint นี้สามารถใช้โดยตัวปรับสมดุลโหลด ระบบตรวจสอบ หรือแพลตฟอร์มการจัดเตรียมเพื่อตรวจสอบว่าเซิร์ฟเวอร์ทำงานและพร้อมรับการเชื่อมต่อ

Endpoint: GET /healthz

การตอบสนอง:

  • รหัสสถานะ: 200 OK
  • เนื้อหา: ok

ตัวอย่างการใช้งาน:

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# With custom address
curl http://localhost:9090/healthz

หมายเหตุ: endpoint การตรวจสอบสุขภาพพร้อมใช้งานเฉพาะเมื่อใช้ทรานสปอร์ต SSE หรือ streamable HTTP ไม่พร้อมใช้งานเมื่อใช้ทรานสปอร์ต stdio (-t stdio) เนื่องจาก stdio ไม่ได้เปิดเผยเซิร์ฟเวอร์ HTTP

การสังเกตการณ์

เซิร์ฟเวอร์ MCP รองรับเมตริก Prometheus การติดตามแบบกระจาย OpenTelemetry และการส่งออกบันทึก OpenTelemetry ตาม หลักการตั้งชื่อ MCP semantic ของ OTel การติดตามและการส่งออกบันทึกได้รับการกำหนดค่าผ่านตัวแปรสภาพแวดล้อมมาตรฐาน OTEL_* และทำงานกับทรานสปอร์ตใดก็ได้

หมายเหตุ: mcp-grafana รองรับเฉพาะทรานสปอร์ต OTLP/gRPC สำหรับทั้งการติดตามและบันทึก OTEL_EXPORTER_OTLP_PROTOCOL (และรูปแบบ _TRACES_PROTOCOL / _LOGS_PROTOCOL) จะไม่ถูกนำมาใช้ — ใช้ gRPC เสมอโดยไม่คำนึงถึง

เมตริก

เมื่อใช้ทรานสปอร์ต SSE หรือ streamable HTTP ให้เปิดใช้งานเมตริก Prometheus ด้วยแฟล็ก --metrics:

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

เมตริกที่พร้อมใช้งาน:

เมตริกประเภทคำอธิบาย
mcp_server_operation_duration_secondsHistogramระยะเวลาของการดำเนินการ MCP (ป้ายกำกับ: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramระยะเวลาของเซสชันไคลเอนต์ MCP (ป้ายกำกับ: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramระยะเวลาของคำขอ HTTP server (จาก otelhttp)

หมายเหตุ: เมตริกพร้อมใช้งานเฉพาะเมื่อใช้ทรานสปอร์ต SSE หรือ streamable HTTP ไม่พร้อมใช้งานกับทรานสปอร์ต stdio

การบันทึกคำขอช้า

แฟล็ก --slow-request-threshold ส่งอีเวนต์บันทึกที่มีโครงสร้างเมื่อใดก็ตามที่คำขอ MCP (การเรียกใช้เครื่องมือ รายการ การอ่านทรัพยากร ฯลฯ) เกินระยะเวลาที่กำหนด มีประโยชน์สำหรับการวินิจฉัยคำสั่งและการเรียกใช้เครื่องมือที่ช้าโดยไม่จมอยู่กับบันทึกดีบักเต็มรูปแบบ

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

อีเวนต์บันทึกมีแอตทริบิวต์ที่มีโครงสร้างเหล่านี้:

แอตทริบิวต์คำอธิบาย
mcp.methodเมธอด MCP (เช่น tools/call, tools/list, resources/read)
durationระยะเวลาคำขอที่สังเกตได้
thresholdเกณฑ์ที่กำหนดค่าไว้
toolชื่อเครื่องมือ (มีเฉพาะสำหรับเมธอด tools/call เท่านั้น)
errorค่าข้อผิดพลาด เมื่อคำขอล้มเหลว (บริบทแบบพยายามเต็มที่; เนื้อหาถูกควบคุมโดยการห่อหุ้มข้อผิดพลาดจากต้นทาง)
error.typeการจำแนกข้อผิดพลาดแบบจำกัดคาร์ดินาลิตี้ (_OTHER สำหรับข้อผิดพลาดที่ไม่ได้ระบุประเภท)

การบันทึกคำขอช้าทำงานบนทรานสปอร์ตทั้งหมด (รวมถึง stdio) และไม่ต้องใช้ --metrics เกณฑ์เริ่มต้นของ 0 จะปิดใช้งานทั้งหมด เครื่องมือที่ถูกพร็อกซีจะไหลผ่าน tools/call และครอบคลุมโดยอัตโนมัติ

การติดตาม

การติดตามแบบกระจายได้รับการกำหนดค่าผ่านตัวแปรสภาพแวดล้อมมาตรฐาน OTEL_* และทำงานอิสระจากแฟล็ก --metrics เมื่อตั้งค่า OTEL_EXPORTER_OTLP_ENDPOINT (หรือ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT เฉพาะสัญญาณ) เซิร์ฟเวอร์จะส่งออกการติดตามผ่าน OTLP/gRPC:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

สแปนการเรียกใช้เครื่องมือเป็นไปตามการตั้งชื่อ semconv (tools/call <tool_name>) และรวมแอตทริบิวต์เช่น gen_ai.tool.name, mcp.method.name และ mcp.session.id เซิร์ฟเวอร์ยังรองรับการแพร่กระจายบริบทการติดตาม W3C จากฟิลด์ _meta ของคำขอเรียกใช้เครื่องมือ

บันทึก

เมื่อตั้งค่า OTEL_EXPORTER_OTLP_ENDPOINT (หรือ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT เฉพาะสัญญาณ) เซิร์ฟเวอร์ยังส่งออกบันทึกที่มีโครงสร้างผ่าน OTLP/gRPC นอกเหนือจากเอาต์พุต stderr ข้อความธรรมดาที่มีอยู่ บริดจ์ otelslog แนบ trace_id และ span_id จากสแปนที่ใช้งานอยู่โดยอัตโนมัติ เพื่อให้ระเบียนบันทึกสอดคล้องกับการติดตามที่เซิร์ฟเวอร์ส่งออกอยู่แล้ว

การติดตามและบันทึกจะแก้ไข endpoint ของตนเองอย่างอิสระ ดังนั้นสัญญาณทั้งสองสามารถเปิดใช้งานแยกกันได้: การตั้งค่าเฉพาะ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT จะเปิดใช้งานการติดตาม โดยไม่มี การส่งออกบันทึก การตั้งค่าเฉพาะ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT จะเปิดใช้งานการส่งออกบันทึกโดยไม่มีการติดตาม และ OTEL_EXPORTER_OTLP_ENDPOINT ทั่วไปจะเปิดใช้งานทั้งสองอย่าง

หากคุณใช้ OTEL_EXPORTER_OTLP_ENDPOINT ทั่วไปแต่ต้องการปิดใช้งานการส่งออกบันทึก (เช่น แบ็กเอนด์ของคุณไม่รองรับ LogsService) ให้ตั้งค่า:

OTEL_LOGS_EXPORTER=none

วิธีนี้ป้องกันไม่ให้เซิร์ฟเวอร์สร้างตัวส่งออกบันทึก OTLP โดยไม่คำนึงถึงการกำหนดค่าปลายทาง และหลีกเลี่ยงข้อผิดพลาดเช่น unknown service opentelemetry.proto.collector.logs.v1.LogsService

การบันทึก stderr จะไม่เปลี่ยนแปลงเมื่อเปิดใช้งานการบันทึก OTLP; คุณยังคงพึ่งพาบันทึกคอนเทนเนอร์หรือส่ง stderr ไปยัง /dev/null ได้หากคุณต้องการ

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

การขนส่งคือ OTLP/gRPC (พอร์ตเริ่มต้น 4317) บันทึกสามารถส่งไปยังแบ็กเอนด์ที่จัดการใดๆ ที่ยอมรับ OTLP/gRPC — ตัวอย่างเช่น Grafana Cloud — โดยชี้ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (หรือ OTEL_EXPORTER_OTLP_ENDPOINT ทั่วไป) ไปยังปลายทาง gRPC ระยะไกลและระบุการรับรองความถูกต้องผ่าน OTEL_EXPORTER_OTLP_LOGS_HEADERS (หรือ OTEL_EXPORTER_OTLP_HEADERS) ซึ่งคล้ายกับตัวอย่างการติดตามด้านบน ตัวเก็บรวบรวม OTel ในเครื่องเป็น ทางเลือก — มีประโยชน์สำหรับการกระจาย การจัดกลุ่ม หรือการกำหนดเส้นทางหลายแบ็กเอนด์ แต่ไม่จำเป็น

ตัวแปรเฉพาะสัญญาณ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT, และ OTEL_EXPORTER_OTLP_LOGS_COMPRESSION จะได้รับการยอมรับและแทนที่ OTEL_EXPORTER_OTLP_* ทั่วไป — ดู ข้อกำหนดตัวส่งออก OTel สำหรับรายการเต็มและกฎลำดับความสำคัญ

หากตัวเก็บรวบรวมที่กำหนดค่าไว้ไม่สามารถเข้าถึงได้ เรกคอร์ดบันทึกจะถูกบัฟเฟอร์ในหน่วยความจำ (คิวเริ่มต้น: 2048) และเรกคอร์ดที่เก่าที่สุดจะถูกทิ้งเมื่อคิวเต็ม กระบวนการดำเนินต่อไปโดยไม่บล็อกบริการ กำหนดค่าตัวเก็บรวบรวม OTel ในเครื่องหากคุณต้องการบัฟเฟอร์ที่ไม่สูญเสียระหว่างการหยุดทำงาน

บันทึกยังถูกส่งออกภายใต้การขนส่ง stdio ซึ่งทำให้ง่ายต่อการรวมศูนย์บันทึกจากอินสแตนซ์ mcp-grafana ในเครื่องที่เรียกโดยไคลเอนต์ IDE

ตัวอย่าง Docker พร้อมเมตริก การติดตาม และบันทึก:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

การแก้ไขปัญหา

ความเข้ากันได้ของเวอร์ชัน Grafana

หากคุณพบข้อผิดพลาดต่อไปนี้เมื่อใช้เครื่องมือที่เกี่ยวข้องกับแหล่งข้อมูล:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

โดยทั่วไปแล้วบ่งชี้ว่าคุณกำลังใช้ Grafana เวอร์ชันก่อน 9.0 จุดสิ้นสุด API /datasources/uid/{uid} ถูกนำมาใช้ใน Grafana 9.0 และการดำเนินการแหล่งข้อมูลจะล้มเหลวในเวอร์ชันก่อนหน้า

วิธีแก้ไข: อัปเกรดอินสแตนซ์ Grafana ของคุณเป็นเวอร์ชัน 9.0 หรือใหม่กว่าเพื่อแก้ไขปัญหานี้

การพัฒนา

ยินดีรับการสนับสนุน! โปรดเปิด issue หรือส่ง pull request หากคุณมีข้อเสนอแนะหรือการปรับปรุง

โปรเจกต์นี้เขียนด้วยภาษา Go ติดตั้ง Go ตามคำแนะนำสำหรับแพลตฟอร์มของคุณ

เพื่อเรียกใช้เซิร์ฟเวอร์ในเครื่องในโหมด STDIO (ซึ่งเป็นค่าเริ่มต้นสำหรับการพัฒนาในเครื่อง) ให้ใช้:

make run

เพื่อเรียกใช้เซิร์ฟเวอร์ในเครื่องในโหมด SSE ให้ใช้:

go run ./cmd/mcp-grafana --transport sse

คุณยังสามารถเรียกใช้เซิร์ฟเวอร์โดยใช้การขนส่ง SSE ภายในอิมเมจ Docker ที่สร้างเองได้ เช่นเดียวกับอิมเมจ Docker ที่เผยแพร่ จุดเริ่มต้นของอิมเมจที่กำหนดเองนี้จะตั้งค่าเป็นโหมด SSE ตามค่าเริ่มต้น ในการสร้างอิมเมจ ให้ใช้:

make build-image

และเพื่อเรียกใช้อิมเมจในโหมด SSE (ค่าเริ่มต้น) ให้ใช้:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

หากคุณต้องการเรียกใช้ในโหมด STDIO แทน ให้ล้างค่าการตั้งค่าการขนส่ง:

docker run -it --rm mcp-grafana:latest -t stdio

การทดสอบ

มีการทดสอบสามประเภท:

  1. การทดสอบหน่วย (ไม่ต้องพึ่งพาภายนอก):
make test-unit

คุณยังสามารถเรียกใช้การทดสอบหน่วยได้ด้วย:

make test
  1. การทดสอบการรวมระบบ (ต้องมีคอนเทนเนอร์ Docker รันอยู่):
make test-integration
  1. การทดสอบคลาวด์ (ต้องมีอินสแตนซ์ Grafana คลาวด์และข้อมูลรับรอง):
make test-cloud

หมายเหตุ: การทดสอบคลาวด์ถูกกำหนดค่าโดยอัตโนมัติใน CI สำหรับการพัฒนาในเครื่อง คุณจะต้องตั้งค่าอินสแตนซ์ Grafana Cloud และข้อมูลรับรองของคุณเอง

การทดสอบการรวมระบบที่ครอบคลุมมากขึ้นจะต้องมีอินสแตนซ์ Grafana รันในเครื่องที่พอร์ต 3000; คุณสามารถเริ่มได้ด้วย Docker Compose:

docker-compose up -d

การทดสอบการรวมระบบสามารถเรียกใช้ได้ด้วย:

make test-all

หากคุณกำลังเพิ่มเครื่องมือเพิ่มเติม โปรดเพิ่มการทดสอบการรวมระบบสำหรับเครื่องมือเหล่านั้น การทดสอบที่มีอยู่ควรเป็นจุดเริ่มต้นที่ดี

การตรวจสอบโค้ด (Linting)

เพื่อตรวจสอบโค้ด ให้รัน:

make lint

ซึ่งรวมถึง linter ที่กำหนดเองที่ตรวจสอบเครื่องหมายจุลภาคที่ไม่ได้รับการ escape ในแท็กโครงสร้าง jsonschema เครื่องหมายจุลภาคในฟิลด์ description ต้องถูก escape ด้วย \\, เพื่อป้องกันการตัดทอนอย่างเงียบๆ คุณสามารถรันเฉพาะ linter นี้ได้ด้วย:

make lint-jsonschema

ดู เอกสาร JSONSchema Linter สำหรับรายละเอียดเพิ่มเติม

ลิขสิทธิ์

โปรเจกต์นี้อยู่ภายใต้ Apache License, เวอร์ชัน 2.0