Merge pull request #15 from kodehat/feature/prometheus-metrics

feat: add Prometheus metrics

Author: kodehat

README.md

@@ -61,6 +61,7 @@
 - [Installation](#installation)
 - [Usage](#usage)
 - [Configuration](#configuration)
+- [Metrics](#metrics)
 - [Docker](#docker)
 - [Development](#development)
 - [See Also](#see-also)
@@ -122,9 +123,15 @@ logJson: false
 # Set the host where the application should bind to.
 host: localhost
 # Set the port where the application should bind to.
-port: 3000
+port: 1414
 # Set the context path (aka base-url) portkey is hosted under. Must not be specified unless you're using a reverse proxy and are hosting portkey under a directory. If that's the case then you can set this value to e.g. /portkey or whatever the directory is called. Note that the forward slash (/) in the beginning is required!
 contextPath: ""
+# Enables the HTTP server that serves metrics that can be scraped by e.g. Prometheus.
+enableMetrics: false
+# Set the host where the metrics server should bind to.
+metricsHost: localhost
+# Set the port where the metrics server should bind to.
+metricsPort: 1515
 ```
 
 ### Styling
@@ -190,6 +197,34 @@ pages:
     It also supports using <strong>HTML</strong>!
 ```
 
+## Metrics
+
+Metrics can be enabled with the `enableMetrics` configuration key and are served on a dedicated HTTP server. By default they are served on `http://localhost:1515/metrics`. Use this address to configure your tool of choice (e.g. [Prometheus](https://prometheus.io/)) to scrape the exported metrics.
+
+Besides the default metrics provided by the [Prometheus instrumentation library for Go applications ](https://github.com/prometheus/client_golang), the following additional metrics are provided:
+
+```plain
+# HELP portkey_page_handler_requests_total Total number of HTTP requests by page.
+# TYPE portkey_page_handler_requests_total counter
+portkey_page_handler_requests_total{path="<page_path>"} 0
+
+# HELP portkey_portal_handler_requests_total Total number of HTTP requests by portal.
+# TYPE portkey_portal_handler_requests_total counter
+portkey_portal_handler_requests_total{portal="<portal_title>"} 0
+
+# HELP portkey_search_requests_no_results_total Total number of HTTP requests for search with no results.
+# TYPE portkey_search_requests_no_results_total counter
+portkey_search_requests_no_results_total 0
+
+# HELP portkey_search_requests_with_results_total Total number of HTTP requests for search with at least one result.
+# TYPE portkey_search_requests_with_results_total counter
+portkey_search_requests_with_results_total 0
+
+# HELP portkey_version_info Version information about portkey.
+# TYPE portkey_version_info gauge
+portkey_version_info{buildTime="2024.10.09_17:29:19",commitHash="4fd1a0f",goVersion="1.23.1",version="dev"} 1
+```
+
 ## Docker
 
 There are also Docker images available at Docker hub that you can use. You can start a container for instance with:

config.yml

@@ -1,6 +1,9 @@
 host: localhost
 port: 3000
 contextPath: ""
+enableMetrics: true
+metricsHost: localhost
+metricsPort: 3030
 title: "portkey"
 hideTitle: false
 headerAddition: |-
@@ -49,10 +52,6 @@ portals:
   emoji: 🔢
   link: /version
   external: false
-- title: home
-  emoji: 🏠
-  link: /
-  external: false
 pages:
 - heading: "About"
   path: /about

fly.toml

@@ -8,14 +8,19 @@ primary_region = 'ams'
 
 [env]
   HOST = '0.0.0.0'
+  METRICSHOST = '0.0.0.0'
 
 [http_service]
   internal_port = 3000
   force_https = true
-  auto_stop_machines = true
+  auto_stop_machines = "stop"
   auto_start_machines = true
   min_machines_running = 0
   processes = ['app']
 
+[metrics]
+  port = 3030
+  path = "/metrics"
+
 [[vm]]
   size = 'shared-cpu-1x'

go.mod

@@ -5,15 +5,23 @@ go 1.23
 require (
 	github.com/a-h/templ v0.2.778
 	github.com/adrg/strutil v0.3.1
+	github.com/prometheus/client_golang v1.20.4
 	github.com/spf13/viper v1.19.0
 )
 
 require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
+	github.com/klauspost/compress v1.17.9 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.3 // indirect
+	github.com/prometheus/client_model v0.6.1 // indirect
+	github.com/prometheus/common v0.55.0 // indirect
+	github.com/prometheus/procfs v0.15.1 // indirect
 	github.com/sagikazarmark/locafero v0.6.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
@@ -25,6 +33,7 @@ require (
 	golang.org/x/exp v0.0.0-20240904232852-e7e105dedf7e // indirect
 	golang.org/x/sys v0.25.0 // indirect
 	golang.org/x/text v0.18.0 // indirect
+	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -2,6 +2,10 @@ github.com/a-h/templ v0.2.778 h1:VzhOuvWECrwOec4790lcLlZpP4Iptt5Q4K9aFxQmtaM=
 github.com/a-h/templ v0.2.778/go.mod h1:lq48JXoUvuQrU0VThrK31yFwdRjTCnIE5bcPCM9IP1w=
 github.com/adrg/strutil v0.3.1 h1:OLvSS7CSJO8lBii4YmBt8jiK9QOtB9CzCzwl4Ic/Fz4=
 github.com/adrg/strutil v0.3.1/go.mod h1:8h90y18QLrs11IBffcGX3NW/GFBXCMcNg4M7H6MspPA=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
@@ -14,21 +18,35 @@ github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
+github.com/klauspost/compress v1.17.9 h1:6KIumPrER1LHsvBVuDa0r5xaG0Es51mhhB9BQB2qeMA=
+github.com/klauspost/compress v1.17.9/go.mod h1:Di0epgTjJY877eYKx5yC51cX2A2Vl2ibi7bDH9ttBbw=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/pelletier/go-toml/v2 v2.2.3 h1:YmeHyLY8mFWbdkNWwpr+qIL2bEqT0o95WSdkNHvL12M=
 github.com/pelletier/go-toml/v2 v2.2.3/go.mod h1:MfCQTFTvCcUyyvvwm1+G6H/jORL20Xlb6rzQu9GuUkc=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/prometheus/client_golang v1.20.4 h1:Tgh3Yr67PaOv/uTqloMsCEdeuFTatm5zIq5+qNN23vI=
+github.com/prometheus/client_golang v1.20.4/go.mod h1:PIEt8X02hGcP8JWbeHyeZ53Y/jReSnHgO035n//V5WE=
+github.com/prometheus/client_model v0.6.1 h1:ZKSh/rekM+n3CeS952MLRAdFwIKqeY8b62p8ais2e9E=
+github.com/prometheus/client_model v0.6.1/go.mod h1:OrxVMOVHjw3lKMa8+x6HeMGkHMQyHDk9E3jmP2AmGiY=
+github.com/prometheus/common v0.55.0 h1:KEi6DK7lXW/m7Ig5i47x0vRzuBsHuvJdi5ee6Y3G1dc=
+github.com/prometheus/common v0.55.0/go.mod h1:2SECS4xJG1kd8XF9IcM1gMX6510RAEL65zxzNImwdc8=
+github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0learggepc=
+github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
 github.com/sagikazarmark/locafero v0.6.0 h1:ON7AQg37yzcRPU69mt7gwhFEBwxI6P9T4Qu3N51bwOk=
 github.com/sagikazarmark/locafero v0.6.0/go.mod h1:77OmuIc6VTraTXKXIs/uvUxKGUXjE1GbemJYHqdNjX0=
 github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
@@ -61,9 +79,11 @@ golang.org/x/sys v0.25.0 h1:r+8e+loiHxRqhXVl6ML1nO3l1+oFoWbnlu2Ehimmi34=
 golang.org/x/sys v0.25.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.18.0 h1:XvMDiNzPAl0jr17s6W9lcaIhGUfUORdGCNsuLmPG224=
 golang.org/x/text v0.18.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
+google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
+google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
 gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/components/portal.templ

@@ -33,7 +33,7 @@ templ HomePortal(portal models.Portal) {
 				target="_blank"
 				rel="nofollow"
 			}
-			href={ templ.SafeURL(portal.Link) }
+			href={ templ.SafeURL("/" + portal.TitleForUrl()) }
 			class="mx-4 whitespace-nowrap no-underline border-b-2 border-solid border-slate-700 dark:border-slate-300 hover:text-slate-800 dark:hover:text-slate-300"
 		>{ portal.Title }</a>
 	</span>
@@ -49,7 +49,7 @@ templ FooterPortal(portal models.Portal) {
 				target="_blank"
 				rel="nofollow"
 			}
-			href={ templ.SafeURL(portal.Link) }
+			href={ templ.SafeURL("/" + portal.TitleForUrl()) }
 			class="ml-1 no-underline border-b-2 border-solid border-slate-700 dark:border-slate-300 hover:text-slate-800 dark:hover:text-slate-300"
 		>{ portal.Title }</a>
 	</span>

internal/config/config.go

@@ -20,6 +20,9 @@ type Config struct {
 	Host                       string
 	Port                       string
 	ContextPath                string
+	EnableMetrics              bool
+	MetricsHost                string
+	MetricsPort                string
 	Title                      string
 	HideTitle                  bool
 	Footer                     string
@@ -70,6 +73,8 @@ func loadConfig(configPath string) {
 	viper.SetDefault("host", "localhost")
 	viper.SetDefault("port", "1414")
 	viper.SetDefault("contextPath", "")
+	viper.SetDefault("metricsHost", "localhost")
+	viper.SetDefault("metricsPort", "1515")
 	viper.SetDefault("title", "Your Portal")
 	viper.SetDefault("footerText", "Works like a portal.")
 	viper.SetDefault("minimumStringSimilarity", 0.75)

internal/metrics/metrics.go

@@ -0,0 +1,63 @@
+package metrics
+
+import (
+	"github.com/kodehat/portkey/internal/build"
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+const NAMESPACE = "portkey"
+
+type Metrics struct {
+	PortalHitCounter         *prometheus.CounterVec
+	PageHitCounter           *prometheus.CounterVec
+	SearchWithResultsCounter prometheus.Counter
+	SearchNoResultsCounter   prometheus.Counter
+	buildInfo                prometheus.Gauge
+}
+
+var M Metrics
+
+func Load() {
+	M = Metrics{
+		PortalHitCounter: prometheus.NewCounterVec(prometheus.CounterOpts{
+			Namespace: NAMESPACE,
+			Name:      "portal_handler_requests_total",
+			Help:      "Total number of HTTP requests by portal.",
+		}, []string{"portal"}),
+		PageHitCounter: prometheus.NewCounterVec(prometheus.CounterOpts{
+			Namespace: NAMESPACE,
+			Name:      "page_handler_requests_total",
+			Help:      "Total number of HTTP requests by page.",
+		}, []string{"path"}),
+		SearchWithResultsCounter: prometheus.NewCounter(prometheus.CounterOpts{
+			Namespace: NAMESPACE,
+			Name:      "search_requests_with_results_total",
+			Help:      "Total number of HTTP requests for search with at least one result.",
+		}),
+		SearchNoResultsCounter: prometheus.NewCounter(prometheus.CounterOpts{
+			Namespace: NAMESPACE,
+			Name:      "search_requests_no_results_total",
+			Help:      "Total number of HTTP requests for search with no results.",
+		}),
+		buildInfo: prometheus.NewGauge(prometheus.GaugeOpts{
+			Namespace: NAMESPACE,
+			Name:      "version_info",
+			Help:      "Version information about portkey.",
+			ConstLabels: prometheus.Labels{
+				"buildTime":  build.B.BuildTime,
+				"commitHash": build.B.CommitHash,
+				"version":    build.B.Version,
+				"goVersion":  build.B.GoVersion,
+			},
+		}),
+	}
+
+	// Set build info gauge to "1" so it can be used in queries.
+	M.buildInfo.Set(1.0)
+
+	prometheus.MustRegister(M.PortalHitCounter)
+	prometheus.MustRegister(M.PageHitCounter)
+	prometheus.MustRegister(M.SearchWithResultsCounter)
+	prometheus.MustRegister(M.SearchNoResultsCounter)
+	prometheus.MustRegister(M.buildInfo)
+}

internal/models/models.go

@@ -1,5 +1,7 @@
 package models
 
+import "regexp"
+
 // Portal struct containing information about a portal.
 // This is used later as a link destination shown to the user.
 type Portal struct {
@@ -21,6 +23,13 @@ type Portal struct {
 	Keywords []string `json:"keywords"`
 }
 
+var /* const */ alphaNumDashOnlyRegex = regexp.MustCompile("[^a-zA-Z0-9-]")
+
+// TitleForUrl returns the portal's title with alpha-numerical (and dash) characters only.
+func (portal Portal) TitleForUrl() string {
+	return alphaNumDashOnlyRegex.ReplaceAllString(portal.Title, "")
+}
+
 // Page struct defines a custom page that consists of a heading, content and a path,
 // where the page will be available at.
 type Page struct {

internal/server/metrics_handler.go

@@ -0,0 +1,11 @@
+package server
+
+import (
+	"net/http"
+
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+func metricsHandler() http.HandlerFunc {
+	return promhttp.Handler().ServeHTTP
+}

internal/server/page_handler.go

@@ -7,6 +7,8 @@ import (
 	"github.com/kodehat/portkey/internal/build"
 	"github.com/kodehat/portkey/internal/components"
 	"github.com/kodehat/portkey/internal/config"
+	"github.com/kodehat/portkey/internal/metrics"
+	"github.com/kodehat/portkey/internal/models"
 )
 
 type pageHandlerInfo struct {
@@ -17,10 +19,23 @@ type pageHandlerInfo struct {
 func pageHandler() []pageHandlerInfo {
 	var pageHandlerInfos = make([]pageHandlerInfo, len(config.C.Pages))
 	for i, page := range config.C.Pages {
+		if config.C.EnableMetrics {
+			// Required to initialize all portal metrics to "0".
+			metrics.M.PageHitCounter.WithLabelValues(page.Path).Add(0)
+		}
 		pageHandlerInfos[i] = pageHandlerInfo{
 			pagePath:    page.Path,
-			handlerFunc: templ.Handler(components.ContentLayout(page.Heading, config.C, build.B, components.ContentPage(page.Content))).ServeHTTP,
+			handlerFunc: pageMetricsHandler(page, templ.Handler(components.ContentLayout(page.Heading, config.C, build.B, components.ContentPage(page.Content)))).ServeHTTP,
 		}
 	}
 	return pageHandlerInfos
 }
+
+func pageMetricsHandler(p models.Page, h http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if config.C.EnableMetrics {
+			metrics.M.PageHitCounter.WithLabelValues(p.Path).Inc()
+		}
+		h.ServeHTTP(w, r)
+	})
+}