> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/bluerock-dashboard/bluerock-dashboard-user-guide.md). # Bluerock Dashboard User Guide ## Introduction The BlueRock Dashboard provides a centralized interface for monitoring MCP infrastructure, telemetry activity, sessions, events, alerts, analytics, and operational reports. The dashboard enables users to: * Monitor MCP infrastructure and activity * Investigate alerts and policy violations * Analyze telemetry and events * Visualize topology relationships * Review operational analytics * Monitor MCP agents and servers * Explore historical and real-time activity * Investigate operational trends and anomalies *** ## Accessing the Dashboard The dashboard is accessed through HTTPS. ### Dashboard URL ``` https:// ``` ### Grafana URL ``` https:///grafana ``` ### Browser Security Warning The dashboard uses a self-signed certificate. During first access, the browser may display a security warning or "Not Secure" message. Accept the warning to continue accessing the dashboard. *** ## Dashboard Navigation The left-side navigation menu provides access to dashboard sections and monitoring views. ### Main Navigation Areas * Dashboard * Hosts * MCP Servers * MCP Agents * Tools * Alerts * Event Log * Reports * Explore * Workbooks * Reactive Rules * HRamp Operations * A2M Analytics
*** ## Dashboard Home The Dashboard Home page provides a high-level summary of MCP ecosystem activity. ### Dashboard Metrics The dashboard displays the following summary metrics: * Alerts * Reviewed/Dismissed Alerts * Events * Servers * Tools * Agents * Hosts These metrics provide a quick overview of platform activity and operational health. #### User Interface Example:
*** ### Dashboard Widgets #### Agent Ecosystem The Agent Ecosystem section displays information about MCP agents operating within the environment. The visualization helps users understand: * Active agent inventory * Agent distribution * Agent activity trends * Framework utilization #### Recent Events The Recent Events section displays operational events collected by BlueRock. Events may include: * Informational events * Warning events * Error events * Operational events This section provides visibility into recent activity occurring within the monitored environment. #### MCP Activity Trends The MCP Activity section provides visibility into MCP operational activity. The dashboard displays: * Active MCP sessions * Session creation activity * Session termination activity * MCP activity trends over time These metrics help users understand MCP utilization patterns and operational behavior. #### Top Tools The Top Tools widget displays the most frequently utilized MCP tools within the environment. This visualization helps identify: * Frequently used tools * Tool activity patterns * Operational trends #### User Interface Example:
*** ### Time Filtering The dashboard supports time-based filtering for viewing recent operational activity. Available views depend on the selected dashboard and time range. #### User Interface Example:
*** ## Hosts The Hosts page displays infrastructure hosts monitored by BlueRock. Users can review host inventory and investigate host-related activity. ### Host Information Each host entry displays: * Host Name * First Seen * Last Seen ### Available Actions #### Graph Displays host relationships within the topology graph. #### Historical Displays historical activity for the selected host. #### User Interface Example:
*** ## MCP Servers The MCP Servers page displays registered MCP servers. ### MCP Server Information Each server entry displays: * Server Name * Host * Entity ID * Last Seen * Created Timestamp ### Available Actions #### Graph Displays server relationships within the topology graph. #### Historical Displays historical activity associated with the selected server. #### User Interface Example:
*** ## MCP Agents The MCP Agents page displays discovered MCP clients and agents. ### Agent Information Each agent entry displays: * Agent Name * Host * Entity ID * Component * Last Seen * Created Timestamp Users can review agent activity and investigate relationships between agents, sessions, and MCP servers. #### User Interface Example:
*** ## AI Agent Monitoring BlueRock supports monitoring of AI agents and AI-assisted workflows. Examples may include: * Claude Code * Cursor * Gemini CLI * Codex CLI * Custom AI Agents Available visibility includes: * Tool Calls * Token Consumption * Permission Denials * Errors * Cost Metrics * Sub-Agent Activity This information helps users understand AI usage patterns and operational behavior. *** ## Tools The Tools page displays tools registered by MCP servers. ### Tool Information Each tool entry displays: * Tool Name * Description * Associated Server ### Example Tools #### read\_file Reads file contents. #### write\_file Creates or modifies files. #### remove\_file Deletes files. #### User Interface Example:
*** ## Alerts The Alerts page displays operational alerts and policy violations. ### Alert Categories The dashboard supports: * Active Alerts * Acknowledged Alerts * Dismissed Alerts #### User Interface Example:
*** ### MCP Policy Violations Policy violations are generated when MCP activity violates configured security policies. Example: ``` check_message_size ``` #### Alert Information Each alert displays: * Alert ID * Rule Name * Host * Timestamp * Occurrence Count ### Alert Actions Available actions include: * Acknowledge * Dismiss #### User Interface Example:
*** ## Event Log The Event Log page provides access to operational events. ### Event Log Features The Event Log supports: * Event Search * Event Filtering * Event Export * Event Analysis ### Time Filters Available time ranges include: * 1 Hour * 6 Hours * 24 Hours * 3 Days * 7 Days #### User Interface Example:
*** ## Reports The Reports page provides pre-built operational reports. ### Accessing Reports 1. Navigate to Reports. 2. Browse available reports. 3. Click View to generate a report. #### User Interface Example:
*** ### Available Reports The Reports page includes several predefined reports.
ReportDescription
Active Hosts OverviewUnified view of hosts with status distribution, pulse vitals, and regional breakdown.
MCP Sessions ReportSession inventory with client-server connections, success rates, and lifecycle states.
Alert Trends & Critical AlertsAlert severity trends with detailed critical alert drill-down.
Top Tools UsageTool call counts, success rates, and average execution times.
Tool Failure AnalysisTool failures, error codes, and failure patterns.
MCP Agent ActivityAgent inventory, status, session counts, request velocity, and host associations.
MCP Server ActivityServer inventory with status, registered tools, session activity, and request throughput.
#### User Interface Example:
*** ## Explore The Explore page provides an interactive topology visualization of the MCP ecosystem. ### Root Views Available root views include: * Default * MCP Servers * Agents * Sessions * LLMs #### User Interface Example:
*** ### Layout Modes The topology graph supports multiple layouts: * Tree * Force * Circle * Group #### User Interface Example:
*** ### Graph Filter Language (GFL) The Explore page supports Graph Filter Language (GFL) expressions for filtering and analyzing entities. GFL is used throughout BlueRock for: * Entity filtering * Relationship analysis * Session tracing * Activity investigation * Operational analytics #### Common Entity Types | Prefix | Entity | | ------ | ---------- | | ho | Host | | ms | MCP Server | | mc | MCP Agent | | ss | Session | | tl | Tool | | mo | Model | | ag | AI Agent | | al | Alert | #### Example Filters ``` mc.state == 'active' ``` ``` ms.transport == 'stdio' ``` ``` pivot mc mc == ALL ``` #### Time-Based Filtering **Examples:** ``` since 1h ``` ``` since 24h ``` ``` mc.state == 'active' && since 6h ``` #### User Interface Example:
*** ### Session Tracing Explore supports graph-based tracing of relationships between entities. A typical investigation workflow may involve: Host → Agent → MCP Server → Session → Event Activity This enables users to follow operational activity across the MCP ecosystem and investigate issues. *** ### Ghost Entities Ghost entities represent historical relationships that are no longer active. #### User Interface Example:
*** ### Re-layout The Re-layout action redraws the topology using the selected layout algorithm. #### User Interface Example:
*** ## Workbooks The Workbooks page provides access to predefined and custom analytical workbooks. Workbooks organize charts, tables, and analytical panels into reusable investigation views. #### User Interface Example:
*** ### Available Workbooks Examples visible in the dashboard include: * agent-drill-down * agent-health * danger-tool-audit * error-investigation * health-matrix * llm-cost-performance * llm-operations * mcp-activity * ops-triage * production-triage * server-overview * session-drill-down * topology-and-stats *** ### Workbook Purpose Workbooks help users: * Investigate incidents * Analyze trends * Monitor infrastructure * Review session activity * Track agent behavior * Perform operational triage *** ### Workbook Panel Types Workbooks may contain: * Charts * Tables * Time Series * Health Tests * Snapshots * Event Views * Alert Views *** ### Creating a Workbook 1. Navigate to Workbooks. 2. Select Create Workbook. 3. Configure workbook details. 4. Add charts and panels. 5. Save the workbook. #### User Interface Example:
*** ## Reactive Rules Reactive Rules allow users to create automated operational monitoring rules. Rules monitor selected entities and trigger actions when configured conditions are met. #### User Interface Example:
*** ### Creating a Rule 1. Select New Rule. 2. Enter a rule name. 3. Define a GFL expression. 4. Configure conditions. 5. Configure actions. 6. Save the rule. #### User Interface Example:
*** ### Rule Components #### GFL Expression A GFL expression defines the scope of entities that the rule evaluates. The expression is used to identify the graph entities that should be monitored by the rule. Example: ``` mc.state == 'active' ``` #### **Rule Conditions** Rule conditions define the criteria that must be met before an action is triggered. Conditions are configured during rule creation and are evaluated against the entities returned by the GFL expression. #### **Actions** Actions define the response that occurs when the configured rule conditions are met. *** ## HRamp Operations Dashboard The HRamp Operations dashboard provides operational telemetry visibility. ### Dashboard Metrics Visible metrics include: * Active Hosts * Total Active Entities * Total Terminated Sessions ### Dashboard Panels The dashboard includes: * Top Event Types by Volume * Event Type Counts * Active MCP Sessions * Session Creation Rate * Total MCP Sessions Created * Session Termination Reasons #### User Interface Example:
*** ## Agent-to-Model (A2M) Analytics The A2M Analytics dashboard provides visibility into LLM activity, token consumption, latency, and cost. ### Purpose A2M Analytics helps organizations understand how AI models are being used across monitored environments. ### Supported Use Cases #### Agent Monitoring Organizations running AI agents can monitor: * Model Usage * Framework Usage * Token Consumption * Cost * Request Volume * Latency #### Developer AI Usage Organizations using AI-assisted development tools can monitor: * LLM Utilization * Token Consumption * Cost Trends * Model Adoption ### Dashboard Metrics Visible metrics include: * Total Calls * Pending Requests * Completed Requests * Input Tokens * Output Tokens * Models * Frameworks ### Dashboard Panels The dashboard includes: * LLM Call Rate * Token Consumption Rate * Call Latency * Calls by Model * Model Distribution * Framework Distribution * Cost Trends #### User Interface Example:
*** ## LLM Cost Dashboard ### Overview The **LLM Cost** dashboard provides operational visibility into Large Language Model (LLM) usage by monitoring token consumption, estimated costs, and model utilization across AI agents and applications. The dashboard helps administrators understand LLM usage patterns and identify opportunities to optimize AI workloads. *** #### Dashboard Views The dashboard displays estimated LLM token consumption and cost information. Data can be grouped using the following dimensions: * Team * User * Application * Agent * Model * Framework * Tag The dashboard supports multiple time ranges, including: * Last 1 hour * Last 6 hours * Last 24 hours * Last 7 days *** #### Dashboard Panels **LLM Cost** Displays estimated LLM token consumption and cost information. The table provides usage statistics grouped by the selected view (Agent, Model, Framework, Team, or Tag) and includes: * Selected grouping dimension * Usage trend * Input token count * Output token count * Estimated cost (when available) Users can switch between grouping options to analyze LLM usage from different operational perspectives. **Calls by Outcome** Displays the distribution of completed LLM requests based on request outcomes. The panel summarizes: * Total tool calls * Stop conditions * Average response length * Percentage distribution of each outcome This information helps administrators understand request completion behavior and overall workload characteristics. **Tokens per Call** Displays statistical information about input and output token consumption for each language model. The panel includes: * Input token distribution * Output token distribution * Percentile statistics (P50, P95, and P99) These metrics help identify models generating unusually large requests or responses. **Containment Activity** Displays alerts generated by configured cost-control rules and other containment policies. This panel helps administrators identify policy violations, abnormal LLM usage patterns, and cost-related operational events. #### User Interface Example:
*** #### Grouping Views The LLM Cost dashboard allows users to analyze usage data using the following views: **Agent View** Displays token usage and estimated cost information grouped by AI agent. This view helps identify: * High-utilization agents * Token consumption by individual agents * Estimated LLM cost per agent * Input and output token counts * Usage trends
**Model View** Displays token usage grouped by Large Language Models. This view enables administrators to: * Compare model utilization * Identify heavily used models * Compare token consumption across models * Review estimated costs by model
**Framework View** Displays token usage grouped by AI framework or provider, such as OpenAI, Anthropic, Gemini, or LiteLLM. This view helps compare framework utilization and understand token consumption across different AI providers.
**Team View** Displays aggregated LLM usage grouped by organizational team. This view enables administrators to compare token consumption and estimated costs across teams and identify which teams are generating the highest LLM usage.
**User View** Displays LLM usage grouped by individual users, allowing administrators to analyze token consumption, estimated costs, and usage patterns for each user. **Application View** Displays LLM usage grouped by application or service, enabling administrators to compare token consumption and estimated costs across applications. *** #### Operational Benefits The LLM Cost dashboard helps administrators: * Monitor LLM token consumption across AI workloads. * Compare usage across agents, models, frameworks, applications, and teams. * Identify the most frequently used AI models and providers. * Understand request characteristics using call outcome statistics. * Analyze input and output token distribution across models. * Detect abnormal usage through containment policies and alerts. * Optimize AI usage and reduce operational costs. *** ### LLM Cost Alerts #### Overview The LLM Cost Alerts page provides visibility into alerts generated when configured LLM cost-control or containment policies are triggered. Alerts are generated when configured thresholds detect abnormal LLM activity, excessive token usage, or other cost-related conditions requiring administrator attention. Administrators can review alert details, investigate related events, and perform follow-up actions to understand and resolve abnormal LLM usage. #### Alert Information Each alert includes information to help administrators understand the detected condition, including: * Alert severity * Alert status * Alert type * Timestamp * Affected agent or application * Alert description * Associated containment policy * Related operational events This information helps administrators quickly identify the cause of the alert and determine the appropriate response. #### Alert Actions The Alerts page provides the following actions for managing and investigating alerts: * **Acknowledge** the alert after review. * **Dismiss** alerts that do not require further action. * **Add to TODO** for follow-up investigation. * **View Events** to examine the events associated with the alert. * **View Trace** to analyze the execution path leading to the alert. * **Analyze** to investigate the alert using the available analytics and investigation tools. These actions help administrators investigate policy violations, understand runtime behavior, and perform operational troubleshooting. #### User Interface Example:
*** ### Agent-to-Model (A2M) Analytics #### Overview The **Agent-to-Model (A2M) Analytics** dashboard provides operational insights into interactions between AI agents and Large Language Models (LLMs). It enables administrators to monitor request volume, token consumption, model utilization, framework distribution, and call performance over time. Unlike the LLM Cost dashboard, which focuses on cost and token usage, the A2M Analytics dashboard emphasizes request volume, latency, model utilization, and operational performance. The dashboard helps identify usage trends, evaluate model performance, and optimize AI workloads. #### Dashboard Panels **Summary Metrics** Provides an overview of LLM activity, including: * Total calls * Pending calls * Completed calls * Input tokens * Output tokens * Models in use * Frameworks in use **LLM Call Rate** Displays the rate of LLM requests over time for each model, helping administrators monitor workload trends and identify spikes in activity. **Token Consumption Rate** Displays input and output token usage over time, allowing users to analyze token consumption patterns across different language models. **Call Latency (Average)** Displays the average response time for LLM requests, enabling users to monitor model performance and identify latency trends. **Calls by Model** Displays the distribution of requests across configured language models, helping administrators understand model utilization. **Calls by Framework** Displays the distribution of requests across supported AI frameworks or providers, such as OpenAI, Anthropic, Gemini, and LiteLLM. #### Time Filter The dashboard supports viewing analytics over configurable time ranges. Users can select the desired time period from the time filter to analyze recent activity. #### User Interface Example:
*** ### Token Usage Policy Control #### Overview The Token Usage Policy Control feature enables administrators to monitor and control Large Language Model (LLM) token consumption. The policy helps prevent excessive token usage by enforcing configurable limits on individual requests and overall token consumption. When enabled, the policy can generate violations or block requests that exceed configured limits. It also provides token usage information that is displayed in the BlueRock Dashboard for operational monitoring and cost analysis. **Note:** Token usage monitoring is supported for the LLM Model Framework sensors, including OpenAI, Anthropic, Gemini, and LiteLLM. It is not supported for Coding Sensors in this release. #### Policy Configuration The Token Usage Policy Control feature is configured using the **`llm_max_tokens`** policy. **Default Policy:** ```json "llm_max_tokens": { "enable": false, "remediate": false, "max_total_tokens_per_call": null, "bucket_enabled": false, "bucket_capacity": 100000, "refill_rate": 200.0, "multiplier": 0.3, "refuse_fewer_than_tokens": 100, "token_estimator": "bytes_div4" } ``` **Configuration Parameters**
ParameterDescription
enableEnables or disables token usage monitoring.
remediateWhen enabled, requests exceeding configured limits are blocked.
max_total_tokens_per_callMaximum combined input and output tokens permitted for a single LLM request. Null means no limit.
bucket_enabledEnables token bucket rate limiting.
bucket_capacityMaximum number of tokens that can accumulate in the token bucket.
refill_rateNumber of tokens added to the bucket per second.
multiplierMultiplier applied to available bucket tokens to determine the effective request allowance.
refuse_fewer_than_tokensRejects requests when the remaining available response token budget falls below the configured threshold.
token_estimatorMethod used to estimate input token usage.
*** #### Generated Events The Token Usage Policy Control feature generates operational events that provide visibility into LLM token usage and policy enforcement. **Usage Event** A python\_llm\_reply event is generated for each monitored LLM request. The event contains token usage statistics together with the model and framework information. **Token Limit Violation Event** A python\_llm\_max\_tokens\_violation event is generated in the following situations: • When max\_total\_tokens\_per\_call is configured and the estimated request and response tokens exceed the configured limit. • When refuse\_fewer\_than\_tokens is configured and the effective response token budget falls below the configured threshold. **Event Examples** The following examples demonstrate the operational events generated by the Token Usage Policy Control feature. **Example 1 – Usage Event** The following example shows a python\_llm\_reply event containing token usage statistics. **Policy Configuration** ```json "llm_max_tokens": { "enable": true, "remediate": true, "max_total_tokens_per_call": 2048, "bucket_enabled": true, "bucket_capacity": 10000, "refill_rate": 200.0, "multiplier": 0.3, "refuse_fewer_than_tokens": 100, "token_estimator": "bytes_div4" } ``` **Event Output** {% code expandable="true" %} ```json { "created": 1783409328, "id": "chatcmpl-7d7295d5-42c3-42f5-87f1-ea613929d8b5", "model": "claude-sonnet-4-6@default", "object": "chat.completion", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "completion_tokens": 53, "completion_tokens_details": { "reasoning_tokens": 0, "text_tokens": 53 }, "prompt_tokens": 2375, "prompt_tokens_details": { "cache_creation_token_details": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_creation_tokens": 0, "cached_tokens": 0, "text_tokens": 2375 }, "total_tokens": 2428 }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/7dac4012-146e-44a2-bc3e-e4745f33e6b4", "domain": "gyro", "event_name": "python_llm_reply", "hostid": "ip-172-31-39-21.ec2.internal", "origin": "bluepython", "sensor_id": 3727, "source_event_id": 18, "type": "event" } } ``` {% endcode %} **Example 2 – Maximum Token Limit Violation** The following example shows a python\_llm\_max\_tokens\_violation event generated when the estimated request and response tokens exceed the configured max\_total\_tokens\_per\_call limit. **Remediation Disabled** ```json "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "LLM request max_tokens set to 1744 (was Some(4096), input estimate: 304)", "event_name": "python_llm_max_tokens_violation", "type": "log" } ``` **Remediation Enabled** ```json "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "LLM request max_tokens set to 889 (was Some(4096), input estimate: 2036)", "event_name": "python_llm_max_tokens_violation", "remediation_kind": "modify", "type": "remediation" } ``` **Example 3 – Response Token Threshold Violation** The following example shows a python\_llm\_max\_tokens\_violation event generated when the effective response token budget falls below the configured refuse\_fewer\_than\_tokens threshold. **Remediation Disabled** ```json "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "LLM request refused: effective max_tokens 12 is below threshold 100 (input estimate: 2036)", "domain": "gyro", "event_name": "python_llm_max_tokens_violation", "hostid": "ip-172-31-39-21.ec2.internal", "origin": "uc-gyro", "sensor_id": 3737, "source_event_id": 17, "type": "log" } ``` **Remediation Enabled** ```json "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "LLM request refused: effective max_tokens 80 is below threshold 100 (input estimate: 390)", "domain": "gyro", "event_name": "python_llm_max_tokens_violation", "hostid": "ip-172-31-39-21.ec2.internal", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 3746, "source_event_id": 52, "type": "remediation" } ``` *** ## Operational Diagnostics The Operational Diagnostics panel displays diagnostic events generated by the platform. Users can: * View diagnostic events * Review operational health information * Clear diagnostic entries #### User Interface Example:
*** ## User Profile The User Profile panel displays authenticated user information. Information displayed includes: * User Email * Role * Capabilities #### User Interface Example:
*** ## Common User Workflows ### Monitoring MCP Activity Users can: * Monitor MCP agents * Monitor MCP servers * Analyze sessions * Review activity trends * Explore topology relationships ### Investigating Alerts Users can: * Review active alerts * Analyze policy violations * View related events * Investigate traces ### Exploring Infrastructure Users can: * Open Explore * Apply GFL filters * Switch layouts * Analyze relationships ### Monitoring Analytics Users can: * Review A2M metrics * Analyze token consumption * Monitor latency trends * Review operational dashboards ### Managing Reactive Rules Users can: * Create rules * Configure triggers * Monitor rule activity *** ## Troubleshooting ### Dashboard Not Loading Verify: * Dashboard accessibility * HTTPS connectivity * Active dashboard instance ### Empty Dashboard Panels Some dashboard views require active event traffic before data becomes visible. ### Graph Loading Issues Verify: * Selected filters * Selected time ranges * Event visibility * Active telemetry ingestion ### Alert Visibility Issues Verify: * Event ingestion * Active policies * Alert generation *** ## FAQ ### Why does the browser show "Not Secure"? The dashboard uses a self-signed certificate. Accept the browser warning to continue. ### Why are some dashboards empty? Certain dashboards require incoming telemetry and event traffic before data is displayed. ### Why are graphs not loading? Verify event visibility, filters, and selected time ranges. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bluerock.io/bluerock-dashboard/bluerock-dashboard-user-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.