Ask O11y transforms how you interact with your observability data. Query metrics, analyze logs, create dashboards, and troubleshoot issues through natural language conversations—no need to write PromQL, LogQL, or navigate complex UIs.
Ask O11y is a Grafana app plugin that brings AI assistance directly into your observability workflow. Instead of learning complex query languages or navigating multiple dashboards, simply ask questions in plain English:
- "Show me CPU usage across all servers in the last hour"
- "Find error logs from the payment service"
- "Create a dashboard to monitor Kubernetes cluster health"
- "What's causing the spike in response times?"
The assistant understands your Grafana environment, executes the right queries, and presents results with interactive visualizations—all through natural conversation.
For SREs and DevOps Engineers:
- Troubleshoot faster with natural language queries
- No need to memorize PromQL, LogQL, or TraceQL syntax
- Get instant visualizations without building dashboards
For Platform Teams:
- Democratize access to observability data across your organization
- Reduce training time for new team members
- Enable non-technical stakeholders to explore metrics and logs
For Engineering Teams:
- Reduce mean time to resolution (MTTR) during incidents
- Query multiple data sources (metrics, logs, traces) in one conversation
- Automate common dashboard and alerting tasks
Query Your Data Without Writing Code:
- Ask questions in plain English and get instant answers
- Support for Prometheus metrics (PromQL), Loki logs (LogQL), and Tempo traces (TraceQL)
- Real-time streaming responses with live tool execution status
- Context-aware suggestions based on your Grafana environment
Example Queries:
"Show me HTTP request rate grouped by endpoint as a bar chart"
"Find all timeout errors in the last 15 minutes"
"Display memory utilization as a gauge with thresholds"
"Compare CPU usage between production and staging"
Get automatic visualizations with every query—no manual dashboard building required:
- Time Series: Line graphs for metrics over time
- Stats: Single-value statistics with sparklines and trends
- Gauge: Visual indicators with configurable thresholds
- Table: Sortable, filterable tabular data
- Pie Chart: Proportional distributions
- Bar Chart: Comparative visualizations (horizontal/vertical)
- Heatmap: Density patterns and distributions
- Histogram: Value distribution analysis
Interactive Controls:
- Switch visualization types on-the-fly (time series → gauge → pie chart)
- Adjust time ranges with built-in time picker
- Configure auto-refresh intervals (5s to 1h)
- Expand charts for detailed analysis
- Copy queries (PromQL/LogQL/TraceQL) to clipboard for reuse
- Automatic light/dark theme support
Extensible Tool Architecture:
- 56+ Built-in Grafana Tools: Complete dashboard, datasource, alerting, and query management
- Dynamic Tool Discovery: Automatically detects available tools from configured MCP servers
- Multiple Transport Types: Supports standard MCP, OpenAPI/REST, SSE streaming, and HTTP streamable
- Custom Server Support: Add your own MCP servers for internal tools and APIs
Available Tool Categories:
- Datasource Operations: Query, list, test connectivity
- Dashboard Management: Create, update, delete, search dashboards
- Alert Management: Configure alerts, silences, notification channels
- Query Execution: Run PromQL, LogQL, TraceQL queries with visualization
- Resource Discovery: Search and explore Grafana resources
Role-Based Access Control (RBAC):
- Admin/Editor: Full access to all 56 tools (read + write operations)
- Viewer: Restricted to 45 read-only tools (query, list, get, search only)
- Automatic permission enforcement on every tool execution
- Granular control over who can modify dashboards, datasources, and alerts
Multi-Tenant Organization Isolation:
- Chat sessions automatically scoped per Grafana organization
- Complete data isolation between organizations
- Seamless context switching when changing organizations
- Organization-specific MCP server configurations
Security Best Practices:
- Comprehensive input validation and schema validation
- SQL injection and XSS prevention
- Secure credential handling
- Audit logging for all operations
Never Lose Your Work:
- Auto-Save: All conversations saved every 2 seconds
- Session History: Browse, resume, and manage previous conversations
- Organization Scoping: Sessions isolated per Grafana organization
- Import/Export: Backup sessions as JSON or share with team members
- Automatic Cleanup: Oldest sessions removed when storage quota reached
- Session Metadata: Auto-generated titles, timestamps, message counts
Quick Actions:
- Start new conversations instantly
- Delete individual sessions or clear all
- Search through conversation history
- Export important conversations for documentation
- System Prompts: Customize AI behavior (default, replace, or append mode)
- Token Limits: Configure maximum tokens for LLM requests
- MCP Server Management: Add, configure, enable/disable servers
- Health Monitoring: Real-time health checks with status indicators
- Streaming responses with real-time updates
- Efficient storage with smart caching
- Type-safe TypeScript frontend + Go backend
- JSON Schema validation for all operations
- Comprehensive test coverage
- Grafana: Version 12.1.1 or later
- Grafana LLM Plugin: grafana-llm-app configured with an AI provider
- Datasources (recommended):
- Prometheus for metrics
- Loki for logs
- Tempo for traces (optional)
Once published to the Grafana plugin catalog, install with one command:
grafana-cli plugins install consensys-asko11y-appThen restart your Grafana instance.
- Download the latest release from GitHub Releases
- Extract to your Grafana plugins directory:
- Linux:
/var/lib/grafana/plugins/ - macOS (Homebrew):
/opt/homebrew/var/lib/grafana/plugins/ - Docker: Mount as volume to
/var/lib/grafana/plugins/ - Windows:
C:\Program Files\GrafanaLabs\grafana\data\plugins\
- Linux:
- Restart Grafana
git clone https://github.com/Consensys/ask-o11y-plugin.git
cd ask-o11y-plugin
npm install
npm run build
# Copy dist/ to your Grafana plugins directorygrafana-cli plugins install grafana-llm-appIn Grafana UI:
- Navigate to Configuration → Plugins → Grafana LLM
- Click Enable
- Configure your AI provider:
- OpenAI: Add API key, select model (gpt-4, gpt-3.5-turbo)
- Anthropic: Add API key, select model (claude-3-opus, claude-3-sonnet)
- Other providers: Follow provider-specific instructions
- Go to Configuration → Plugins → Ask O11y → Configuration
- Add MCP Grafana server:
- Name:
grafana - URL: Your mcp-grafana endpoint (e.g.,
http://mcp-grafana:8000/mcp) - Type:
streamable-http - Enabled: ✓
- Name:
- Click Save
- Navigate to Apps → Ask O11y
- Type your first question: "Show me CPU usage in the last hour"
- Watch the magic happen!
"Show me CPU usage across all servers in the last hour"
"Create a gauge showing memory utilization percentage"
"Display HTTP request rate as a bar chart grouped by endpoint"
"Show me a heatmap of response times over the last 24 hours"
"Find all error logs from the payment service in the last 15 minutes"
"Show me logs containing 'timeout' from production namespace"
"What are the most common error messages in the last hour?"
"Display recent failed authentication attempts"
"Show me traces for the checkout API with duration > 500ms"
"Find slow database queries in the last 30 minutes"
"Display a histogram of request latencies"
"Which services have the highest error rates?"
"Create a dashboard to monitor Kubernetes cluster health"
"Add a time series panel showing 95th percentile latency"
"List all dashboards in the 'Production' folder"
"Search for dashboards related to payments"
Frontend: React + TypeScript with real-time streaming, interactive visualizations, and session management
Backend: Go plugin with MCP server aggregation, OpenAPI validation, RBAC, and multi-tenant support
Integration: Supports multiple MCP transport types with dynamic tool discovery and health monitoring
Want to contribute or customize the plugin?
- Node.js >= 22
- Go >= 1.21
- Docker & Docker Compose
- Mage (Go build tool)
# Install dependencies
npm install
# Build the plugin
npm run build
# Start development environment
npm run server
# Access Grafana at http://localhost:3000 (admin/admin)Frontend Development (with hot reload):
npm run devBackend Development:
# Build for current platform
npm run build:backend
# Restart Grafana to load new binary
docker compose restart grafanaTesting:
# Frontend unit tests
npm test
# Backend tests
go test ./pkg/...
# E2E tests (requires running server)
npm run e2eLinting:
npm run lint
npm run lint:fixFor detailed development documentation, see AGENTS.md.
Configure the plugin in Configuration → Plugins → Ask O11y → Configuration:
- System Prompts: Customize AI behavior (default/replace/append modes)
- MCP Servers: Add servers with name, URL, and transport type
- Health Monitoring: Automatic health checks every 30 seconds
For self-hosted deployments, see .env.example for environment variables.
We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or enhancing UI/UX, your help is appreciated.
Want to contribute? Please read our Contributing Guide for:
- Development setup and workflow
- Code standards and testing guidelines
- Pull request process
- Commit message conventions
Quick Start for Contributors:
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/ask-o11y-plugin.git
cd ask-o11y-plugin
# Install dependencies and build
npm install
npm run build
# Start development environment
npm run serverReporting Issues:
- Bug reports: GitHub Issues
- Security vulnerabilities: Use GitHub Security Advisory feature (private disclosure)
For detailed contribution guidelines, see CONTRIBUTING.md.
- Documentation: Start with this README and AGENTS.md
- Issues: Report bugs or request features on GitHub Issues
- Discussions: Join conversations on GitHub Discussions
Common Issues:
- "I don't see visualizations": Check datasource configuration and time range
- "Tool execution failed": Verify RBAC permissions and MCP server health
- "Session not loading": Ensure correct organization and localStorage is enabled
- "LLM plugin not found": Install and configure grafana-llm-app plugin
For detailed troubleshooting, see the Troubleshooting Guide.
Issue: After installation, plugin doesn't appear in Apps menu
Solutions:
- Verify plugin is in the correct directory:
ls -la /var/lib/grafana/plugins/consensys-asko11y-app/
- Check Grafana logs for errors:
tail -f /var/log/grafana/grafana.log
- Ensure plugin signature is valid (for signed plugins):
grafana-cli plugins ls
- Restart Grafana after installation
- Clear browser cache and hard reload (Cmd/Ctrl + Shift + R)
Issue: Chat interface loads but doesn't respond to queries
Solutions:
- Verify Grafana LLM plugin is installed and enabled
- Check LLM API key is configured correctly in Grafana LLM settings
- Verify API key has sufficient quota/credits
- Check browser console for errors (F12 → Console tab)
- Ensure network connectivity to LLM provider (OpenAI, Anthropic, etc.)
Issue: "MCP server unavailable" or connection timeout errors
Solutions:
- Verify MCP server URL is accessible from Grafana:
curl http://mcp-grafana:8000/mcp/health
- Check MCP server is running:
docker ps | grep mcp-grafana - Verify network connectivity between Grafana and MCP server
- Check MCP server logs for errors
- Ensure correct transport type is selected (streamable-http, stdio, etc.)
Issue: Query executes but chart doesn't render
Solutions:
- Check query returned data (view raw response in browser console)
- Try switching visualization type (Time Series → Table → Stat)
- Verify time range includes data
- Check datasource permissions (user must have query access)
- Ensure datasource is healthy (test in Grafana Explore)
Issue: "Insufficient permissions" or "Access denied" errors
Solutions:
- Verify user role:
- Admin/Editor: Full access (56 tools)
- Viewer: Read-only access (45 tools)
- Check datasource permissions in Grafana settings
- Ensure organization context is correct
- Review Grafana RBAC policies if using Enterprise
Issue: Plugin fails to build or run in development
Solutions:
- Verify Node.js version:
node --version(requires >= 22) - Verify Go version:
go version(requires >= 1.23) - Clear and reinstall dependencies:
rm -rf node_modules package-lock.json dist npm install npm run build
- Check for port conflicts (dev server uses port 3000)
- Ensure Mage is installed:
go install github.com/magefile/mage@latest
If you're still experiencing issues:
- Search Existing Issues: Check GitHub Issues for similar problems
- Enable Debug Logging: Set
GF_LOG_LEVEL=debugin Grafana config - Collect Information:
- Grafana version
- Plugin version
- Browser and OS
- Error messages from browser console and Grafana logs
- Open an Issue: Create a new issue with details
- GitHub Issues: Report bugs and request features
- GitHub Discussions: Ask questions and share ideas
- Contributing: See CONTRIBUTING.md for how to contribute
- User Guide: src/README.md - Comprehensive feature documentation
- Developer Guide: AGENTS.md - Architecture and development patterns
- API Reference: Grafana Plugin Documentation
- MCP Protocol: Model Context Protocol Specification
Found a security vulnerability? Please do not open a public issue. Instead:
- Email: [email protected]
- See: CONTRIBUTING.md - Security for our security policy
Licensed under the MIT License - see the LICENSE file for details.
Built with Grafana, Model Context Protocol, React, TypeScript, and Go.
- CONTRIBUTING.md: Contribution guidelines, development setup, and PR process
- AGENTS.md: Comprehensive developer guide with architecture patterns
- src/README.md: Detailed feature documentation and user guide
- CHANGELOG.md: Version history and release notes
- .env.example: Environment variable configuration template
- Grafana Plugin Development: Official Grafana documentation
Made with ❤️ by the Consensys Observability Team
Got questions or feedback? We'd love to hear from you! Open an issue, join our community, or contribute to make Ask O11y even better.