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/CodexBarCodexBar 将 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 KeyGroqCloud 的密钥存储在 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_KEYGroqCloud API Key无缺失时报missingCredentialsGROQ_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 minuteSecondary次级指标每分钟 Token 数tokens per minuteTertiary第三指标每分钟 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/minsecondary填充tokensPerMinute描述文本为X tok/mintertiary仅在promptCacheHitRatePerSecond 0时生成描述文本为X cache/min否则为nil——这正对应文档中当该指标存在时的表述窗口固定为 5 分钟windowMinutes: 5因为底层 PromQL 查询使用的就是rate5m5 分钟速率登录方式标记为 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数组的最后一个数值元素并求和compactMapreduce(0, )。由于value数组中时间戳为字符串、数值为数字解码器实现了PrometheusValue枚举同时兼容数字与字符串两种类型保证容错。请求过程使用 Swift 并发async let同时发起 4 个查询避免串行等待拖慢刷新超时与错误信息则通过responseSummary截取响应前 500 字节作为诊断摘要。错误处理与排障官方文档特别强调如果 API Key 缺少 Prometheus 指标访问权限CodexBar 会直接展示 API 返回的错误而不是从无关端点猜测数据。这与源码中的错误分类设计一致GroqUsageError见 GroqUsageFetcher.swift定义了 5 类错误错误类型触发条件missingCredentialsAPI Key 缺失提示设置apiKey于~/.codexbar/config.json或GROQ_API_KEYinvalidURLPrometheus 指标 URL 构造失败accessDeniedHTTP 401/403说明密钥无指标访问权限apiError其他非 2xx 响应附带 HTTP 状态码与响应摘要parseFailed响应 JSON 解析失败或status ! success从 fetch 管道角度看GroqProviderImplementation.swiftPrometheus 密钥路径的 strategy ID 为groq.apisource label 为metrics当密钥缺失时抛出missingCredentials。普通 GroqCloud 密钥未开通 Enterprise Prometheus在此接口上通常会得到 404 之类的响应CodexBar 不会据此伪造零数据而是如实呈现错误或空数据方便你区分没数据与权限不足两种情况。需要补充的背景是从源码结构看Groq 数据源实际存在两条路径——文档所述的 API Key Prometheus 是其中一条groq.api另一条是读取浏览器中console.groq.com会话 Cookiestytch_session/stytch_session_jwt走控制台平台 API 的groq.console路径相关实现见 GroqConsoleSession.swift 与 GroqConsoleFetcher.swiftfetch 计划按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可启用。显示权限错误accessDenied401/403 表示该 Key 未开通 Enterprise Prometheus 指标访问需要在 GroqCloud 侧确认组织/密钥权限而非更换显示来源。Tertiary 缓存指标不显示这是预期行为——仅当prompt_cache_hits查询返回非零速率时才会渲染第三行。私有网关接入通过GROQ_API_URL覆盖基础地址注意其必须为 HTTPS URL 或裸主机名且端点需兼容 Groq 的/metrics/prometheus/api/v1/query路径结构。延伸阅读本文涉及的核心实现与配置均可继续深入仓库官方文档入口docs/groqcloud.mdPrometheus 指标抓取与解析Sources/CodexBarCore/Providers/Groq/GroqUsageFetcher.swift环境变量与端点校验Sources/CodexBarCore/Providers/Groq/GroqSettingsReader.swiftProvider 注册与 fetch 策略编排Sources/CodexBar/Providers/Groq/GroqProviderImplementation.swiftCLIset-api-key用法Sources/CodexBarCLI/CLIHelp.swift控制台会话补充路径背景知识Sources/CodexBarCore/Providers/Groq/GroqConsoleSession.swift【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考