Generate an Access Monitoring event reference

.github/workflows/lint.yaml

@@ -272,6 +272,11 @@ jobs:
         # The protoc-gen-terraform version must match the version in integrations/terraform/Makefile
         run: git config --global --add safe.directory $(realpath .) && go install github.com/gravitational/protoc-gen-terraform/v3@v3.0.2 && make terraform-resources-up-to-date
 
+      - name: Check if the Access Monitoring reference is up to date
+        # We have to add the current directory as a safe directory or else git commands will not work as expected.
+        # The protoc-gen-terraform version must match the version in integrations/terraform/Makefile
+        run: git config --global --add safe.directory $(realpath .) && make access-monitoring-reference-up-to-date
+
   lint-rfd:
     name: Lint (RFD)
     needs: changes

Makefile

@@ -2013,6 +2013,17 @@ audit-event-reference-up-to-date: must-start-clean/host audit-event-reference
 		exit 1; \
 	fi
 
+.PHONY: access-monitoring-reference
+access-monitoring-reference:
+	cd ./build.assets/tooling/cmd/gen-athena-docs && go run main.go > ../../../../docs/pages/includes/access-monitoring-events.mdx
+
+.PHONY: access-monitoring-reference-up-to-date
+access-monitoring-reference-up-to-date: access-monitoring-reference
+	@if ! git diff --quiet; then \
+		./build.assets/please-run.sh "Access Monitoring event reference docs" "make access-monitoring-reference"; \
+		exit 1; \
+	fi
+
 .PHONY: gen-docs
 gen-docs:
 	$(MAKE) -C integrations/terraform docs

build.assets/tooling/cmd/gen-athena-docs/main.go

@@ -0,0 +1,86 @@
+// Teleport
+// Copyright (C) 2025 Gravitational, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package main
+
+import (
+	_ "embed"
+	"fmt"
+	"os"
+	"regexp"
+	"slices"
+	"strings"
+	"text/template"
+	"unicode"
+	"unicode/utf8"
+
+	"github.com/gravitational/teleport/gen/go/eventschema"
+)
+
+// colNameList prints an example of columns from a given Access Monitoring event
+// view to include an example command. It only prints up to the first three
+// columns.
+func colNameList(cols []*eventschema.ColumnSchemaDetails) string {
+	var sb strings.Builder
+	for i := range min(3, len(cols)) {
+		if i != 0 {
+			sb.WriteString(",")
+		}
+		sb.WriteString(cols[i].NameSQL())
+	}
+	return sb.String()
+}
+
+var descPredicate = regexp.MustCompile(`^(is|are) `)
+
+// prepareDescription returns a description of the column data provided in col.
+func prepareDescription(col *eventschema.ColumnSchemaDetails) string {
+	// Remove the initial verb, since there is no subject in the sentence.
+	desc := descPredicate.ReplaceAllString(col.Description, "")
+
+	// Capitalize the first word in the description.
+	if r, size := utf8.DecodeRuneInString(desc); r != utf8.RuneError {
+		desc = string(unicode.ToUpper(r)) + desc[size:]
+	}
+
+	return desc
+}
+
+// docTempl is the template that represents an Access Monitoring event reference
+// docs page. The assumption is that "@" characters are replaced with backticks
+// before rendering the template.
+//
+//go:embed schema-reference.mdx.tmpl
+var docTempl string
+
+func main() {
+	data, err := eventschema.GetViewsDetails()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Cannot generate an Access Monitoring schema reference: %v\n", err)
+		os.Exit(1)
+	}
+
+	slices.SortFunc(data, func(a, b *eventschema.TableSchemaDetails) int {
+		return strings.Compare(a.Name, b.Name)
+	})
+
+	template.Must(template.New("event-reference").Funcs(
+		template.FuncMap{
+			"ColNameList":        colNameList,
+			"PrepareDescription": prepareDescription,
+		},
+	).Parse(docTempl)).Execute(os.Stdout, data)
+}

build.assets/tooling/cmd/gen-athena-docs/schema-reference.mdx.tmpl

@@ -0,0 +1,28 @@
+{/*generated file. DO NOT EDIT.*/}
+{/*To generate, run make access-monitoring-reference*/}
+{/*vale messaging.capitalization = NO*/}
+{/*vale messaging.consistent-terms = NO*/}
+
+{{ range . -}}
+## {{ .Name }}
+
+`{{ .Name }}` {{ .Description }}.
+
+Example query:
+
+```code
+$ tctl audit query exec \
+  'select {{ ColNameList .Columns }} from {{ .SQLViewName }} limit 1'
+```
+
+Columns:
+
+|SQL Name|Type|Description|
+|---|---|---|
+{{- range .Columns }}
+|{{ .NameSQL }}|{{ .Type }}|{{ PrepareDescription . }}|
+{{- end }}
+
+{{ end }}
+{/*vale messaging.capitalization = YES*/}
+{/*vale messaging.consistent-terms = YES*/}