Hermetiq Documentation

Everything you need to set up, configure, and get the most out of Hermetiq's build intelligence platform for Bazel.

What is Hermetiq?

Hermetiq is a cloud-native build intelligence platform purpose-built for Bazel. It ingests telemetry from multiple data sources across your build infrastructure and transforms it into actionable insights — so you can fix cache misses, lower costs, and build faster.

What makes Hermetiq unique is its MCP server, which connects your build data directly to AI assistants like Claude, Cursor, Windsurf, and other MCP-capable tools. Ask questions about your builds in natural language and get instant, data-driven answers.

Real-Time Build Intelligence

Live monitoring, historical trends, and team-wide performance insights.

Deep Observability

Multiple data source integration, cache analytics, cost tracking, and anomaly detection.

Root Cause Analysis

Automatically identify why cache misses occur and get actionable fixes.

✓
Teams typically see results within the first build. Configure your data sources, run bazel build //..., and start exploring your data immediately.

Data Sources

Hermetiq ingests telemetry from multiple sources across your build infrastructure to give you a complete picture of build performance, cost, and reliability.

Build Event Protocol (BEP)

Bazel's native Build Event Protocol streams detailed build events — targets, actions, test results, timing data, and more — directly to Hermetiq in real time.

Remote Cache Data

Cache hit/miss data, eviction patterns, and storage utilization from your remote cache layer, giving you insight into cache efficiency and optimization opportunities.

Buildbarn Completed Action Logs

Detailed action execution data from Buildbarn workers — including execution times, queue wait times, I/O metrics, and worker resource utilization.

OpenTelemetry Traces

End-to-end distributed traces that follow a build from Bazel invocation through worker execution, enabling full-stack performance debugging.

Cost Data

Cloud infrastructure cost data via OpenCost integration, enabling per-build and per-target cost attribution so you know exactly where money is being spent.

Infrastructure Metrics

System-level metrics from your build cluster — CPU, memory, disk, and network utilization — correlated with build events for holistic observability.

i
Your project's Quickstart page provides the specific configuration for each source after you sign up and log in.

Getting Started

Setting up Hermetiq takes just a few minutes. Follow these three steps to start streaming build telemetry to the platform.

1

Create Your Account & Project

Sign up for Hermetiq and create your first project. Once logged in, your project's Quickstart page will provide all the configuration values, endpoints, and credentials you need — tailored to your specific project.

2

Configure Your Builds

Follow the step-by-step instructions in the Quickstart page to set up your data sources. This involves downloading a credential helper for secure authentication, adding flags to your .bazelrc file, and optionally configuring OpenTelemetry and remote cache integration.

i
All configuration values — endpoints, project IDs, and credential paths — are provided in your Quickstart page after you log in.
3

Run Builds & Explore

Run any Bazel build command and your telemetry will automatically stream to Hermetiq. Navigate to your dashboard to view build results, cache analytics, cost data, and performance metrics.

Core Features

Hermetiq provides a comprehensive suite of tools for understanding and optimizing your Bazel builds.

Build History

Every build is automatically logged and searchable. Quickly find past builds, compare results, and understand what changed between successful and failed builds.

  • Searchable build archive
  • Filter by dozens of criteria
  • Detailed build metadata and logs
  • One-click drill-down into failures

Analytics & Trends

Track your build performance over time with comprehensive trend analysis. Spot regressions early and measure the impact of your optimizations.

  • Historical build performance tracking
  • Trend visualization and charts
  • Regression detection
  • Team-wide performance metrics

Cache Analytics

Deep insights into your cache performance across all builds. Understand cache hit rates, identify patterns, and optimize your caching strategy.

  • Cache hit rate by action type (CppCompile, GenProto, etc.)
  • Miss reason breakdown (input changes, command changes, evictions)
  • Daily trend heatmaps
  • Target-level cache analysis

Build Comparison

Compare any two builds side-by-side to understand exactly what changed. Perfect for validating optimizations or investigating regressions.

  • Side-by-side invocation diffing
  • Action-level diff analysis
  • Performance delta tracking
  • Visual change highlighting

Cost Reporting

Real-time visibility into the cost of your builds. Understand where compute time and money are being spent across your build infrastructure.

  • Per-build and per-target cost estimates
  • OpenCost integration for cloud cost attribution
  • Resource utilization tracking
  • Cost trend analysis over time

Critical Path Analysis

Identify the longest chain of sequential actions in your build graph. Focus optimization efforts where they will have the biggest impact.

  • Automatic critical path identification
  • Action-level timing breakdown
  • Bottleneck detection
  • Optimization recommendations

Configuration Reference

Hermetiq is configured primarily through your .bazelrc file and environment variables. All configuration values specific to your project are available in the Quickstart page after you log in.

i
Log in to your Hermetiq dashboard to access your project's Quickstart page, which provides ready-to-copy configuration with your specific endpoints, project IDs, and credential paths.

BEP Configuration

The Build Event Protocol (BEP) is the primary mechanism for streaming build data to Hermetiq. Configuration involves setting your project ID, BEP backend endpoint, upload timeout, results URL, and upload mode in your .bazelrc.

