Authelia 遥测参考指南：Prometheus 指标的配置、指标清单与 Grafana 可视化

Authelia 遥测参考指南Prometheus 指标的配置、指标清单与 Grafana 可视化【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本文基于 Authelia 官方遥测参考文档系统讲解 Authelia 的遥测体系如何启用独立的 Prometheus 指标服务端默认监听tcp://:9959/metrics、完整解读全部计数器与直方图指标及其向量标签、配置各参数地址、缓冲区、超时并配合官方示例将指标接入 Prometheus 与 Grafana。读完本文你既能完成一套可落地的监控采集配置也能从源码层面理解每个指标是如何被记录与打标的。需要首先明确的基调是Authelia 的任何二进制或工具默认不收集任何遥测数据所有遥测数据仅供各部署实例的管理员用于监控自己的 Authelia 服务不存在任何形式的默认外发或第三方上报。Prometheus 指标导出机制Authelia 支持导出 Prometheus 格式指标。指标不在主业务端口上提供而是当telemetry.metrics.enabled开启后由一个独立的监听器在配置的路径上提供默认即为 Prometheus 官方已注册的:9959端口、/metrics路径。这一设计在配置 schema 中有明确定义。从 telemetry.go 可以看到遥测配置的完整结构// Telemetry represents the telemetry config. type Telemetry struct { Metrics TelemetryMetrics koanf:metrics yaml:metrics,omitempty ... } // TelemetryMetrics represents the telemetry metrics config. type TelemetryMetrics struct { Enabled bool ... jsonschema:defaultfalse,titleEnabled jsonschema_description:Enables the metrics server. Address *AddressTCP ... jsonschema:defaulttcp://:9959/,titleAddress ... Buffers ServerBuffers ... Timeouts ServerTimeouts ... }要点enabled默认为false即指标服务默认关闭address默认值为tcp://:9959/metrics见DefaultTelemetryConfigtelemetry.go与文档所述官方已注册端口 9959一致buffers与timeouts分别控制指标 HTTP 服务端的读写缓冲区和超时默认为读写缓冲各4096字节读/写超时6s、空闲超时30s。配置示例仓库根目录的 config.template.yml 给出了telemetry段的完整官方模板# telemetry: ## ## Metrics Configuration ## # metrics: ## Enable Metrics. # enabled: false ## The address for the Metrics server to listen on in the address common syntax. ## Formats: ## - [scheme://]hostname[:port][/path] ## - [scheme://][hostname]:port[/path] ## Square brackets indicate optional portions of the format. Scheme must be tcp, tcp4, ## tcp6, unix, or fd. The default scheme is unix if the address is an absolute path ## otherwise its tcp. The default port is 9959. ## If the path is not specified it defaults to /metrics. # address: tcp://:9959/metrics ## Metrics Server Buffers configuration. # buffers: ## Read buffer. # read: 4096 ## Write buffer. # write: 4096 ## Metrics Server Timeouts configuration. # timeouts: ## Read timeout in the duration common syntax. # read: 6 seconds ## Write timeout in the duration common syntax. # write: 6 seconds ## Idle timeout in the duration common syntax. # idle: 30 seconds一个最小的启用配置即telemetry: metrics: enabled: true地址语法与默认值补全逻辑address采用 Authelia 通用地址语法[scheme://]hostname[:port][/path]合法 scheme 为tcp、tcp4、tcp6、unix、fd未写 scheme 且地址是绝对路径时默认为unix否则为tcp。ValidateTelemetry 在校验阶段负责补全默认值Address为 nil 时回落到tcp://:9959/metrics端口为 0 时补为 9959路径为空时补为/metricsbuffers.read/buffers.write非正数时补为 4096三项超时非正值时分别补为 6s、6s、30s。也就是说只要写enabled: true即使完全不写address指标服务也会按:9959/metrics启动。指标记录的实现链路指标本身在 internal/metrics/prometheus.go 中实现。NewPrometheus()创建独立的prometheus.Registry并在register()prometheus.go中注册collectors.NewProcessCollectorprocess_*进程指标与collectors.NewGoCollectorgo_*Go 运行时指标因此/metrics输出中还包含这两组基础指标以Subsystem: authelia注册 5 个CounterVec和 3 个HistogramVec即实际暴露的指标名为authelia_request_total、authelia_authz_total、authelia_authn_total、authelia_authn_passkey_total、authelia_authn_second_factor_total、authelia_authn_duration_seconds_*、authelia_request_duration_seconds_*、authelia_request_duration_openid_connect_seconds_*。埋点通过 fasthttp 中间件完成internal/middlewares/metrics.goNewMetricsRequestmetrics.go在请求处理前后计时以 HTTP 状态码、请求方法与耗时记录request计数器与request_duration直方图NewMetricsRequestOpenIDConnectmetrics.go为 OpenID Connect 端点单独记录request_duration_openid_connect直方图注意其会先把端点名中的-替换为_以符合指标标签命名NewMetricsAuthzRequestmetrics.go为授权authz校验请求记录authz计数器。认证类指标则由限频/封禁调节器触发regulator.go 中调用ctx.RecordAuthn(successful, banned, strings.ToLower(authType))最终进入 RecordAuthn 的分发逻辑func (r *Prometheus) RecordAuthn(success, banned bool, authType string) { switch authType { case 1fa, : r.authnCounter.WithLabelValues(strconv.FormatBool(success), strconv.FormatBool(banned)).Inc() case passkey: r.authnPasskeyCounter.WithLabelValues(strconv.FormatBool(success)).Inc() default: r.authn2FACounter.WithLabelValues(strconv.FormatBool(success), strconv.FormatBool(banned), authType).Inc() } }这解释了指标文档中的表结构1fa密码等第一因子认证计入authnpasskey计入authn_passkey其余webauthn、totp、duo等第二因子计入authn_second_factor并带上type标签。已记录的指标清单向量计数器Vectored Counters名称向量标签说明requestcode,method全部 HTTP 请求authzcode授权Authz请求authnsuccess,banned认证请求1FA第一因子authn_passkeysuccess认证请求Passkeyauthn_second_factorsuccess,banned,type认证请求2FA第二因子向量直方图Vectored Histograms名称向量标签桶Buckets单位秒authn_durationsuccess.0005, .00075, .001, .005, .01, .025, .05, .075, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.8, 0.9, 1, 5, 10, 15, 30, 60request_durationcode.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10, 15, 20, 30, 40, 50, 60request_duration_openid_connectendpoint,code.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10, 15, 20, 30, 40, 50, 60authn_duration的桶从 0.5ms 起步明显是为捕捉认证路径上毫秒级的性能差异而设计而请求类直方图从 5ms 起步更关注整体处理耗时。两个直方图的桶设置与 prometheus.go 中HistogramOpts.Buckets的定义完全一致。向量标签定义codeHTTP 响应状态码。methodHTTP 请求方法GET、POST 等。success认证是否成功true/false。banned该认证是否被判定为bannedtrue/false。这一标签来自 Authelia 的认证调节regulation机制——当认证触发封禁/限频策略时banned为true可用于监控暴力破解或异常登录行为。type第二因子认证类型取值为webauthn、totp或duo。endpointOpenID Connect 端点名取值为consentauthorizationpushed_authorization_requesttokenuserinforevocationintrospectionopenid_configurationoauth_configurationjwksPrometheus 抓取配置示例在 Prometheus 中为 Authelia 添加如下抓取任务即可文档原示例中authelia占位符需替换为你 Authelia 容器或主机的 URL/IP# Authelia - job_name: authelia scrape_interval: 15s scheme: http static_configs: - targets: [authelia:9959]由于指标端口独立于业务端口暴露给 Prometheus 抓取器时只需放通 9959 端口上的/metrics路径无需暴露 Authelia 的会话/登录端口这缩小了攻击面。在 Grafana 中展示指标Prometheus 采集到的指标可以通过新建仪表盘或导入已有仪表盘在 Grafana 中展示与分析。Authelia 官方提供了一个社区维护的 Grafana 仪表盘目的在于演示如何探索上述可用指标。仓库内直接附带了该仪表盘的 JSON 文件simple.json。在 Grafana 中新建 Dashboard 时选择 Import将上述 JSON 内容粘贴或上传即可导入随后把数据源指向你的 Prometheus 实例即可开始分析 Authelia 的请求量、认证成功率、banned 事件与端点延迟等指标。小结Authelia 遥测遵循默认关闭、仅服务本地管理员的原则telemetry.metrics.enabled: true是唯一的启用开关指标服务独立监听tcp://:9959/metrics可自定义地址/端口/路径缓冲区与超时均可调其默认值补全逻辑见 validator/telemetry.go共 8 个业务指标5 计数器 3 直方图覆盖请求、授权、第一/第二因子认证三大维度另附go_*与process_*运行时指标接入链路为中间件/调节器埋点 → Prometheus 独立 Registry → 9959 端口/metrics→ Prometheus 抓取 → Grafana 仪表盘相关实现分别位于 internal/middlewares/metrics.go、internal/metrics/prometheus.go 与 internal/regulation/regulator.go。参考文档官方 Telemetry 参考指南。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考