Telegraf GitHub 输入插件inputs.github完全指南采集仓库指标与 API 限流监控【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本文围绕 Telegraf 官方 GitHub 输入插件展开讲解如何通过 GitHub REST API 周期性采集指定仓库的 Star、Fork、Issue、Watch 等元数据指标并配套说明访问令牌配置、Enterprise 私有化部署支持、附加字段扩展以及基于internal插件的 API 限流自监控方案。读完本文你将掌握[[inputs.github]]的完整配置方法、输出指标结构以及从源码层面理解其并发采集与令牌脱敏实现并能在 Telegraf 与 webhook 两种采集方案之间做出合理选型。插件概览与适用场景inputs.github是 Telegraf 自带的官方输入插件仓库版本为 Telegraf v1.11.0 引入用于从 GitHub 托管的项目与仓库中采集公开的元数据信息。它面向的是按固定间隔主动拉取的模式Telegraf 代理在每个采集周期内调用 GitHub API读取每个配置仓库的基本信息并写入github_repository测量。该插件与 webhook 方案形成互补。原文档明确指出Telegraf 同样提供了 webhook 输入插件 作为收集仓库信息的替代途径。两者的差异在于维度inputs.github轮询webhooks/github推送数据获取方式主动调用 GitHub API接收 GitHub 推送的 webhook 事件触发时机按采集间隔周期性执行仓库事件发生时实时触发网络方向Telegraf 出站访问 APIGitHub 入站回调 Telegraf典型场景定期快照仓库状态、趋势分析实时响应 commit、issue 等事件你可以在 webhook 文档 中查看其事件类型与指标结构下文聚焦轮询方案的inputs.github。安装与插件注册在默认构建的 Telegraf 中该插件已包含在全部输入插件集合中注册入口位于 plugins/inputs/all/github.go其构建标签为//go:build !custom || inputs || inputs.github import _ github.com/influxdata/telegraf/plugins/inputs/github // register plugin这意味着默认编译时插件自动注册若使用自定义构建custom builder参见 docs/CUSTOMIZATION.md只需保留inputs.github标签即可。插件的实际注册逻辑在 github.go 的init()函数中完成func init() { inputs.Add(github, func() telegraf.Input { return GitHub{ HTTPTimeout: config.Duration(time.Second * 5), } }) }从源码可见插件结构体GitHub由 TOML 反序列化填充且http_timeout的默认值为 5 秒。完整配置与参数详解原文档给出的配置示例与仓库内 sample.conf 完全一致如下# Gather repository information from GitHub hosted repositories. [[inputs.github]] ## List of repositories to monitor repositories [ influxdata/telegraf, influxdata/influxdb ] ## Github API access token. Unauthenticated requests are limited to 60 per hour. # access_token ## Github API enterprise url. Github Enterprise accounts must specify their base url. # enterprise_base_url ## Timeout for HTTP requests. # http_timeout 5s ## List of additional fields to query. ## NOTE: Getting those fields might involve issuing additional API-calls, so please ## make sure you do not exceed the rate-limit of GitHub. ## ## Available fields are: ## - pull-requests -- number of open and closed pull requests (2 API-calls per repository) # additional_fields []各配置项的语义与源码对应关系如下repositories必需需要监控的仓库列表元素格式为owner/repository例如influxdata/telegraf。在 github.go 中由splitRepositoryName()负责解析按第一个/拆分为 owner 与 repository 两部分若不存在/则报错xxx is not of format owner/repository。这一点已被单元测试验证见 github_test.goinfluxdata/telegraf、rawkode/saltstack-dotfiles属于合法输入而influxdata-influxdb会被拒绝。access_token可选GitHub API 访问令牌。未认证请求的速率限制为每小时 60 次而携带令牌后个人访问令牌PAT的配额会显著提高。如果同时监控多个仓库或开启了additional_fields会额外消耗 API 调用强烈建议配置令牌以避免限流。源码层面令牌通过oauth2.StaticTokenSource注入 HTTP 客户端见createGitHubClient()并做脱敏处理——仅保留前 4 个字符与后 3 个字符中间以...代替例如abcd...xyz随后作为internal_github指标的access_token标签值未配置令牌时该标签固定为Unauthenticated。enterprise_base_url可选GitHub Enterprise 私有化部署的 API 基础地址。配置后newGithubClient()会调用github.NewEnterpriseClient(baseURL, , httpClient)指向企业实例而非公共的api.github.com。对应的测试github_test.go 中的TestNewGithubClient验证了默认客户端 BaseURL 包含api.github.com而设置EnterpriseBaseURL api.example.com/后 BaseURL 变为企业地址。注意GitHub Enterprise 账户必须指定该参数公共 GitHub 用户无需设置。http_timeout可选HTTP 请求超时时间默认5sGo 的time.Duration类型支持5s、1m等格式。该值直接作用于底层http.Client.Timeout。additional_fields可选需要额外查询的字段列表当前支持pull-requests统计每个仓库的开放与已关闭 Pull Request 数量每个仓库消耗 2 次 API 调用分别搜索 open 与 closed 状态的 PR。原文档特别提醒这些附加字段可能产生额外 API 调用务必确认不会超出 GitHub 的限流配额。源码中通过 GitHub Search API 实现Search.Issues查询条件repo:owner/repo is:pr is:open|closed每类状态一次请求结果写入open_pull_requests与closed_pull_requests两个字段。未知的字段名会在运行期返回错误unknown additional field xxx。全局配置与其他插件一致inputs.github也支持 Telegraf 的全局与插件级通用配置例如name_prefix、tags、fieldpass、interval等指标修饰选项详见 docs/CONFIGURATION.md。输出指标详解插件在每个采集周期为每个仓库输出一条github_repository测量指标结构如下github_repositorytags标签name仓库名称owner仓库所有者language仓库主要编程语言license仓库设置的许可证未设置时返回Nonefields字段均为 intforksFork 数量open_issues开放 Issue 数量networks网络数仓库被 Fork 的网络数size仓库大小KBsubscribers订阅Watch用户数starsStar 数量watchersWatch 数量字段映射在 github.go 的getFields()中直接对应 go-github 的Repository结构体方法GetStargazersCount()、GetForksCount()等。许可证在getLicense()中处理当仓库无许可证信息时返回字符串None这一行为同样有单元测试覆盖TestGetLicenseWhenMissing。当启用additional_fields [pull-requests]时额外输出open_pull_requests(int)开放的 PR 数量closed_pull_requests(int)已关闭的 PR 数量限流自监控internal_github 指标插件会利用 Telegraf 的selfstat机制记录 GitHub API 的限流状态。当同时启用 internal 输入插件[[inputs.internal]]时即可看到internal_github测量internal_githubtagsaccess_token脱敏后的令牌引用或Unauthenticatedfieldslimit每小时请求配额上限remaining本小时剩余请求数blocks因限流被阻止的请求次数其实现位于Gather()首次初始化客户端时通过selfstat.Register(github, rate_limit_blocks, tokenTags)等注册三个统计量每次 API 响应后handleRateLimit()从github.Response.Rate更新limit与remaining当错误类型为*github.RateLimitError时对rate_limit_blocks累加 1。internal 插件默认per_instance false即按插件类型聚合统计如需按实例区分可参考 internal 示例配置 设置per_instance true。源码层面的采集流程从 github.go 可以看出整个采集采用并发模型首次采集时创建 go-github 客户端createGitHubClient()并注册限流自监控统计量对repositories列表中的每个仓库启动一个 goroutinesync.WaitGroup管理并行执行每个 goroutine 先解析owner/repository然后调用githubClient.Repositories.Get()获取仓库信息并调用handleRateLimit()记录限流状态组装 tags 与 fields 后若有additional_fields则逐项查询PR 统计走 Search API通过acc.AddFields(github_repository, fields, tags, now)写入指标wg.Wait()等待全部仓库采集完成。值得注意的是 HTTP 客户端显式设置了Transport.Proxy http.ProxyFromEnvironment即尊重环境变量中的代理配置这对受限网络环境下的采集很有帮助。示例输出与查询实践原文档提供的输出示例时间戳为纳秒级github_repository,languageGo,licenseMIT\ License,nametelegraf,ownerinfluxdata forks2679i,networks2679i,open_issues794i,size23263i,stars7091i,subscribers316i,watchers7091i 1563901372000000000 internal_github,access_tokenUnauthenticated closed_pull_requests3522i,rate_limit_remaining59i,rate_limit_limit60i,rate_limit_blocks0i,open_pull_requests260i 1552653551000000000对应的 InfluxQL 查询示例接入 InfluxDB 输出时-- 各仓库 Star 数随时间变化 SELECT last(stars) FROM github_repository GROUP BY owner,name TIME(1h) -- 当前 API 剩余配额 SELECT last(remaining) FROM internal_github WHERE access_token Unauthenticated -- 限流被阻止次数 SELECT last(blocks) FROM internal_github常见问题与最佳实践避免限流未认证配额仅 60 次/小时监控超过 60 个仓库时即会触发建议为access_token配置具备repo私有仓库或public_repo只读权限的令牌并将internal插件纳入采集以实时观察remaining。PR 统计成本每启用一个pull-requests附加字段每个仓库每周期多消耗 2 次 API 调用注意控制仓库数量与配额。Enterprise 环境私有化部署必须设置enterprise_base_url否则客户端仍会指向公共 API 端点。网络代理插件尊重HTTP_PROXY/HTTPS_PROXY环境变量可结合部署环境设置。与 webhook 选型若对实时性要求高且能暴露接收端口优先考虑 webhooks/github若需要周期性快照与历史趋势inputs.github更合适二者也可并存。延伸阅读插件配置文档全局选项与指标修饰inputs.github 源码实现inputs.github 单元测试插件示例配置internal 插件插件自监控指标webhook 输入插件GitHub 事件推送替代方案【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考