Remote Cache

Hermetiq provides a managed remote cache powered by Buildbarn. Configuring the remote cache requires setting a remote instance name and cache endpoint in your .bazelrc.

Remote Execution

Hermetiq also supports managed remote build execution (RBE) powered by Buildbarn, available upon request. To enable remote execution for your project, submit a request through the form on your Quickstart page after logging in.

OpenTelemetry Integration

For end-to-end observability including worker execution traces, configure the OpenTelemetry exporter via environment variables pointing to Hermetiq's OTLP endpoint with mTLS authentication.

Build Metadata

Enrich your builds with metadata (commit SHA, repo, branch, role, etc) for better filtering and analysis. You can provide metadata via a workspace status script or command-line flags — both options are detailed in the. Quickstart page.

Action Profiling

Enable detailed action profiling via Bazel flags to get the most out of critical path analysis and performance debugging. This includes JSON trace profiles and target label annotations.

Technical Details

Supported Build Systems

Hermetiq is purpose-built for Bazel and ingests data from multiple sources including BEP, remote cache, Buildbarn action logs, OpenTelemetry traces, and cost metrics. Any Bazel version that supports BEP streaming is compatible.

Authentication

Hermetiq uses mutual TLS (mTLS) for all client-to-server communication. This provides strong authentication and encryption for your build data.

  • TLS/HSTS for all data in transit
  • Certificate-based client authentication
  • Credential helper script manages the TLS handshake

Infrastructure

  • Remote Cache & RBE: Powered by Buildbarn for high-performance content-addressable storage and remote execution
  • Event Streaming: NATS JetStream handles thousands of events per second
  • Storage: PostgreSQL for structured build data
  • Metrics: VictoriaMetrics for time-series data
  • Tracing: Grafana Tempo for distributed traces
  • API: gRPC for high-performance client communication

Architecture Overview

Hermetiq is cloud-hosted and connects to your Bazel builds via multiple data pipelines. The platform is designed for horizontal scalability and high availability.

Bazel + BuildbarnBEP, Cache, Actions, OTEL
→
Hermetiq IngestgRPC + NATS
→
Data LayerPostgres + VictoriaMetrics
→
Dashboard + MCPWeb UI + AI Integration

MCP Server & AI Integration

Hermetiq's Model Context Protocol (MCP) server connects your build data directly to AI assistants. Query your builds using natural language and get instant, data-driven answers.

Supported AI Assistants

Claude

Connect via Claude Desktop or the Claude API for build analysis with Anthropic's models.

Cursor

In-editor build insights directly within your development workflow.

MCP Clients

Use any MCP-capable assistant for build analysis and optimization suggestions.

Hermetiq AI Plugin

Give your AI agent deep Bazel expertise, backed by real build data from Hermetiq. This plugin adds a skill and MCP server that let Claude Code, Claude Desktop, or Codex analyze build performance, fix cache misses, optimize remote execution, and debug Buildbarn infrastructure using your project's actual metrics.

Diagnose Slow Builds

Find critical path bottlenecks, regressions, and parallelism gaps.

Fix Cache Misses

Pinpoint miss reasons and recommend targeted fixes.

Optimize Remote Execution

Reduce queue wait, right-size workers, and cut RBE costs.

Debug Infrastructure

Investigate Buildbarn storage, scheduler, and worker fleet health.

Audit Configuration

Review .bazelrc flags, hermeticity, and build graph patterns.

Track Trends

Compare performance across time periods, branches, and teams.

Repository: github.com/Hermetiq/hermetiq-ai-plugin

Available Prompts

The MCP server exposes these prompts that your AI assistant can call directly:

debug_cache_misses

Why did my build miss cache? Analyzes cache events to identify miss reasons.

analyze_build

Full build breakdown — invocation details, remote execution analytics, and parallelism.

investigate_failure

Why did this build fail? Inspects actions and remote execution logs to find the root cause.

project_health

Overall project health — build trends, cache trends, and remote action trends.

cost_analysis

Where's my budget going? Remote execution analytics, cache trends, and invocation history.

find_slow_builds

Which builds are slow? Surfaces the slowest invocations for investigation.

weekly_trends_report

Executive summary for the week — aggregated build and cache trends.

cache_trends

Cache performance deep dive over time.

rbe_trends

Remote build execution performance deep dive — action trends and timing.

compare_periods

Week-over-week comparison of build, cache, and execution trends.

API & Integrations

OpenTelemetry

Hermetiq integrates with the OpenTelemetry ecosystem for end-to-end observability. Traces flow from Bazel through Buildbarn workers into Hermetiq's tracing backend, giving you full visibility from build invocation to action execution.

Support

We're here to help you get the most out of Hermetiq. Reach out through any of these channels:

Email Support

Reach our engineering team directly at support@hermetiq.com

Slack Connect

Enterprise customers get a dedicated Slack channel with direct access to Hermetiq engineers.

Contact Us

Have questions or want a demo? Get in touch and we'll respond within 24 hours.

i
Need help getting set up? Schedule a call and we'll walk you through the integration process for your specific CI/CD setup.

Learn More