Update instructions generally for Grafana/prometheus setups

doc/user/content/manage/monitor/self-managed/datadog.md

@@ -36,7 +36,7 @@ which has been tried and tested in production environments.
 
    {{< tip >}}
    You can use [this sample
-   `config.yml.example`](https://github.com/MaterializeIncLabs/materialize-monitoring/blob/main/sql_exporter/config.yml)
+   `config.yml.example`](https://github.com/MaterializeInc/materialize-monitoring/blob/main/legacy/sql_exporter/config.yml)
    as guidance to bootstrap your monitoring with some key Materialize metrics
    and indicators.
    {{</ tip >}}

doc/user/content/manage/monitor/self-managed/prometheus.md

@@ -15,13 +15,19 @@ The metrics scraped are unstable and may change across releases.
 This guide walks you through the steps required to monitor the performance and
 overall health of your Materialize instance using Prometheus and Grafana.
 
+{{< important >}}
+Every monitoring setup is unique, so be sure to adopt the steps in this guide to your specific environment and requirements.
+{{< /important >}}
+
 ## Before you begin
 
 Ensure you have:
 
-- A self-managed instance of Materialize installed with helm values `observability.enabled=true`, `observability.podMetrics.enabled=true`, and `prometheus.scrapeAnnotations.enabled=true`
+- A self-managed instance of Materialize installed with [helm values](/self-managed-deployments/operator-configuration/) `observability.enabled=true`, `observability.podMetrics.enabled=true`, and `prometheus.scrapeAnnotations.enabled=true`
 - [Helm](https://helm.sh/docs/intro/install/) version 3.2.0+ installed
 - [kubectl](https://kubernetes.io/docs/tasks/tools/) installed and configured
+- [metrics-server](https://github.com/kubernetes-sigs/metrics-server) installed in your cluster
+- [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics) installed in your cluster
 
 {{< important >}}
 This guide assumes you have administrative access to your Kubernetes cluster and the necessary permissions to install Prometheus.
@@ -31,14 +37,19 @@ This guide assumes you have administrative access to your Kubernetes cluster and
   Download the Prometheus scrape configurations that we'll use to configure Prometheus to collect metrics from Materialize:
   {{% self-managed/step-download-prometheus-scrape-configs %}}
 
-
+{{< note >}}
+If you are using prometheus-operator or do not know your prometheus distribution, visit [materialize-monitoring/Scraping](https://materializeinc.github.io/materialize-monitoring/metrics/scraping/) for additional scraping configurations.
+{{< /note >}}
 
 ## 2. Install Prometheus to your Kubernetes cluster
 
-  {{< note >}}
-  This guide uses the [prometheus-community](https://github.com/prometheus-community/helm-charts) Helm chart to install Prometheus.
-  {{< /note >}}
+{{< note >}}
+This guide uses the [prometheus-community](https://github.com/prometheus-community/helm-charts) Helm chart to install Prometheus.
 
+Many more production-ready Prometheus Helm charts are available
+which have different ways to configure Prometheus and its scrape configurations.
+Be sure to consult the documentation of the Prometheus Helm chart you are using to ensure that you are configuring Prometheus correctly.
+{{< /note >}}
 
 1. Download the prometheus-community default chart values (`values.yaml`):
    ```bash
@@ -47,7 +58,7 @@ This guide assumes you have administrative access to your Kubernetes cluster and
 
 2. Within `values.yaml`, replace `serverFiles > prometheus.yml > scrape_configs` with our scrape configurations (`prometheus_scrape_configs.yml`).
 
-3. Install the operator with the updated `values.yaml`:
+3. Install the helm chart with the updated `values.yaml`:
    ```bash
    kubectl create namespace prometheus
    helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
@@ -63,8 +74,7 @@ This guide assumes you have administrative access to your Kubernetes cluster and
 
 2.  Set up port forwarding to access the Grafana UI:
     ```bash
-    MZ_POD_GRAFANA=$(kubectl get pods -n monitoring -l app.kubernetes.io/name=grafana -o custom-columns="NAME:.metadata.name" --no-headers)
-    kubectl port-forward pod/$MZ_POD_GRAFANA 3000:3000 -n monitoring
+    kubectl port-forward svc/grafana 3000:80 -n monitoring
     ```
 
     {{< warning >}}
@@ -75,25 +85,12 @@ This guide assumes you have administrative access to your Kubernetes cluster and
 
 4. Add a Prometheus data source. In the Grafana UI, under **Connection > Data sources**,
    - Click **Add data source** and select **prometheus**
-   - In the Connection section, set **Prometheus server URL** to `http://<prometheus server name>.<namespace>.svc.cluster.local:<port>`(e.g. `http://prometheus-server.prometheus.svc.cluster.local:80`).
+   - In the Connection section, set **Prometheus server URL** to `http://<prometheus server name>.<namespace>.svc:<port>`(e.g. `http://prometheus-server.prometheus.svc:80`).
 
-    ![Image of Materialize Console login screen with mz_system user](/images/self-managed/grafana-prometheus-datasource-setup.png)
+    ![Image of Grafana datasource setup](/images/self-managed/grafana-prometheus-datasource-setup.png)
 
-4. Download the following dashboards:
-    ### Environment overview dashboard
-    An overview of the state of different objects in your environment.
-
-    ```bash
-    # environment_overview_dashboard.json
-    curl -O https://raw.githubusercontent.com/MaterializeInc/materialize/refs/heads/self-managed-docs/v25.2/doc/user/data/monitoring/grafana_dashboards/environment_overview_dashboard.json
-    ```
-    ### Freshness overview dashboard
-    An overview of how out of date objects in your environment are.
-     ```bash
-     # freshness_overview_dashboard.json
-    curl -O https://raw.githubusercontent.com/MaterializeInc/materialize/refs/heads/self-managed-docs/v25.2/doc/user/data/monitoring/grafana_dashboards/freshness_overview_dashboard.json
-    ```
+4. Download dashboards from our [Grafana dashboards repository](https://materializeinc.github.io/materialize-monitoring/dashboards/grafana/)
 
 5. [Import the dashboards using the Prometheus data source](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/#importing-a-dashboard)
 
-    ![Image of Materialize Console login screen with mz_system user](/images/self-managed/grafana-monitoring-success.png)
+    ![Image of Grafana](/images/self-managed/grafana-monitoring-success.png)

doc/user/layouts/shortcodes/self-managed/step-download-prometheus-scrape-configs.html

@@ -1,3 +1,3 @@
 ```shell
-curl -o prometheus_scrape_configs.yml https://raw.githubusercontent.com/MaterializeInc/materialize/refs/heads/main/doc/user/data/self_managed/monitoring/prometheus.yml
+curl -o prometheus_scrape_configs.yml https://materializeinc.github.io/materialize-monitoring/prometheus-scrapers/classic/scrape_config.yaml
 ```