CodexBar 接入 GroqCloud 用量统计：GroqCloud Provider 与 Enterprise Prometheus 指标 API 实战指南-平芜编程栈

CodexBar 接入 GroqCloud 用量统计：GroqCloud Provider 与 Enterprise Prometheus 指标 API 实战指南

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar

CodexBar 将 GroqCloud 作为独立的用量统计数据源接入，通过 GroqCloud API Key 与 Groq 的 Enterprise Prometheus 指标 API 获取请求、Token 与缓存命中速率，并在菜单栏中以每分钟速率的形式呈现。本指南完整介绍配置方法、菜单显示语义、底层 Prometheus 查询实现与错误处理机制，阅读后你可以在本地为 CodexBar 配置 GroqCloud 统计、理解速率指标的计算来源，并快速排查权限与数据缺失问题。

GroqCloud Provider 在 CodexBar 中的定位

GroqCloud Provider 与 xAI 的 Grok Provider 是完全独立的两个数据源，这一点在官方文档 docs/groqcloud.md 中明确说明：GroqCloud 使用GroqCloud API Key和Enterprise Prometheus 指标 API获取用量数据，而 Grok 走的是另一套 xAI 认证与接口体系。

从源码可以印证这一设计：在 ProviderManifest.swift 中，Groq Provider 的 descriptor 通过GroqProviderDescriptor.descriptor注册；而 GroqProviderDescriptor.swift 中 CLI 名称为groqcloud，并带有groq、groq-api两个别名。也就是说：

在 CodexBar 设置界面中，该 Provider 显示为Groq，切换标题为 "Show Groq usage"；
在 CLI 与配置层面，它的标识是groqcloud（别名groq）；
默认处于关闭状态（defaultEnabled: false），需要显式启用。

配置 GroqCloud API Key

GroqCloud 的密钥存储在 CodexBar 共享的应用/CLI 配置中，官方文档给出了两种配置方式。

方式一：通过 CLI 写入共享配置

printf '%s' "$GROQ_API_KEY" | codexbar config set-api-key --provider groq --stdin

这条命令将GROQ_API_KEY环境变量的值通过标准输入写入 CodexBar 解析出的配置文件（默认位于~/.codexbar/config.json），同时默认启用该 Provider。命令的完整形态可从 CLIHelp.swift 中看到，它支持：

codexbar config set-api-key --provider <name> (--api-key <key>|--stdin) [--label <label>] [--usage-scope team] [--organization-id <org>] [--workspace-id <project>] [--no-enable]

其中--provider参数接受 provider 名称，Groq 对应的名称就是 descriptor 中定义的groqcloud（别名groq，因此--provider groq也可用）。需要留意的是set-api-key默认会启用该 Provider；若只想存储密钥而不启用，可追加--no-enable。存储后的密钥还会以 Token Account 的形式支持多密钥管理，相关能力定义在 GroqProviderDescriptor.swift 的ProviderCredentialAdapter.apiKey中（标题 "API keys"、通过环境变量注入）。

方式二：进程环境变量

直接设置GROQ_API_KEY环境变量即可，CodexBar 会通过GroqSettingsReader读取。相关的环境变量键在 GroqSettingsReader.swift 中定义：

环境变量	作用	默认值
`GROQ_API_KEY`	GroqCloud API Key	无（缺失时报`missingCredentials`）
`GROQ_API_URL`	覆盖 API 基础地址	`https://api.groq.com/v1`

其中GROQ_API_URL用于接入私有网关（private gateway）或自建代理。值得注意的校验细节是：GroqSettingsReader.validateEndpointOverrides会调用ProviderEndpointOverrideValidator.normalizedHTTPSURL校验该覆盖值，必须是 HTTPS URL 或裸主机名，否则会抛出invalidEndpointOverride错误（"Groq endpoint override GROQ_API_URL must use HTTPS or a bare host."）。读取时还会自动去掉首尾空白与成对的引号包裹（见cleaned方法），避免复制密钥时带入多余字符。

菜单栏显示指标与语义

启用并配置完成后，GroqCloud 的用量会显示在菜单栏，官方文档定义的显示层级为：

Primary（主指标）：每分钟请求数（requests per minute）；
Secondary（次级指标）：每分钟 Token 数（tokens per minute）；
Tertiary（第三指标）：每分钟 Prompt 缓存命中数（prompt cache hits per minute），仅当该指标存在时才显示；
Dashboard 链接：跳转到 GroqCloud 指标面板（https://console.groq.com/dashboard/usage）。

这套语义在源码 GroqUsageFetcher.swift 的GroqUsageSnapshot中有完整对应实现：

public var requestsPerMinute: Double { self.requestRatePerSecond * 60 } public var tokensPerMinute: Double { (self.inputTokenRatePerSecond + self.outputTokenRatePerSecond) * 60 } public var cacheHitsPerMinute: Double { self.promptCacheHitRatePerSecond * 60 }

在toUsageSnapshot()中：

primary填充requestsPerMinute，描述文本为"X req/min"；
secondary填充tokensPerMinute，描述文本为"X tok/min"；
tertiary仅在promptCacheHitRatePerSecond > 0时生成，描述文本为"X cache/min"，否则为nil——这正对应文档中"当该指标存在时"的表述；
窗口固定为 5 分钟（windowMinutes: 5），因为底层 PromQL 查询使用的就是rate5m（5 分钟速率）；
登录方式标记为 "Prometheus metrics"。

数值的显示格式也做了分级处理（formatDecimal）：大于等于 100 显示整数、10 到 100 之间显示 1 位小数、小于 10 显示 2 位小数，保证菜单栏在窄宽度下也能清晰可读。

底层实现：Prometheus 指标查询

GroqCloud Provider 的用量并非猜测或从无关接口拼凑而来，而是直接查询 Groq 的 Enterprise Prometheus 指标 API。核心实现在 GroqUsageFetcher.swift 的fetchUsage中，其请求流程如下：

校验 API Key 非空，否则抛出missingCredentials；
校验GROQ_API_URL覆盖值合法；
基于GroqSettingsReader.apiURL（默认https://api.groq.com/v1）拼接出{base}/metrics/prometheus端点；
并发执行 4 个 PromQL 查询（每条独立请求{base}/metrics/prometheus/api/v1/query）：

查询	对应指标
`sum(model_project_id_status_code:requests:rate5m)`	请求速率
`sum(model_project_id:tokens_in:rate5m)`	输入 Token 速率
`sum(model_project_id:tokens_out:rate5m)`	输出 Token 速率
`sum(model_project_id:prompt_cache_hits:rate5m)`	Prompt 缓存命中速率

每个请求使用Authorization: Bearer <API Key>认证、Accept: application/json头，通过共享的ProviderHTTPClient传输层发出。

Prometheus 返回的标量解析逻辑（parseScalar）值得单独说明：CodexBar 解析响应中status == "success"的data.result序列，取每个序列value数组的最后一个数值元素并求和（compactMap+reduce(0, +)）。由于value数组中时间戳为字符串、数值为数字，解码器实现了PrometheusValue枚举同时兼容数字与字符串两种类型，保证容错。

请求过程使用 Swift 并发（async let）同时发起 4 个查询，避免串行等待拖慢刷新；超时与错误信息则通过responseSummary截取响应前 500 字节作为诊断摘要。

错误处理与排障

官方文档特别强调：如果 API Key 缺少 Prometheus 指标访问权限，CodexBar 会直接展示 API 返回的错误，而不是从无关端点猜测数据。这与源码中的错误分类设计一致，GroqUsageError（见 GroqUsageFetcher.swift）定义了 5 类错误：

错误类型	触发条件
`missingCredentials`	API Key 缺失（提示设置`apiKey`于`~/.codexbar/config.json`或`GROQ_API_KEY`）
`invalidURL`	Prometheus 指标 URL 构造失败
`accessDenied`	HTTP 401/403，说明密钥无指标访问权限
`apiError`	其他非 2xx 响应，附带 HTTP 状态码与响应摘要
`parseFailed`	响应 JSON 解析失败或`status != "success"`

从 fetch 管道角度看（GroqProviderImplementation.swift），Prometheus 密钥路径的 strategy ID 为groq.api，source label 为metrics；当密钥缺失时抛出missingCredentials。普通 GroqCloud 密钥（未开通 Enterprise Prometheus）在此接口上通常会得到 404 之类的响应，CodexBar 不会据此伪造零数据，而是如实呈现错误或空数据，方便你区分"没数据"与"权限不足"两种情况。

需要补充的背景是：从源码结构看，Groq 数据源实际存在两条路径——文档所述的 API Key + Prometheus 是其中一条（groq.api）；另一条是读取浏览器中console.groq.com会话 Cookie（stytch_session/stytch_session_jwt）走控制台平台 API 的groq.console路径（相关实现见 GroqConsoleSession.swift 与 GroqConsoleFetcher.swift），fetch 计划按auto模式先尝试控制台会话、再回退到 Prometheus 密钥路径。这与文档强调的"API Key 可选、仅用于 Enterprise Prometheus 指标"保持一致——设置界面的 API Key 字段副标题也写明：用量与消费来自console.groq.com浏览器会话自动获取，API Key 为可选项，只用于补充 Enterprise Prometheus 指标。

常见问题与排查要点

菜单栏不显示任何指标：确认 API Key 已写入配置（codexbar config dump可查看归一化配置，默认脱敏）或已设置GROQ_API_KEY；确认 Provider 已启用（codexbar config providers可查看持久化启用状态，codexbar config enable --provider groq可启用）。
显示权限错误（accessDenied）：401/403 表示该 Key 未开通 Enterprise Prometheus 指标访问，需要在 GroqCloud 侧确认组织/密钥权限，而非更换显示来源。
Tertiary 缓存指标不显示：这是预期行为——仅当prompt_cache_hits查询返回非零速率时才会渲染第三行。
私有网关接入：通过GROQ_API_URL覆盖基础地址，注意其必须为 HTTPS URL 或裸主机名，且端点需兼容 Groq 的/metrics/prometheus/api/v1/query路径结构。